EctoLedger

> **Your AI agent made 47 decisions. Can you prove what it did? To a regulator? To a court?**
>
> **EctoLedger makes that proof automatic.**

# EctoLedger

[![CI](https://github.com/EctoSpace/EctoLedger/actions/workflows/ci.yml/badge.svg)](https://github.com/EctoSpace/EctoLedger/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.6.3-orange.svg)](Cargo.toml)
[![Rust](https://img.shields.io/badge/rust-1.94%2B%20%7C%20edition%202024-orange.svg)](https://www.rust-lang.org)
[![GitHub issues](https://img.shields.io/github/issues/EctoSpace/EctoLedger.svg)](https://github.com/EctoSpace/EctoLedger/issues)
[![Last commit](https://img.shields.io/github/last-commit/EctoSpace/EctoLedger.svg)](https://github.com/EctoSpace/EctoLedger/commits/main)


<p align="center">
  <img src="assets/ectoLedger-Logo.webp" alt="EctoLedger Logo" width="250" />
</p>

<p align="center">
  <strong>Cryptographically verified AI agent execution - tamper-evident, policy-enforced, compliance-ready.</strong>
</p>

<p align="center">
  <a href="docs/quickstart.md">Quickstart</a> •
  <a href="#what-ectoledger-is-and-is-not">What It Is</a> •
  <a href="#common-use-cases">Use Cases</a> •
  <a href="#choose-your-starting-mode">Choose Mode</a> •
  <a href="#prerequisites">Prerequisites</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#management-gui">Management GUI</a> •
  <a href="#sdks">SDKs</a> •
  <a href="#cli-reference">CLI Reference</a> •
  <a href="#configuration-reference">Configuration</a> •
  <a href="#decentralized-identity-and-w3c-verifiable-credentials">Verifiable Credentials</a> •
  <a href="#compliance-iso-420012023">Compliance</a> •
  <a href="#project-layout">Project Layout</a>
</p>

---

## What is EctoLedger?

**EctoLedger is the dashcam + emergency brake for autonomous AI agents.**

Your AI agent just made 47 decisions.  
Can you prove exactly what it did — to a regulator, an auditor, or a court?  
EctoLedger makes that proof automatic… while physically blocking dangerous actions before they happen.

### What EctoLedger is (and is not)

**What it is**
- A **security proxy** in front of autonomous AI actions.
- A **prevention layer** that can block unsafe commands before execution.
- A **cryptographic evidence layer** that produces tamper-evident audit trails and verifiable certificates.
- An **optional isolation layer** with sandbox tiers (including Firecracker on Linux and Apple Hypervisor guard isolation on supported Apple Silicon builds).

**What it is not**
- Not a crypto trading product.
- Not a replacement for SIEM, ticketing, or full GRC suites.
- Not a legal guarantee by itself; it provides verifiable evidence to support legal/compliance processes.

### Features by platform

| Feature                                    | Linux                      | macOS         | Windows       |
|-------------------------------------------|----------------------------|---------------|---------------|
| Firecracker microVM isolation (optional)   | Yes (when configured)      | Not available | Not available |
| OS-level sandbox (Landlock/Seatbelt/Jobs)  | Yes                        | Yes           | Yes           |
| Real-time GUI dashboard                   | Yes                        | Yes           | Yes           |
| .elc certificate export                  | Yes                        | Yes           | Yes           |
| 4-layer guardrails + tripwire             | Yes                        | Yes           | Yes           |

### Two core capabilities

**1. Constant monitoring + prevention (the emergency brake)**  
Real-time desktop GUI dashboard shows every thought and action live.  
4-layer guardrails (policy engine → dual-LLM checker → schema validation → tripwire) stop risky API calls, data leaks, or unauthorized transactions *before* they execute.

**2. State-of-the-art cryptographic audit (the tamper-proof flight recorder)**  
Every decision is signed, hash-chained, and stored in an immutable ledger.  
Export self-contained `.elc` certificates that any regulator or court can verify offline — no trust in you required.

### Who this is for?
- Teams running AI agents that call APIs, run commands, or touch sensitive data  
- Security & platform engineers who need enforceable guardrails  
- Compliance officers preparing for the EU AI Act (2026) and other AI governance rules  
- Anyone who never wants to say “the AI did it” in front of a judge

### Common use cases

- **AI operations guardrail**: block risky LLM-proposed commands before they hit production systems.
- **Compliance evidence generation**: produce tamper-evident records for SOC 2, PCI-DSS, OWASP, ISO 42001, and internal audits.
- **Enterprise due diligence**: show customers and security teams independently verifiable proof of what the agent did.
- **Incident investigation**: replay what happened during an AI-assisted workflow with signed, hash-chained evidence.

### Choose your starting mode

| Mode | Best for | What you can do |
|---|---|---|
| **Demo (`--demo`)** | Fast product evaluation | Guided local experience with embedded components and seeded data |
| **SQLite (`DATABASE_URL=sqlite://...`)** | Local/dev/CI workflows | Serve dashboard, replay, report, certificate and VC verification |
| **PostgreSQL** | Production and advanced workflows | Full `audit`, `orchestrate`, `diff-audit`, `red-team`, `prove-audit`, `anchor-session` |

### Why now?
The EU AI Act becomes fully enforceable for high-risk AI systems in August 2026.  
Article 12 explicitly requires tamper-evident, automatically recorded logs that normal logging cannot provide.  
Every company deploying autonomous agents will need exactly this infrastructure.  
You built it before the market even knew it was required.

![EctoLedger demo](site/marketing_assets/videos/gui_demo.gif)

### How it works (technical)

EctoLedger gives every AI agent a cryptographically sealed audit trail. Each action is hash-chained, signature-verified, and policy-gated before execution. The result is an immutable ledger that regulators, auditors, and security teams can inspect, replay, and independently verify - with no trust in the issuer.

**Highlights of version 0.6.3:**

| Capability | What it provides |
|---|---|
| **Pluggable ledger backends** | Swap PostgreSQL for SQLite (dev/CI) — or any future store — through the `LedgerBackend` trait; [SQLite does not support](#sqlite-limitations) `audit`, `orchestrate`, `diff-audit`, `red-team`, `prove-audit`, or `anchor-session` |
| **Tauri 2 management GUI** | Glassmorphic desktop app: live dashboard, Prometheus metrics, session browser, policy editor, Tripwire config, settings, certificate export |
| **Python & TypeScript SDKs** | Typed REST clients; LangChain `LedgerTool` and AutoGen `LedgerHook` included |
| **Extended webhooks with HMAC signing** | GuardDenial and TripwireRejection events delivered to any SIEM in JSON, CEF, or LEEF; `X-EctoLedger-Signature: sha256=<hex>` header secures each delivery |
| **W3C Verifiable Credentials** | VC-JWT issued on session completion; Ed25519-signed, `did:key:` anchored; resolvable via `GET /api/sessions/{id}/vc/verify` |
| **ISO 42001:2023** | Machine-readable policy pack (14 controls) and compliance whitepaper |
| **4-layer semantic guard** | Policy engine → dual-LLM guard process → strict schema JSON validation → structural tripwire before every commit |
| **Hardware microVM sandbox (Linux only)** | Firecracker-based execution isolation for `run_command` intents; quick setup via `scripts/setup-firecracker.sh`; enterprise provisioning (custom prefix, `/opt/ectoledger` paths) via `scripts/provision-firecracker.sh` |
| **EVM chain anchoring** | Publish the ledger tip hash to any EVM-compatible chain via `anchor-session --chain ethereum`; built-in and enabled by default |
| **SP1 ZK proofs** | Provable policy compliance without ex

[truncated…]