Lexecon - Cryptographic Governance Protocol for AI Systems

Enterprise-grade cryptographic governance framework for AI safety, compliance, and auditability

Built for the EU AI Act era—tamper-proof audit trails, deny-by-default security, and runtime enforcement

Documentation • Quick Start • Features • Roadmap • Contributing

---

🎯 What is Lexecon?

Lexecon is a comprehensive cryptographic governance protocol that provides:

• 🔐 Cryptographically Auditable Decision-Making: Every AI action is signed, hashed, and chain-linked
• ⚡ Runtime Policy Enforcement: Deny-by-default gating with capability-based authorization
• 📋 Compliance Automation: Built-in mappings for EU AI Act, GDPR, SOC 2, and ISO 27001
• 🛡️ Enterprise Security: RBAC, digital signatures (Ed25519/RSA-4096), audit logging
• 🔗 Tamper-Evident Ledgers: Hash-chained audit trails with integrity verification
• 🤖 Model-Agnostic: Works with OpenAI, Anthropic, and open-source models

Think of it as blockchain-grade governance for AI systems—without the blockchain.

---

🚀 Why Lexecon?

The Problem

Modern AI systems face critical governance challenges:

Challenge	Impact	Regulatory Risk
Uncontrolled Tool Usage	Models execute arbitrary tools without oversight	High
No Audit Trail	Can't prove what decisions were made or why	Critical
Compliance Burden	Manual mapping of AI behavior to regulations	Very High
Policy Drift	Policies become outdated, inconsistent	Medium
Prompt Injection	Adversarial inputs bypass controls	High

The Solution

Lexecon provides cryptographic proof of governance:

# Before Lexecon: Hope and pray
model.call_tool("delete_production_database")  # 😱

# With Lexecon: Cryptographically enforced
decision = governance.request_decision(
    action="database:delete",
    context={"environment": "production"}
)
# ❌ DENIED - Cryptographically signed audit trail created

---

🏗️ Core Capabilities

1. Policy Engine (src/lexecon/policy/)

Lexicoding-forward policy system with graph-based evaluation.

Features:

• ✅ Declarative policy language (terms + relations)
• ✅ Compile-time validation and runtime evaluation
• ✅ Policy versioning with hash pinning
• ✅ Deterministic evaluation (no LLM in the loop)

Example:

from lexecon.policy import PolicyEngine, PolicyTerm, PolicyRelation

engine = PolicyEngine()

# Define terms (nodes in policy graph)
read_action = PolicyTerm.create_action("read", "Read Data")
user_actor = PolicyTerm.create_actor("user", "Standard User")

# Define relations (edges in policy graph)
engine.add_relation(PolicyRelation.permits(user_actor, read_action))

# Evaluate
result = engine.evaluate(actor="user", action="read")  # ✅ Permitted

2. Decision Service (src/lexecon/decision/)

Real-time policy evaluation and capability token issuance.

Features:

• ✅ Pre-execution gating for all tool calls
• ✅ Context-aware policy evaluation
• ✅ Reason traces for explainability
• ✅ Capability token minting (time-limited, scoped)

Flow:

Model Request → Decision Service → Policy Evaluation → Token Issuance → Ledger Recording

3. Capability System (src/lexecon/capability/)

Short-lived authorization tokens for approved actions.

Features:

• ✅ Scoped permissions (single action or resource)
• ✅ Time-limited validity (configurable TTL)
• ✅ Policy version binding
• ✅ Cryptographic verification

Example:

token = capability_service.mint_token(
    action="database:read",
    scope={"table": "users"},
    ttl_seconds=300  # 5-minute validity
)
# Token: cap_a1b2c3d4_read_users_exp1704412800

4. Cryptographic Ledger (src/lexecon/ledger/)

Tamper-evident audit log using hash chaining.

Features:

• ✅ Hash-chained entries (like blockchain, but faster)
• ✅ Ed25519 signatures on all events
• ✅ Integrity verification tooling
• ✅ Audit report generation

Properties:

• 🔒 Tamper-Evident: Any modification breaks the chain
• 🔍 Auditable: Complete forensic trail
• ⚡ Fast: 10,000+ entries/second
• 📦 Portable: Export to JSON/SQLite

5. Evidence Management (src/lexecon/evidence/)

Immutable artifact storage for compliance evidence.

Features:

• ✅ Append-only storage (optional)
• ✅ SHA-256 content hashing
• ✅ Digital signatures (RSA-4096)
• ✅ Artifact types: decisions, attestations, compliance records

Use Cases:

• 📄 EU AI Act technical documentation
• 📊 Compliance audit trails
• 🔏 Signed attestations from executives
• 📈 Risk assessments

6. Risk Management (src/lexecon/risk/)

Quantitative risk assessment and tracking.

Features:

• ✅ Risk scoring (likelihood × impact)
• ✅ Mitigation tracking
• ✅ Escalation workflows
• ✅ Risk register management

7. Escalation System (src/lexecon/escalation/)

Human-in-the-loop oversight for high-risk decisions.

Features:

• ✅ Automatic escalation triggers
• ✅ Resolution workflows (approve/reject/defer)
• ✅ Escalation history tracking
• ✅ Notification integration (email, Slack, PagerDuty)

8. Override Management (src/lexecon/override/)

Executive override capabilities with full audit trail.

Features:

• ✅ Break-glass emergency procedures
• ✅ Executive approval workflows
• ✅ Override justification requirements
• ✅ Compliance reporting

9. Compliance Mapping (src/lexecon/compliance_mapping/)

Automatic mapping of governance primitives to regulatory controls.

Supported Frameworks:

• ✅ EU AI Act (Articles 9-17, 72)
• ✅ GDPR (Articles 5, 22, 25, 32, 35)
• ✅ SOC 2 (CC1-CC9, Trust Service Criteria)
• ✅ ISO 27001 (Controls A.5-A.18)

Example:

mapping = compliance_service.map_primitive_to_controls(
    primitive_type="DECISION_LOGGING",
    primitive_id="dec_12345",
    framework=RegulatoryFramework.EU_AI_ACT
)
# Returns: [Article 12.1, Article 12.2, Article 16.d, Article 72]

10. EU AI Act Compliance (src/lexecon/compliance/eu_ai_act/)

Specialized implementation of EU AI Act requirements.

Modules:

• ✅ Article 11: Technical documentation
• ✅ Article 12: Record-keeping (automatic logging)
• ✅ Article 14: Human oversight workflows

11. Security Services (src/lexecon/security/)

Enterprise security infrastructure.

Components:

• ✅ Authentication: RBAC with hierarchical permissions
• ✅ Digital Signatures: Ed25519 for audit packets, RSA-4096 for artifacts
• ✅ Audit Logging: Comprehensive security event tracking
• ✅ Middleware: FastAPI integration for request signing

12. Observability (src/lexecon/observability/)

Production-ready monitoring and telemetry.

Features:

• ✅ Structured JSON logging with context vars
• ✅ OpenTelemetry tracing integration
• ✅ Prometheus metrics export
• ✅ Health check endpoints

13. Audit Export (src/lexecon/audit_export/)

Compliance-ready audit report generation.

Features:

• ✅ Time-range filtering
• ✅ Event type filtering
• ✅ Multiple export formats (JSON, CSV, PDF)
• ✅ Cryptographic integrity proofs

14. Responsibility Tracking (src/lexecon/responsibility/)

Chain of custody for AI decisions.

Features:

• ✅ Responsibility assignment per decision
• ✅ Delegation workflows
• ✅ Accountability reporting
• ✅ RACI matrix support

15. Storage Layer (src/lexecon/storage/)

Flexible persistence with SQLite and PostgreSQL support.

Features:

• ✅ SQLite for development/testing
• ✅ PostgreSQL for production
• ✅ Migration support
• ✅ Backup and restore utilities

16. CLI Tools (src/lexecon/cli/)

Comprehensive command-line interface.

Commands:

lexecon init              # Initialize configuration
lexecon policy validate   # Validate policy definitions
lexecon audit verify      # Verify ledger integrity
lexecon export audit      # Export audit reports
lexecon doctor            # System diagnostics

17. REST API (src/lexecon/api/)

Production FastAPI server with 30+ endpoints.

Endpoint Categories:

• /decisions - Decision requests and history
• /policies - Policy management
• /capabilities - Token operations
• /ledger - Audit trail queries
• /evidence - Artifact management
• /escalations - Human oversight
• /overrides - Executive actions
• /compliance - Regulatory reporting

---

📊 Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                         Lexecon Protocol Stack                            │
├──────────────────────────────────────────────────────────────────────────┤
│  🌐 API Layer (FastAPI)                                                  │
│     REST Endpoints │ OpenAPI Docs │ Request Validation │ Rate Limiting   │
├──────────────────────────────────────────────────────────────────────────┤
│  🎭 Governance Core                                                      │
│     ┌──────────────────┬──────────────────┬─────────────────────────┐   │
│     │ Policy Engine    │ Decision Service │ Capability System       │   │
│     │ • Graph Eval     │ • Gating         │ • Token Minting         │   │
│     │ • Constraints    │ • Reason Traces  │ • Verification          │   │
│     └──────────────────┴──────────────────┴─────────────────────────┘   │
├──────────────────────────────────────────────────────────────────────────┤
│  🔐 Cryptographic Services                                                │
│     ┌──────────────────┬──────────────────┬─────────────────────────┐   │
│     │ Ledger (Hashing) │ Identity (Keys)  │ Signatures (Ed25519)    │   │
│     │ • Hash Chains    │ • Ed25519 Keys   │ • Packet Signing        │   │
│     │ • Integrity      │ • Key Storage    │ • Verification          │   │
│     └──────────────────┴──────────────────┴─────────────────────────┘   │
├──────────────────────────────────────────────────────────────────────────┤
│  📋 Compliance & Risk                                                     │
│     ┌──────────────────┬──────────────────┬─────────────────────────┐   │
│     │ EU AI Act        │ Compliance Map   │ Risk Management         │   │
│     │ • Art. 11-14     │ • SOC 2 / GDPR   │ • Scoring               │   │
│     │ • Documentation  │ • ISO 27001      │ • Mitigation            │   │
│     └──────────────────┴──────────────────┴─────────────────────────┘   │
├──────────────────────────────────────────────────────────────────────────┤
│  🚨 Oversight & Controls                                                  │
│     ┌──────────────────┬──────────────────┬─────────────────────────┐   │
│     │ Escalations      │ Overrides        │ Responsibility          │   │
│     │ • Human Review   │ • Break-glass    │ • Accountability        │   │
│     │ • Workflows      │ • Justification  │ • Chain of Custody      │   │
│     └──────────────────┴──────────────────┴─────────────────────────┘   │
├──────────────────────────────────────────────────────────────────────────┤
│  📦 Evidence & Audit                                                      │
│     ┌──────────────────┬──────────────────┬─────────────────────────┐   │
│     │ Evidence Store   │ Audit Export     │ Verification Tools      │   │
│     │ • Artifacts      │ • Reports        │ • Integrity Checks      │   │
│     │ • Signatures     │ • Time-range     │ • Hash Validation       │   │
│     └──────────────────┴──────────────────┴─────────────────────────┘   │
├──────────────────────────────────────────────────────────────────────────┤
│  📊 Observability                                                         │
│     Logging (Structured) │ Tracing (OpenTelemetry) │ Metrics (Prometheus)│
├──────────────────────────────────────────────────────────────────────────┤
│  💾 Storage Layer                                                         │
│     SQLite (Dev) │ PostgreSQL (Prod) │ Migrations │ Backups             │
└──────────────────────────────────────────────────────────────────────────┘

---

🛠️ Installation

Prerequisites

• Python 3.8+
• pip or Poetry

Quick Install

# From PyPI (when published)
pip install lexecon

# From source
git clone https://github.com/Lexicoding-systems/Lexecon.git
cd Lexecon
pip install -e ".[dev]"

# Verify installation
lexecon --version
lexecon doctor

Docker

docker pull lexecon/lexecon:latest
docker run -p 8000:8000 lexecon/lexecon:latest

---

🚀 Quick Start

1. Initialize Configuration

lexecon init
# Creates: ~/.lexecon/config.yaml, keys/, policies/

2. Start the API Server

lexecon serve
# Server running at: http://localhost:8000
# API docs: http://localhost:8000/docs

3. Make Your First Decision Request

import requests

response = requests.post("http://localhost:8000/decisions/request", json={
    "actor": "act_human_user:alice",
    "action": "database:read",
    "resource": "users_table",
    "context": {
        "environment": "production",
        "purpose": "analytics"
    }
})

decision = response.json()
print(f"Decision: {decision['outcome']}")  # "allowed" or "denied"
print(f"Reason: {decision['reason']}")
print(f"Token: {decision.get('capability_token')}")

4. Verify Ledger Integrity

lexecon audit verify
# ✅ Ledger integrity verified
# ✅ 1,234 entries checked
# ✅ Chain intact from genesis to head

---

📚 Usage Examples

Policy Definition

from lexecon.policy import PolicyEngine, PolicyTerm, PolicyRelation, RelationType

engine = PolicyEngine()

# Define actors
admin = PolicyTerm.create_actor("admin", "Administrator")
user = PolicyTerm.create_actor("user", "Standard User")

# Define actions
read = PolicyTerm.create_action("read", "Read data")
write = PolicyTerm.create_action("write", "Write data")
delete = PolicyTerm.create_action("delete", "Delete data")

# Define relations
engine.add_relation(PolicyRelation.permits(admin, read))
engine.add_relation(PolicyRelation.permits(admin, write))
engine.add_relation(PolicyRelation.permits(admin, delete))
engine.add_relation(PolicyRelation.permits(user, read))
engine.add_relation(PolicyRelation.forbids(user, delete))

# Evaluate
result = engine.evaluate(actor="user", action="delete")
print(result.outcome)  # "denied"

Compliance Mapping

from lexecon.compliance_mapping import ComplianceMappingService, RegulatoryFramework

service = ComplianceMappingService()

# Map a decision to EU AI Act articles
mapping = service.map_primitive_to_controls(
    primitive_type="DECISION_LOGGING",
    primitive_id="dec_12345",
    framework=RegulatoryFramework.EU_AI_ACT
)

print(f"Mapped to {len(mapping.control_ids)} controls:")
for control_id in mapping.control_ids:
    print(f"  - {control_id}")

# Generate compliance report
report = service.generate_compliance_report(RegulatoryFramework.SOC2)
print(f"Compliance: {report.compliance_percentage:.1f}%")

Risk Assessment

from lexecon.risk import RiskService, RiskLevel

risk_service = RiskService()

# Create risk assessment
risk = risk_service.create_risk(
    title="Unauthorized data access",
    description="User attempting to access PII without proper authorization",
    category="data_privacy",
    likelihood=0.3,
    impact=0.9,
    affected_systems=["user_database", "audit_log"]
)

print(f"Risk ID: {risk.risk_id}")
print(f"Risk Score: {risk.risk_score:.2f}")
print(f"Risk Level: {risk.risk_level}")  # HIGH

# Add mitigation
risk_service.add_mitigation(
    risk_id=risk.risk_id,
    action="Implement additional RBAC checks",
    responsible_party="security_team"
)

Evidence Management

from lexecon.evidence import EvidenceService, ArtifactType

evidence_service = EvidenceService()

# Store compliance evidence
artifact = evidence_service.store_artifact(
    artifact_type=ArtifactType.ATTESTATION,
    content="We certify that all AI decisions are logged and auditable",
    source="cto@company.com",
    metadata={
        "regulation": "EU AI Act Article 12",
        "period": "2024-Q1"
    }
)

# Sign artifact (RSA-4096)
signed = evidence_service.sign_artifact(
    artifact_id=artifact.artifact_id,
    signer_id="act_human_user:cto",
    signature="...",
    algorithm="RSA-SHA256"
)

print(f"Artifact ID: {artifact.artifact_id}")
print(f"SHA256 Hash: {artifact.sha256_hash}")

---

🧪 Testing & Quality

Test Coverage

pytest --cov=src/lexecon --cov-report=html
# 824 tests passing
# 69% coverage (targeting 80%+)

Modules at 100% Coverage

• ✅ observability/logging.py
• ✅ observability/metrics.py
• ✅ observability/health.py
• ✅ evidence/append_only_store.py
• ✅ compliance_mapping/service.py
• ✅ policy/terms.py
• ✅ ledger/chain.py
• ✅ identity/signing.py
• ✅ capability/tokens.py

Quality Metrics

Metric	Status	Target
Test Coverage	69%	80%+
Tests Passing	824	All
Type Coverage	85%	90%+
Linting	✅ Black + Ruff	Clean
Security Scan	✅ CodeQL	No High

---

🗺️ Roadmap

Phase 1: Foundation ✅ COMPLETE

• ✅ Policy engine with graph evaluation
• ✅ Decision service with capability tokens
• ✅ Cryptographic ledger with hash chaining
• ✅ Evidence management system
• ✅ Basic compliance mapping (EU AI Act, GDPR, SOC 2)

Phase 2: Enterprise Features ✅ COMPLETE

• ✅ Risk management and scoring
• ✅ Escalation workflows
• ✅ Override management
• ✅ Responsibility tracking
• ✅ Security services (RBAC, signing, audit)
• ✅ REST API (30+ endpoints)
• ✅ CLI tooling

Phase 3: Advanced Compliance 🚧 IN PROGRESS

• ✅ EU AI Act Articles 11, 12, 14
• ✅ Compliance mapping automation
• 🚧 Automated compliance reporting
• 🚧 Real-time compliance dashboards
• 🚧 Export to regulatory formats (ESEF, XBRL)

Phase 4: Production Hardening 📋 PLANNED

• 📋 PostgreSQL production backend
• 📋 Horizontal scaling support
• 📋 High-availability deployments
• 📋 Kubernetes operators
• 📋 Terraform modules
• 📋 Performance benchmarking (10K+ req/s)

Phase 5: ML Integration 📋 PLANNED

• 📋 LangChain integration
• 📋 OpenAI function calling adapters
• 📋 Anthropic tool use integration
• 📋 Prompt injection detection
• 📋 Model behavior analysis

Phase 6: Advanced Features 🔮 FUTURE

• 🔮 Federated governance (multi-org)
• 🔮 Zero-knowledge proofs for privacy
• 🔮 Blockchain anchoring (optional)
• 🔮 AI-generated policy suggestions
• 🔮 Automated red-teaming
• 🔮 Compliance prediction (ML-based)

---

📖 Documentation

Core Concepts

• Policy Terms: Nodes in the policy graph (actors, actions, resources, data classes)
• Policy Relations: Edges defining permissions (permits, forbids, requires, implies)
• Governance Primitives: Core operations (decisions, escalations, overrides, evidence)
• Capability Tokens: Short-lived authorization tokens for approved actions
• Hash Chaining: Tamper-evident linking of audit entries
• Digital Signatures: Ed25519 for speed, RSA-4096 for compliance

API Reference

Full API documentation available at /docs when server is running:

lexecon serve
# Visit: http://localhost:8000/docs

CLI Reference

lexecon --help              # Show all commands
lexecon policy --help       # Policy management
lexecon audit --help        # Audit operations
lexecon export --help       # Export utilities

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/Lexicoding-systems/Lexecon.git
cd Lexecon

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linters
black src/ tests/
ruff check src/ tests/

# Run type checker
mypy src/

Areas for Contribution

• 🧪 Test coverage (target: 80%+)
• 📚 Documentation and examples
• 🌍 Additional compliance frameworks
• 🔌 Model integrations (LangChain, LlamaIndex)
• 🚀 Performance optimizations
• 🐛 Bug fixes and improvements

---

🔒 Security

Reporting Vulnerabilities

Please report security issues to: [Jacobporter@lexicoding.tech]

Do not open public issues for security vulnerabilities.

Security Features

• ✅ Ed25519 cryptographic signatures (tamper-proof)
• ✅ Hash-chained audit logs (immutable)
• ✅ RBAC with hierarchical permissions
• ✅ Time-limited capability tokens
• ✅ Request signing middleware
• ✅ Audit log integrity verification
• ✅ Input validation and sanitization

---

📄 License

Lexecon is released under the MIT License.

Copyright (c) 2024 Lexicoding Systems

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

🌟 Why Choose Lexecon?

Feature	Lexecon	Traditional Approaches
Audit Trail	Cryptographically tamper-proof	Mutable logs, easy to alter
Policy Enforcement	Runtime gating, deny-by-default	Post-hoc analysis, hope-based
Compliance	Automated mapping, real-time	Manual processes, expensive
Transparency	Every decision explained	Black-box decisions
Security	Ed25519 signatures, hash chains	Often none
Scalability	10K+ req/s (target)	Varies

---

📞 Support & Community

• Documentation: https://lexecon.readthedocs.io (coming soon)
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [Jacobporter@lexicoding.tech] (mailto:Jacobporter@lexicoding.tech)

---

🙏 Acknowledgments

Built with:

• FastAPI - Modern web framework
• Pydantic - Data validation
• Cryptography - Ed25519 and RSA implementations
• SQLAlchemy - Database ORM
• pytest - Testing framework

Inspired by:

• EU AI Act requirements
• NIST AI Risk Management Framework
• OpenAI's safety practices
• Anthropic's Constitutional AI

---

Lexecon - Governance you can prove

Get Started • View Roadmap • Contribute