Your AI agent made 47 decisions. Can you prove what it did? To a regulator? To a court?

EctoLedger makes that proof automatic.

Cryptographically verified AI agent execution - tamper-evident, policy-enforced, compliance-ready.

Quickstart • What It Is • Use Cases • Choose Mode • Prerequisites • Quick Start • Architecture • Management GUI • SDKs • CLI Reference • Configuration • Verifiable Credentials • Compliance • Project Layout

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 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.

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.

• 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

• 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.

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 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:

The agent is the database. The Rust process is a transient worker. All durable state - the event log and snapshots - lives in the configured ledger backend (PostgreSQL or SQLite). The process has no long-term memory; it restores state from the ledger on each run.

Verify then commit. Actions proposed by the LLM pass through a strict four-layer pipeline before they are committed or executed:

1. Ledger goal anchoring. The session goal is hashed at creation (goal_hash) and re-verified on every append_event. Events are SHA-256-chained: any insertion, deletion, or mutation anywhere in the chain is detectable on startup without replaying execution.

2. Guard process (dual-LLM). A secondary LLM (GUARD_LLM_BACKEND / GUARD_LLM_MODEL) runs in a separate process (guard-worker) communicating over stdin/stdout JSON. It evaluates each proposed intent against the stated goal and returns ALLOW or DENY: <reason>. Configure GUARD_REQUIRED=true in production.

3. Output content scanning (hybrid). Execution observations are scanned by two passes before being appended to the ledger:

   • Regex pass: NFKC normalization followed by tuned patterns - injection phrases, Unicode homoglyphs, zero-width characters, LLM template tags, embedded action JSON, data/javascript URIs, role-injection, base64-encoded blobs, and prompt continuation markers.
   • Strict schema pass: Every JSON object containing an "action" key is validated against the sealed StrictAgentOutput schema with #[serde(deny_unknown_fields)]. Any object that carries fields outside the four allowed keys (action, params, justification, reasoning) is immediately flagged as a strict_schema_violation - catching hijack insertions like override_goal or system_prompt that exploit structural overlap with valid agent outputs.
   • Structural JSON/AST pass: bracket-depth extraction plus serde_json parse of every {...} candidate, detecting action-shaped objects and goal-hijacking keys that regex alone would miss.
   • Base64 pass: decodes eyJ... base64 candidates and re-runs the structural check on the decoded payload.

Tripwire (structural rules):

• Paths - component-level .. rejection, normalization without canonicalize(), symlink-escape detection; only directories under the configured workspace are permitted.
• Networks - allowlisted domains only; HTTPS enforced by default (configurable).
• Commands - blocklist of dangerous shell constructs (sudo, rm -rf, etc.).
• Justification - every non-complete action requires a minimum length of justification (default 5 characters); empty or missing justifications are rejected immediately.

Tripwire rules (min justification length, require HTTPS, allowed paths/domains, banned command patterns) are configurable via the GUI Tripwire menu or ~/.ectoledger/tripwire.json. See the "Hardware microVM sandbox" and "Automatic signing-key rotation" sections below for additional environment-driven options.

Together these layers raise the bar for prompt injection without claiming unconditional immunity - no software defence is absolute. Intents that pass all checks are appended to the hash-chained ledger and executed; nothing is ever updated or deleted.

All configuration is loaded from environment variables (with optional .env file support via dotenvy). Values marked [required] have no sensible default and must be set for the described feature to be active.

The cognitive loop is a strict pipeline: Perceive → Propose → Verify → Commit → Execute.

flowchart LR Perceive[Perceive State] Propose[Propose Intent] Policy[Policy Engine] Guard[Guard Process] Tripwire[Tripwire] Commit[Commit to Ledger] Execute[Execute Side Effect] LLM[Primary LLM] DB[(Ledger Backend\nPostgres · SQLite)] Host[Host] Perceive -->|restore from backend| Propose Propose -->|LLM JSON| LLM LLM --> Propose Propose --> Policy Policy --> Guard Guard --> Tripwire Tripwire -->|allowed only| Commit Commit -->|hash-chain + Ed25519| DB Commit --> Execute Execute -->|run / read / http| Host Execute -->|observation scanned| DB 

1. Perceive - Restore agent state from the ledger (latest snapshot + replayed events).
2. Propose - Send state to the primary LLM; receive a single JSON intent (run_command, read_file, http_get, complete).
3. Verify - Policy engine (if --policy is set), then Guard process (separate binary), then Tripwire; reject or accept.
4. Commit - Verify goal hash, append the action to the ledger (hash-chained, Ed25519-signed), then run the side effect.
5. Execute - Run the command, read the file, or perform the HTTP GET; scan observation; append to the ledger. Loop until complete or max_steps is reached.

The LedgerBackend trait (crates/ledger-api) decouples the agent runtime from any specific storage engine. EctoLedger ships two production-ready implementations:

⚠️ Not all commands are available in SQLite mode. The following commands require PostgreSQL and will exit with an error if DATABASE_URL points to a SQLite file:

Unsupported command	Why PostgreSQL is required
audit	Full cognitive loop requires PG-backed session locking and migrations
orchestrate	Multi-agent coordination relies on PG advisory locks
diff-audit	Session diffing uses PG-specific window functions
red-team	Attack simulation requires full event streaming over PG
prove-audit	ZK proof generation reads from PG-only tables
anchor-session	On-chain anchoring reads the PG event schema

SQLite mode fully supports: serve, replay, verify-session, report, verify-certificate, and verify-vc.

Switch backends at runtime via DATABASE_URL:

# PostgreSQL (default) DATABASE_URL=postgres://ectoledger:ectoledger@localhost:5432/ectoledger cargo run -- serve # SQLite - zero infrastructure, zero configuration DATABASE_URL=sqlite://ledger.db cargo run -- serve

The LedgerBackend trait provides a minimal, cursor-style interface (simplified — see crates/ledger-api/src/lib.rs for the full production trait with signing keys, sequence ranges, and admin operations):

pub trait LedgerBackend: Send + Sync { async fn create_session(&self, new: NewSession) -> Result<(Session, Vec<u8>), LedgerError>; async fn append_event(&self, session_id: Uuid, payload: RawPayload, signing_key: &SigningKey, seq: i64) -> Result<AppendResult, LedgerError>; async fn seal_session(&self, session_id: Uuid) -> Result<(), LedgerError>; async fn get_events_by_session(&self, session_id: Uuid) -> Result<Vec<LedgerEvent>, LedgerError>; async fn list_sessions(&self, limit: i64) -> Result<Vec<Session>, LedgerError>; async fn verify_chain(&self, from: i64, to: i64) -> Result<bool, LedgerError>; async fn prove_compliance(&self, session_id: Uuid) -> Result<RawPayload, LedgerError>; }

Third parties can implement this trait to add custom backends (DynamoDB, FoundationDB, etc.) without modifying EctoLedger itself.

SQLite is a single-instance backend. Do not run multiple EctoLedger processes against the same SQLite file — use PostgreSQL for multi-instance deployments.

PostgreSQL supports horizontal scaling with the following caveats:

• SSE fanout uses PostgreSQL LISTEN/NOTIFY to wake subscribers across instances (see pg_notify module).
• Approval state can be persisted to the pending_approvals table for cross-instance visibility.
• Session ownership uses per-session advisory locks to prevent duplicate cognitive loops.

See docs/SCALING.md for the full horizontal-scaling guide.

• ECTO_FC_BINARY, ECTO_FC_KERNEL, ECTO_FC_ROOTFS – paths required to enable the Firecracker sandbox. Set at least ECTO_FC_BINARY to opt in; the agent will warn if the files are missing or on non-Linux platforms.
• ECTO_FC_VCPUS, ECTO_FC_MEM_MIB, ECTO_FC_TIMEOUT_SECS – optional tuning parameters for microVM size and execution timeout.
• AGENT_KEY_ROTATION_STEPS – positive integer number of cognitive-loop steps between automatic session signing-key rotations. If unset or zero, rotation is disabled. A KeyRotation ledger event is appended each time a new key is generated.

Two provisioning scripts are provided:

The scripts/setup-firecracker.sh script automates the entire Firecracker setup on any KVM-capable Linux host (x86_64 and aarch64). It downloads the Firecracker binary, a minimal Linux kernel image, and a compatible rootfs, then prints the exact environment variable exports needed:

# One-time setup (run as root for system-wide paths, or as a normal user for ~/.local) sudo bash scripts/setup-firecracker.sh # Export the variables printed by the script, then: cargo build --release --features sandbox-firecracker # Or with the pre-built Linux binary: ECTO_FC_BINARY=/usr/local/bin/firecracker \ ECTO_FC_KERNEL=/opt/ectoledger/vmlinux \ ECTO_FC_ROOTFS=/opt/ectoledger/rootfs.ext4 \ ./ectoledger-linux audit "<your goal>"

When running as a non-root user, assets are installed to ~/.local/bin and ~/.local/opt/ectoledger without requiring sudo. The script validates architecture, checks for KVM availability, verifies binary checksums, and prints a ready-to-source export block on completion.

EctoLedger is self-deploying - no manual database creation, migration tools, or configuration files required.

PostgreSQL mode (default): if DATABASE_URL is unset, the binary defaults to postgres://ectoledger:ectoledger@localhost:5432/ectoledger. It checks for a Docker container named ectoledger-postgres, starts one if absent, polls until ready, then runs migrations and creates the genesis block automatically.

SQLite mode: set DATABASE_URL=sqlite://ledger.db. No Docker, no external process, no migration tool. The database file is created on first run.

If OBSERVER_TOKEN is unset, a random token is generated and printed at startup with the dashboard URL - use it as ?token=… or in the Authorization header.

macOS:

git clone https://github.com/EctoSpace/EctoLedger.git cd EctoLedger ./ectoledger-mac

Linux:

git clone https://github.com/EctoSpace/EctoLedger.git cd EctoLedger ./ectoledger-linux

Windows (PowerShell):

git clone https://github.com/EctoSpace/EctoLedger.git cd EctoLedger .\ectoledger-win.ps1

That's it. The launcher script:

1. Checks prerequisites (cargo, node, npm; warns if Ollama isn't running)
2. Creates a .env with safe dev defaults on first run
3. Builds the Rust binary (skipped on subsequent runs - fast restart)
4. Installs npm packages for the GUI (gui/node_modules)
5. Starts the backend server on http://127.0.0.1:3000
6. Opens the Tauri desktop GUI with hot-reload

Press Ctrl+C to stop everything cleanly.

Want to see EctoLedger in action without configuring databases or API keys? Run the launcher with the --demo flag:

# macOS ./ectoledger-mac --demo # Linux ./ectoledger-linux --demo # Windows (PowerShell) .\ectoledger-win.ps1 -demo

What happens? The launcher starts an isolated embedded PostgreSQL instance on a separate port, auto-detects your LLM, and sets ECTO_DEMO_MODE=true so the backend uses a completely separate database from your normal data. Read the full Demo Architecture Guide for details.

LLM selection (automatic, in priority order):

Data isolation: Demo PostgreSQL runs on port 5433 with database ectoledger_demo, stored separately from your normal data (~/.local/share/ectoledger/postgres-demo on Linux, ~/Library/Application Support/ectoledger/postgres-demo on macOS). Use --reset-db --demo together to wipe it.

First run only: pg-embed Postgres binaries download once (~30 MB). If using Ollama, qwen2.5:0.5b downloads once (~500 MB). Subsequent demo starts take seconds.

No Rust toolchain, no Node.js, no Ollama — just Docker. One command pulls a pre-built image from GitHub Container Registry and starts the full backend stack:

docker compose -f docker-compose.demo.yml up

Then open http://localhost:3000 in your browser.

To stop and remove all data:

docker compose -f docker-compose.demo.yml down -v

Build from source (optional — only if you want to test local code changes):

docker compose -f docker-compose.demo.yml -f docker-compose.build.yml up --build

The Docker demo exposes only the REST API and Observer dashboard — there is no Tauri desktop GUI. Use the --demo flag with the native launcher (above) for the full desktop experience.

Use this path when you need strong guardrails and verifiable evidence (not just a demo run):

1. Use PostgreSQL backend (DATABASE_URL=postgres://...) for full command support.
2. Configure guard settings and keep GUARD_REQUIRED=true.
3. Run:

cargo run -- audit "Audit production deployment configuration" \ --policy crates/host/policies/iso42001.toml

4. Export and verify evidence:

cargo run -- report <session_id> --format certificate --output audit.elc ./target/release/verify-cert audit.elc

5. Optional: anchor the session hash for timestamp non-repudiation.

cargo run -- anchor-session <session_id>

• Confirm backend mode: SQLite does not support audit, orchestrate, red-team, diff-audit, prove-audit, or anchor-session.
• Verify LLM connectivity and API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, or Ollama availability).
• If running production settings, check guard variables (GUARD_REQUIRED, GUARD_LLM_BACKEND, GUARD_LLM_MODEL).

• Demo mode is tuned for fast evaluation and isolated data; production requires explicit guard/policy/backend configuration.
• Re-check .env and backend selection before comparing results.
• Validate policy and tripwire settings from the GUI or config files.

• verify-session validates signed event chain integrity for a session.
• verify-certificate / verify-cert validates exported .elc artifacts offline.
• VC verify endpoints perform structural/expiry checks; for full signature assurances use the documented cryptographic verification API path.

Shorthand via make (macOS/Linux):

Customise your setup - edit .env (created automatically on first launch):

# Use OpenAI instead of Ollama LLM_BACKEND=openai OPENAI_API_KEY=sk-... # Enable production guard GUARD_REQUIRED=true GUARD_LLM_BACKEND=ollama GUARD_LLM_MODEL=llama3 # Enable SIEM webhook egress WEBHOOK_URL=https://your-siem.example.com/events

gui/ contains a Tauri 2 + Svelte 5 desktop application - a native binary for macOS, Windows, and Linux that communicates with the local Axum server over HTTP.

Design: Apple-glass glassmorphism - frosted translucent panels, backdrop-filter: blur, vibrant purple accents on a deep dark gradient background. On macOS, vibrancy: "under-window" is used for native frosted glass.

Screens:

The GUI solves a common operational pain point: the Observer dashboard is embedded inside the application and never closes or requires a browser.

# Development (hot-reload, requires backend running) cd gui && npm install && npm run tauri dev # Production bundle cd gui && npm run tauri build # Installer at: target/release/bundle/ (the workspace root, not inside gui)

cd gui npm install npm run tauri build

# Core client only pip install ectoledger-sdk # With LangChain support pip install 'ectoledger-sdk[langchain]' # With AutoGen support pip install 'ectoledger-sdk[autogen]'

import asyncio from ectoledger_sdk import LedgerClient async def main(): async with LedgerClient("http://localhost:3000") as client: session = await client.create_session(goal="Audit Cargo.toml dependencies") await client.append_event(session.session_id, {"step": "read", "file": "Cargo.toml"}) ok = await client.verify_chain(session.session_id) print("Chain intact:", ok) await client.seal_session(session.session_id) asyncio.run(main())

LangChain integration - appends every agent reasoning step to the ledger:

from ectoledger_sdk.langchain import LedgerTool ledger_tool = LedgerTool( session_id="<uuid>", base_url="http://localhost:3000", ) agent_executor = AgentExecutor(agent=agent, tools=[search_tool, ledger_tool])

AutoGen integration - hooks into reply processing on any ConversableAgent:

from ectoledger_sdk.autogen import LedgerHook hook = LedgerHook(session_id="<uuid>") hook.attach(my_conversable_agent)

See sdk/python/README.md for the full API reference.

npm install ectoledger-sdk

import { EctoLedgerClient } from "ectoledger-sdk"; const client = new EctoLedgerClient({ baseUrl: "http://localhost:3000" }); const session = await client.createSession("Summarise quarterly report"); await client.appendEvent(session.id, { step: "retrieved_docs", count: 42 }); const ok = await client.verifyChain(session.id); await client.sealSession(session.id); // Export audit certificate as a Blob const cert = await client.exportCertificate(session.id);

Zero external dependencies — uses the native fetch API (Node 18+, browsers, Deno, Bun). Fully typed with TypeScript generics. Non-2xx responses throw EctoLedgerApiError with .status and .body properties.

See sdk/typescript/README.md for the full API reference.

cargo run -- serve # Observer: http://localhost:3000 (use printed token as ?token=… or Authorization header)

# Basic audit cargo run -- audit "Read server_config.txt" # With a compliance policy cargo run -- audit "Audit Cargo.toml dependencies" \ --policy crates/host/policies/soc2-audit.toml # SQLite backend - no infrastructure required DATABASE_URL=sqlite://ledger.db \ cargo run -- audit "Quick local audit" # Cloud credential injection AGENT_CLOUD_CREDS_FILE=~/.ectoledger/aws-audit.json \ cargo run -- audit "Audit S3 bucket policy for public exposure" \ --policy crates/host/policies/soc2-audit.toml # Interactive approval gates (stdin - no dashboard required) cargo run -- audit "Run nmap scan" --policy gate_policy.toml --interactive # Development only - disable guard (requires explicit confirmation flag) cargo run -- audit "Quick read" --no-guard --no-guard-confirmed

# Supported formats: json (default), sarif, html, certificate (.elc), # github_actions, gitlab_codequality cargo run -- report <session_id> --format sarif --output report.sarif cargo run -- report <session_id> --format html --output report.html cargo run -- report <session_id> --format certificate --output audit.elc cargo run -- report <session_id> --format github_actions cargo run -- report <session_id> --format gitlab_codequality --output codequality.json

Exits with code 1 when any finding is high or critical severity - suitable as a CI gate.

cargo run -- verify-session <session_id>

cargo run -- verify-certificate audit.elc # Standalone binary (no Rust, PostgreSQL, or Ollama required - ship to auditors) ./target/release/verify-cert audit.elc

cargo run -- replay <session_id> cargo run -- replay <session_id> --inject-observation "seq=3:injected content"

Useful for debugging and adversarial testing.

cargo run -- diff-audit \ --baseline <session_id> \ --current <session_id> \ [--output diff.json]

Runs three sequential sub-agents - Recon → Analysis → Verify - each in an independent ledger session. On completion, a CrossLedgerSeal event with a length-prefixed SHA-256 commitment is appended to every session, cryptographically binding them together without merging their event chains.

Security note: The cross-ledger seal hash uses length-prefixed encoding (len(tip) || tip) for each input to prevent boundary-collision attacks where sha256("AB" || "C") would equal sha256("A" || "BC") without prefixes.

cargo run -- orchestrate "Audit the Rust dependency tree for known vulnerabilities" cargo run -- orchestrate "Audit Nginx config" \ --policy shared_policy.toml --max-steps 25 # Per-role policy overrides via environment variables: ECTO_RECON_POLICY=/etc/ectoledger/strict-recon.toml \ ECTO_VERIFY_POLICY=/etc/ectoledger/strict-verify.toml \ cargo run -- orchestrate "Audit production Kubernetes configuration"

Policy resolution order (highest priority first):

1. Role-specific env var (ECTO_RECON_POLICY, ECTO_ANALYSIS_POLICY, ECTO_VERIFY_POLICY)
2. Shared --policy file (applies to all roles if role-specific var is not set)
3. Built-in hardcoded defaults

# Bitcoin via OpenTimestamps (default) cargo run -- anchor-session <session_id> # EVM chain (Ethereum, Polygon, or any EVM-compatible network) EVM_RPC_URL=https://mainnet.infura.io/v3/<key> \ EVM_CHAIN_ID=1 \ EVM_CONTRACT_ADDRESS=0x... \ EVM_PRIVATE_KEY=0x... \ cargo run -- anchor-session <session_id> --chain ethereum

Submits the ledger tip hash to the OTS aggregator pool (Bitcoin path) or calls anchor(bytes32) on the deployed EctoLedgerAnchor smart contract (EVM path). An Anchor event is appended to the session in both cases, embedding the proof and transaction hash for independent verification.

EVM anchoring is enabled in all pre-built binaries by default (evm feature is on). No --features evm flag is required.

cargo run -- red-team --target-session <session_id> cargo run -- red-team --target-session <session_id> \ --attack-budget 100 --output red-team-report.json

Generates injection payloads via LLM and tests each against the output scanner and tripwire in isolation. Exit code 1 when any payload passes all checks - integrate directly into CI. For single-payload manual testing, use replay --inject-observation instead.

cargo build --features zk cargo run --features zk -- prove-audit <session_id> cargo run --features zk -- prove-audit <session_id> \ --policy crates/host/policies/soc2-audit.toml --output audit.elc

Generates an SP1 ZK validity proof over the full event hash chain and policy commitment. A verifier can confirm policy compliance without access to raw event payloads - the right tool for regulated industries (healthcare, finance) where audited data cannot leave the client's perimeter. For all other use cases, the standard .elc certificate (five-pillar verification) provides sufficient cryptographic provenance without proof generation overhead.

Every completed session can be exported as a self-contained .elc file that is verifiable completely offline against five independent guarantees:

A sixth proof (SP1 ZK validity proof) is available when built with --features zk.

The verify-cert binary is a static, dependency-free binary (< 5 MB) designed to be shipped to customers, auditors, or regulators. It requires no Rust toolchain, PostgreSQL, or Ollama.

Sessions and .elc certificates carry an optional session_did field. When present, it contains a did:key: URI derived from the session Ed25519 keypair - providing a W3C-compatible, self-sovereign identity anchor for each audit session that can be verified by any standards-compliant DID resolver without calling back to the EctoLedger instance.

When an agent session completes, EctoLedger automatically issues a W3C VC-JWT that encodes the session identity, goal, policy hash, and completion status in a tamper-evident, portable credential:

{ "iss": "did:key:z...", "sub": "did:key:z...", "jti": "urn:uuid:<session-id>", "iat": 1740000000, "exp": 1747776000, "vc": { "@context": ["https://www.w3.org/2018/credentials/v1", "https://ectoledger.security/2026/credentials/v1"], "type": ["VerifiableCredential", "EctoLedgerSessionCredential"], "credentialSubject": { "id": "did:key:z...", "sessionId": "<uuid>", "goal": "Audit S3 bucket policies", "policyHash": "sha256:<hex>", "status": "completed", "issuedAt": "2026-02-22T03:00:00Z" } } }

Retrieve a session credential:

curl -H "Authorization: Bearer $OBSERVER_TOKEN" \ http://localhost:3000/api/sessions/<session-id>/vc | jq .

Verify (resolve) a session credential:

curl -H "Authorization: Bearer $OBSERVER_TOKEN" \ http://localhost:3000/api/sessions/<session-id>/vc/verify | jq . # → { "valid": true, "vc_payload": { ... } }

The verify endpoint performs:

1. Structural validation - checks that the JWT has the required header.payload.signature format.
2. Expiry check - rejects credentials whose exp claim is in the past (default lifetime: 90 days).
3. Signature verification - not performed by this REST endpoint; for full Ed25519 signature verification, use the verify_vc_jwt Rust API in crates/host/src/verifiable_credential.rs.

use ectoledger::verifiable_credential::{build_vc_jwt, verify_vc_jwt, VcVerifyError}; // Verify a VC-JWT with the session signing key let vk = signing_key.verifying_key(); match verify_vc_jwt(&vc_jwt, Some(&vk)) { Ok(payload) => println!("Valid credential: {}", payload), Err(VcVerifyError::Expired) => eprintln!("Credential has expired"), Err(VcVerifyError::InvalidSignature) => eprintln!("Signature mismatch"), Err(e) => eprintln!("Verification error: {}", e), }

EctoLedger emits structured events to any HTTP endpoint - configure once and receive real-time notifications for all security-relevant agent decisions.

Event kinds:

Configuration:

WEBHOOK_URL=https://siem.corp.example/ingest WEBHOOK_BEARER_TOKEN=<token> SIEM_FORMAT=json # json (default) | cef | leef WEBHOOK_INCLUDE_GUARD=true # default true - include GuardDenial events WEBHOOK_INCLUDE_TRIPWIRE=true # default true - include TripwireRejection events

CEF and LEEF payloads include event_kind, session_id, payload_hash, and timestamp. These formats are directly ingested by Splunk, IBM QRadar, and ArcSight.

cargo run -- audit "Audit SOC2 controls" \ --policy crates/host/policies/soc2-audit.toml cargo run -- audit "Audit cardholder data environment" \ --policy crates/host/policies/pci-dss-audit.toml cargo run -- audit "Audit web application for OWASP Top 10" \ --policy crates/host/policies/owasp-top10.toml cargo run -- audit "ISO 42001 AI system audit" \ --policy crates/host/policies/iso42001.toml

The TOML policy file supports four rule categories. All sections are optional.

name = "example-policy" max_steps = 30 # 1. Allowed / forbidden action lists [[allowed_actions]] action = "read_file" [[forbidden_actions]] action = "http_get" # 2. Conditional command rules - evaluated in order; first match wins [[command_rules]] program = "curl" arg_pattern = "^https://(internal\\.corp|api\\.example)\\.com" decision = "allow" [[command_rules]] program = "curl" arg_pattern = ".*" decision = "deny" reason = "curl permitted only to approved internal domains" # 3. Observation content rules - applied after each execution [[observation_rules]] pattern = "(?i)(password|secret|api.key)\\s*[:=]\\s*\\S+" action = "redact" # redact | flag | abort label = "credential_leak" # 4. Approval gate triggers - policy-driven human-in-the-loop [[approval_gates]] trigger = "action == 'run_command' && command_contains('nmap')" require_approval = true timeout_seconds = 300 on_timeout = "deny"

Rule types:

• command_rules - Applied to run_command actions only. program matches the first token; arg_pattern is a regex over remaining arguments. Decisions: allow, deny, require_approval.
• observation_rules - Applied to raw observation text after every tool execution. redact replaces matches with [REDACTED:<label>]; flag logs a warning and continues; abort terminates the session.
• approval_gates - Boolean trigger expressions (action == 'x', command_contains('y'), joined by &&). When triggered, an ApprovalRequired event is appended and the agent waits for a human decision via the REST API or --interactive stdin.

Additional trigger predicates:

[[plugins]] name = "trivy" binary = "trivy" description = "Container and filesystem vulnerability scanner" arg_patterns = ["^image\\s+\\S+", "^fs\\s+\\."] env_passthrough = ["TRIVY_USERNAME", "TRIVY_PASSWORD"] [[plugins]] name = "semgrep" binary = "semgrep" description = "Static analysis" arg_patterns = ["^--config\\s+\\S+\\s+\\."] env_passthrough = []

Plugin binaries are added to the executor allowlist only when declared in the policy file. env_passthrough injects named host environment variables into the plugin child process exclusively - the parent environment is never modified.

crates/host/policies/iso42001.toml provides 14 machine-readable controls mapped to ISO 42001:2023 clauses (4.1 through 10.1), loadable directly as a policy pack.

docs/iso42001.md provides the full compliance whitepaper: clause-by-clause mapping table, cryptographic controls reference (hash chain formula, Ed25519 signing, DID, Merkle), governance architecture diagram, and deployment checklist.

Safely audit AWS, GCP, Azure, or Kubernetes environments with ephemeral credentials. Credentials are injected only into matching cloud CLI child processes and never appear in the parent environment or audit logs.

Credential file format (~/.ectoledger/aws-audit.json):

{ "name": "aws-audit-role", "provider": "aws", "env_vars": { "AWS_ACCESS_KEY_ID": "ASIA...", "AWS_SECRET_ACCESS_KEY": "...", "AWS_SESSION_TOKEN": "..." } }

AGENT_CLOUD_CREDS_FILE=~/.ectoledger/aws-audit.json \ cargo run -- audit "Audit S3 bucket policy for public exposure"

Supported providers (added to executor allowlist only when credentials are present): aws, gcloud, az, kubectl, terraform, eksctl, helm. The credential name and provider are recorded as an auditable Thought event at session start; credential values are never logged.

Unit tests (no database required):

cargo test

Integration tests - PostgreSQL:

# Ephemeral Docker container (recommended) ./scripts/test-integration.sh # Against an existing instance DATABASE_URL=postgres://... cargo test --features integration

Integration tests - SQLite:

DATABASE_URL=sqlite://test.db cargo test --features integration

crates/host/tests/adversarial_guards.rs is a native Rust test module with 93 adversarial payloads that exercise the output scanner and tripwire layers directly — no running server, no database, no network, no external dependencies.

# Run all adversarial tests: cargo test -p ectoledger --test adversarial_guards # Run a single category: cargo test -p ectoledger --test adversarial_guards goal_injection cargo test -p ectoledger --test adversarial_guards tripwire_bypass cargo test -p ectoledger --test adversarial_guards output_scanner_evasion cargo test -p ectoledger --test adversarial_guards semantic_guard cargo test -p ectoledger --test adversarial_guards ancillary

OS-specific payloads (e.g. /etc/shadow on Linux, SAM on Windows, Keychain on macOS) are gated with #[cfg(target_os = "...")] so they compile and run only on the relevant platform — zero runtime overhead, no OS detection needed.

Each test calls scan_observation() or Tripwire::validate() directly as pure functions — no I/O, no async runtime. This means the adversarial test suite:

• Runs in < 0.1 seconds (no server startup)
• Requires zero external dependencies (no Python, npm, or Docker)
• Works offline on any platform with a Rust toolchain
• Integrates naturally with cargo test and CI pipelines

Apple's Seatbelt sandbox does not provide per-process network isolation. Child processes spawned by the executor inherit full outbound network access. This is an architectural limitation of macOS, not a bug in EctoLedger.

For production macOS deployments, apply edge network filtering to restrict outbound traffic from the EctoLedger process:

• Deploy a host-level firewall (pfctl, Little Snitch, Lulu) or corporate forward proxy.
• Configure AGENT_ALLOWED_DOMAINS to restrict http_get destinations.
• Use Docker Desktop for Mac (ECTO_DOCKER_IMAGE=alpine:3.19) to gain --network=none isolation for run_command actions.
• Use a local DNS sinkhole (dnsmasq / Unbound) to block DNS-tunnelling exfiltration.

See SANDBOX_CROSS_PLATFORM.md for the full cross-platform security comparison.

Beyond the defaults (sandbox + evm), the following optional features are available:

Note: The sandbox feature activates Linux-specific Landlock LSM + seccomp-BPF. On macOS and Windows, OS-level sandboxing (Seatbelt / Job Objects) is compiled unconditionally — the sandbox flag is a no-op on those platforms.

EctoLedger/ ├── ectoledger-mac # macOS launcher (bash) ├── ectoledger-linux # Linux launcher (bash) ├── ectoledger-win.ps1 # Windows launcher (PowerShell) ├── crates/ │ ├── core/ # Pure logic - no I/O; shared with the SP1 zkVM guest │ │ └── src/ │ │ ├── hash.rs # SHA-256 helpers (sha256_hex, compute_content_hash) │ │ ├── merkle.rs # Binary Merkle tree, inclusion proofs │ │ ├── intent.rs # ProposedIntent, ValidatedIntent │ │ ├── policy.rs # PolicyEngine, all policy structs, policy_hash_bytes │ │ └── schema.rs # SP1 zkVM protocol types: ChainEvent, GuestInput, GuestOutput │ ├── guest/ # SP1 RISC-V zkVM guest (compiled separately with --features zk) │ │ └── src/main.rs # Verifies genesis, hash chain, Merkle root, policy patterns │ ├── guard_unikernel/ # Bare-metal guard unikernel (aarch64-unknown-none) │ │ └── src/main.rs # Standalone guard binary for hardware enclaves │ ├── ledger-api/ # Pluggable LedgerBackend trait - standalone, no host dependency │ │ └── src/lib.rs # LedgerBackend, LedgerError, LedgerEvent, Session, AppendResult │ └── host/ # Main application: ectoledger, guard-worker, verify-cert │ ├── src/ │ │ ├── main.rs # CLI entry point │ │ ├── agent.rs # Cognitive loop │ │ ├── ledger.rs # Module root - re-exports postgres free functions │ │ ├── ledger/ │ │ │ ├── postgres.rs # PostgresLedger implementing LedgerBackend │ │ │ └── sqlite.rs # SqliteLedger implementing LedgerBackend │ │ ├── server.rs # Axum server (Observer, SSE, metrics, approvals API) │ │ ├── orchestrator.rs # Multi-agent: Recon → Analysis → Verify + CrossLedgerSeal │ │ ├── guard.rs # Guard trait; in-process fallback │ │ ├── guard_process.rs # Spawns guard-worker, communicates via stdin/stdout JSON │ │ ├── tripwire.rs # Structural intent validation │ │ ├── output_scanner.rs # Hybrid scanner (13 regex + 8 exfil patterns + structural JSON/AST) │ │ ├── policy.rs # Host-side policy loader │ │ ├── certificate.rs # .elc: Merkle, OTS, Ed25519, optional SP1 ZK proof │ │ ├── report.rs # SARIF 2.1, HTML, GitHub Actions, GitLab CQ, certificate │ │ ├── webhook.rs # Async SIEM egress (JSON/CEF/LEEF); EgressKind enum │ │ ├── signing.rs # Ed25519 session keypair and per-event signing │ │ ├── cloud_creds.rs # Ephemeral cloud credential injection │ │ ├── sandbox.rs # Linux Landlock/seccomp, macOS Seatbelt, Windows Job Object │ │ ├── approvals.rs # Approval gate state, session pause/resume │ │ ├── ots.rs # OpenTimestamps integration │ │ ├── red_team.rs # Adversarial payload generation and defense testing │ │ ├── snapshot.rs # Agent state snapshots │ │ ├── executor.rs # run_command / read_file / http_get │ │ ├── config.rs # Environment variable loading, settings persistence │ │ ├── metrics.rs # Prometheus metrics and counters │ │ ├── compensation.rs # Compensating-action planner for rollback │ │ ├── schema.rs # Event types: Genesis, Thought, Action, Observation, … │ │ ├── diff_audit.rs # Cross-session diff comparisons │ │ ├── verifiable_credential.rs # W3C VC-JWT issuance and verification (Ed25519 / did:key) │ │ ├── evm_anchor.rs # Ethereum on-chain session hash anchoring (feature: evm) │ │ ├── llm/ # LLM backends: Ollama, OpenAI, Anthropic │ │ └── bin/ # guard_worker.rs, verify_cert.rs │ ├── migrations/ # PostgreSQL migrations (sqlx) │ │ └── sqlite/ # SQLite migrations (001–005) │ ├── tests/ │ │ ├── adversarial_guards.rs # 93 adversarial prompt injection tests (pure Rust, no I/O) │ │ └── cross_platform_cmd_guards.rs # Windows CMD + Linux host injection guard tests │ └── policies/ # Policy packs: soc2, pci-dss, owasp-top10, iso42001 ├── assets/ │ ├── ectoLedger-Logo.webp # README logo │ └── el-logo.webp # Icon source (icons generated via npm run icon:generate) ├── scripts/ │ ├── test-integration.sh # Integration test harness (Docker Postgres) │ ├── setup-firecracker.sh # Firecracker microVM setup (Linux/KVM) │ └── provision-firecracker.sh # Firecracker provisioning with custom prefix ├── gui/ # Tauri 2 + Svelte 5 management GUI │ ├── scripts/ │ │ └── generate-icons.mjs # Generates Tauri icons from assets/el-logo.webp │ ├── src/ │ │ ├── App.svelte # Root layout - three-tab glassmorphic shell │ │ └── lib/ │ │ ├── Sidebar.svelte # Navigation sidebar │ │ ├── Dashboard.svelte # Test Prompt panel + live metrics │ │ ├── LiveDashboard.svelte # Real-time streaming agent activity view │ │ ├── MetricsView.svelte # Prometheus metrics tab │ │ ├── Sessions.svelte # Session browser, event viewer, certificate export │ │ ├── PolicyEditor.svelte # TOML policy editor with live validation │ │ ├── TripwireView.svelte # Tripwire config (paths, domains, commands, justification) │ │ ├── TokensView.svelte # RBAC API token management │ │ ├── WebhooksView.svelte # Webhook/SIEM egress configuration │ │ ├── ObserverPanel.svelte # Embedded Observer dashboard panel │ │ ├── TestingView.svelte # Adversarial testing interface │ │ ├── DevHub.svelte # Developer reference and integration guides │ │ ├── SetupWizard.svelte # First-run onboarding wizard │ │ └── Settings.svelte # LLM backend and model settings │ └── src-tauri/ # Tauri 2 Rust backend (9 HTTP-proxy Tauri commands) ├── sdk/ │ ├── python/ # Python SDK - pip install ectoledger-sdk │ │ └── ectoledger_sdk/ │ │ ├── client.py # LedgerClient (httpx + pydantic) │ │ ├── models.py # Session, LedgerEvent, AppendResult, MetricsSummary │ │ ├── langchain/ # LedgerTool (langchain_core BaseTool) │ │ └── autogen/ # LedgerHook (ConversableAgent reply hook) │ └── typescript/ # TypeScript SDK - npm install ectoledger-sdk │ └── src/ │ ├── client.ts # EctoLedgerClient (native fetch, zero dependencies) │ ├── models.ts # Typed interfaces │ └── index.ts # Barrel export ├── contracts/ │ └── EctoLedgerAnchor.sol # EVM smart contract for on-chain session hash anchoring ├── docs/ │ ├── schema.md # Event schema reference │ ├── iso42001.md # ISO 42001:2023 compliance whitepaper │ ├── sandbox-parity.md # Sandbox feature parity matrix │ └── sandbox-verification-report.md # Sandbox verification test results ├── SANDBOX_CROSS_PLATFORM.md # Cross-platform sandbox comparison + macOS security warning └── audit_policy.example.toml # Annotated example policy file 

Apache 2.0 — use it freely for personal, internal, commercial, research, and open-source purposes. See LICENSE for the full text.

For enterprise consulting, custom integrations, or support SLAs, contact ectoledger@pm.me.