How lexicoding-systems/lexecon-demo works
1. Overall shape
Lexecon is a Python package that sits between an agent’s tool request and the actual tool execution. Its core responsibility is to decide whether a requested action is allowed, blocked, or escalated, and to write a tamper-evident audit trail for that decision.
2. Primary control point
The architectural gate is lexecon/enforcement/interceptor.py. Every agent tool call is expected to enter through Interceptor.intercept(). That method is the trust boundary: it receives a normalized tool-call payload, asks policy for a decision, records the result, and only then permits execution.
3. Policy evaluation layer
lexecon/enforcement/policy_engine.py implements deterministic policy checks driven by YAML files in lexecon/policies/. The repository ships with default_policy.yaml and demo_policy.yaml, so policy is configuration-driven rather than hardcoded in the execution path.
4. Decision model
lexecon/enforcement/decision.py defines the small decision vocabulary: ALLOW, BLOCK, and ESCALATE. This keeps enforcement logic and downstream handling simple: execution is only allowed on ALLOW, while malformed or risky inputs fail closed.
5. Tool execution boundary
Actual command execution lives in lexecon/tools/shell.py. This layer is intentionally separate from enforcement; it should be called only after an allow decision. The README explicitly warns that direct calls to the tools layer bypass policy and audit entirely.
6. Audit trail subsystem
The audit path is split into three concerns: record.py defines the canonical record shape and hashing, ledger.py appends records to a JSONL ledger with hash chaining, and signer.py handles Ed25519 signing. The audit trail is local-file based and designed to be append-only and verifiable after the fact.
7. Offline verification
lexecon/audit/verifier.py replays the ledger offline to check three things: record hash integrity, previous_hash continuity, and signature validity. This is what turns the audit log into a tamper-evident artifact rather than just an event log.
8. External adapter boundary
lexecon/adapters/anthropic_adapter.py is the integration seam for Anthropic-style agent payloads. Its role is to normalize provider-specific tool-call structures into Lexecon’s internal request shape so the same interceptor and policy engine can be reused regardless of upstream model provider.
9. CLI and demo flows
lexecon/cli.py exposes three operational entry points: init-keys, demo, and verify. The demo path exercises the full chain end to end: agent request → interception → policy decision → signed ledger entry → optional execution. The included example script in examples/ shows the same blocked-destructive-command scenario.
10. Key management and local state
Keys are generated locally into .lexecon/ as Ed25519 PEM files. This keeps the demo self-contained and offline, but also makes the trust model intentionally local; the repository does not include enterprise key management, HSM/KMS integration, or remote attestation.
11. Failure mode and security stance
The system is designed to fail closed. Tests cover malformed payloads and unsupported tool shapes at both the policy engine and interceptor levels, ensuring that bad inputs block execution rather than slipping through. This is central to the architecture because the main safety guarantee depends on rejecting ambiguous requests.
12. Testing and CI posture
The test suite covers the main subsystems separately and together: policy normalization, interceptor behavior, audit signing/verifying, ledger concurrency, malformed inputs, and the full demo flow. The GitHub Actions workflow runs these checks as the repo’s primary regression guard.
13. What is intentionally out of scope
The repository is about control and verifiable logging, not OS sandboxing or deep command understanding. The README is explicit that direct subprocess use outside the interceptor, advanced command obfuscation, and distributed transparency mechanisms are not solved here. Those are important boundaries to show in any architecture diagram.
Main entry points: interceptor.py Interceptor · cli.py CLI · policy_engine.py Policy engine · signer.py Signer
Components 16
Enforcement
Trust boundary, policy evaluation, and decisioning for tool calls.
- Interceptor · Primary gate that receives tool calls, consults policy, records decisions, and permits or blocks execution.
lexecon/enforcement/interceptor.py - Policy engine · Evaluates normalized requests against configured policy rules.
lexecon/enforcement/policy_engine.py - Decision model · ALLOW, BLOCK, and ESCALATE decision vocabulary.
lexecon/enforcement/decision.py
Audit
Append-only record, signing, and offline verification.
- Audit record · Canonical audit record shape and hashing inputs.
lexecon/audit/record.py - Ledger · JSONL ledger with hash chaining for recorded decisions.
lexecon/audit/ledger.py - Signer · Signs audit records for tamper evidence.
lexecon/audit/signer.py - Verifier · Replays the ledger to validate hashes, continuity, and signatures.
lexecon/audit/verifier.py
Adapters
Provider-specific payload normalization into Lexecon's internal request shape.
- Anthropic adapter · Converts provider payloads into Lexecon's internal tool-call shape.
lexecon/adapters/anthropic_adapter.py
Runtime
Tool execution boundary and demo entry points.
- CLI · Operational commands for key init, demo, and verification.
lexecon/cli.py - Demo flow · End-to-end example of interception, audit, and optional execution.
examples/block_destructive_shell.py - Shell tools · Actual command execution layer that must only run after allow decisions.
lexecon/tools/shell.py - Key init · Generates local Ed25519 key material under .lexecon/.
lexecon/cli.py - Verify cmd · Runs offline audit verification over the ledger.
lexecon/cli.py - Demo cmd · Executes the demo scenario end to end.
lexecon/cli.py
Policies
YAML policy inputs used by deterministic enforcement.
- Default policy · Built-in policy configuration for normal enforcement.
lexecon/policies/default_policy.yaml - Demo policy · Policy variant used by the demo flow.
lexecon/policies/demo_policy.yaml
Connections 19
- Demo flow → Anthropic adapter: normalize · Example payload is adapted into the internal request form.
- Anthropic adapter → Interceptor: submit · Normalized tool-call payload enters the trust boundary.
- CLI → Key init: init-keys · CLI exposes local key generation.
- CLI → Demo cmd: demo · CLI launches the end-to-end demo flow.
- CLI → Verify cmd: verify · CLI launches offline ledger verification.
- Demo cmd → Anthropic adapter: request · Demo path begins with a provider-style tool call.
- Interceptor → Policy engine: evaluate · Interceptor asks policy for a decision.
- Policy engine → Default policy: load · Default policy provides the baseline rules.
- Policy engine → Demo policy: load · Demo policy is an alternate configuration.
- Policy engine → Decision model: decide · Policy engine returns an allow, block, or escalate result.
- Interceptor → Audit record: shape · Decision is converted into a canonical audit record.
- Audit record → Signer: hash · Record contents are hashed before signing.
- Signer → Ledger: append · Signed record is appended to the JSONL ledger.
- Interceptor → Ledger: write · Interceptor persists the decision trail.
- Interceptor → Shell tools: allow only · Execution proceeds only after an allow decision.
- Ledger → Verifier: replay · Verifier replays ledger entries for integrity checks.
- Signer → Verifier: validate · Verifier checks signature validity.
- CLI → Verifier: run · Verify command invokes offline verification.
- Interceptor → Decision model: gate · Execution is blocked or escalated unless decision is allow.