Lilith-Zero

Deterministic Security Middleware for MCP tool calls written in Rust.

Lilith Zero is a high-performance security runtime designed to mitigate data exfiltration and unauthorized tool invocation in LLM-based agent systems. By interposing at the transport layer, Lilith Zero enforces security invariants through deterministic policy evaluation and strictly framed execution.

Lilith Zero is OS, framework, and language agnostic, providing uniform security primitives across diverse implementation environments.

Technical Fundamentals

• Security Priority: Lilith Zero adheres to a hierarchy of constraints where security correctness precedes performance and feature parity.
• Fail-Closed Architecture: The system defaults to a DENY state. If a policy is missing, corrupted, or if an internal evaluation error occurs, all traffic is blocked.
• Zero-Trust Transport: Stdio and network payloads are treated as potentially malicious. Lilith Zero enforces strictly framed Content-Length headers to prevent JSON smuggling and synchronization attacks.
• Type-Safe Invariants: Core security logic leverages the Rust type system to make invalid security states (e.g., unverified taint propagation) unrepresentable at compile time.

Core Capabilities

System Architecture

Lilith Zero functions as a standalone security boundary between the Agent (client) and the Tool Server (upstream).

graph TD
    subgraph "Client Environment"
        A[AI Agent / LLM] <-->|SDK| B[Lilith Zero Runtime]
    end

    subgraph "Lilith Zero Core (Rust)"
        B <--> Codec[Framed Codec]
        Codec <--> Coordinator[Session Coordinator]
        Coordinator <--> Policy[Policy Engine]
        Coordinator <--> Supervisor[Process Supervisor]
    end

    subgraph "Upstream Environment"
        Supervisor <--> Tool[MCP Tool Server]
    end

    style B fill:#f4f4f4,stroke:#333,stroke-width:2px
    style Tool fill:#f4f4f4,stroke:#333,stroke-width:2px

Component Specification

• Session Coordinator: An asynchronous actor based on the Tokio runtime, responsible for session state management and HMAC-signed token verification.
• Hardened Codec: A framing layer implementing LSP-style headers to ensure unambiguous message boundaries across stdio streams.
• Policy Engine: A deterministic evaluator that processes serialized policy definitions without the non-determinism of probabilistic models.

Implementation

1. Installation & Auto-Discovery

Option A: Python SDK
The Python SDK handles the entire lifecycle. It automatically downloads the correct Lilith Zero binary for your OS/Arch from GitHub Releases.

pip install lilith-zero

Option B: Shell Installer (Unix/macOS)

curl -sSfL https://badcompany.xyz/lilith-zero/install.sh | sh

Option C: PowerShell Installer (Windows)

irm https://badcompany.xyz/lilith-zero/install.ps1 | iex

No manual binary compilation is required. The installers ensure strict platform-matching execution.

2. Policy Configuration (policy.yaml)

Security boundaries are defined in a structured YAML schema.

Lethal Trifecta Protection

The "Lethal Trifecta" (Access Private Data + Access Untrusted Source + External Communication) is the most critical agentic risk. Lilith Zero can block this pattern automatically, without complex rule definitions.

Option A: Global Enforcement (Ops / CI)
Set LILITH_ZERO_FORCE_LETHAL_TRIFECTA=true in your environment. This overrides local policies and enforces protection globally.

Option B: Policy-Level (Dev)

protect_lethal_trifecta: true  # Enable automatic exfiltration blocking

resourceRules:
  - uriPattern: "file:///private/*"
    action: ALLOW
    taintsToAdd: [ACCESS_PRIVATE]
  - uriPattern: "http*"
    action: ALLOW
    taintsToAdd: [UNTRUSTED_SOURCE]

taintRules:
  - tool: curl
    action: ADD_TAINT
    tag: UNTRUSTED_SOURCE

# ... existing rules ...

When enabled, if a session acquires both ACCESS_PRIVATE and UNTRUSTED_SOURCE taints, any tool classified as EXFILTRATION or NETWORK (e.g., curl, wget, requests) is automatically blocked.

3. Configuration Reference

Lilith Zero is configured via environment variables and policy files.

4. Agent Integration

Lilith Zero integrates with standard agent architectures by wrapping the tool server invocation.

from lilith_zero import Lilith
from lilith_zero.exceptions import PolicyViolationError

async def main():
    # Automatic binary discovery and process management
    async with Lilith("python tools.py", policy="policy.yaml") as az:
        try:
            # Authorized call
            await az.call_tool("calculator", {"expression": "2+2"})
            
            # Blocked by Taint Tracking
            data = await az.call_tool("read_customer_data", {"id": "123"})
            await az.call_tool("export_analytics", {"data": data})
            
        except PolicyViolationError as e:
            # Handle security interception
            print(f"Policy Violation: {e}")

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

5. Observability & Auditing

Audit Logs
Lilith Zero emits cryptographically signed audit logs to stderr (visible in agent logs).

Format: [AUDIT] <HMAC-SHA256 Signature> <JSON Payload>

Example:

[AUDIT] 8f3...a1b {"session_id": "uuid", "event": "Decision", "decision": "DENY", "details": {...}}

This ensures non-repudiation. Even if the log file is tampered with, the signature will fail verification against the session's ephemeral secret (or a configured shared secret).

Telemetry Grouping
Lilith Zero integrates directly with the lilith-telemetry system. When run with a Flock telemetry link (e.g., --telemetry-link), it enables cross-process span propagation. This allows all multi-tool interactions originating from a single LLM reasoning step to be accurately traced and grouped into unified, logical context spans within your dashboard.

6. Examples

Full integration examples are available in the examples/ directory:

• LangChain Agent: Complete ReAct agent demonstrating static rules, taint tracking, and logic exceptions.
• ReAct Agent: Minimalist demonstration of security middleware.

Development and Verification

Build Requirements

For full setup instructions, see docs/development.md.

• Rust: Managed via rustup (Stable + Nightly for Miri).
• Python: Managed via uv (3.10+).
• Supported Platforms: Linux, Windows, macOS.

Technical Constraints

• Max Message Size: 10 MB (JSON-RPC payloads exceeding this are dropped to prevent DoS).
• Supported Platforms: Windows (x64), Linux (x64, ARM64), macOS (ARM64).

Security & Assurance

Lilith Zero is engineered with high-assurance rigor, employing a multi-layered verification strategy to ensure mathematical correctness and runtime invulnerability.

View full SECURITY.md for detailed proof harnesses and audit logs.

Performance Benchmarks

Lilith Zero adds negligible overhead to agent interactions, optimized for high-frequency trading (HFT) grade latency.

Micro-Benchmarks (Core Logic):

• Codec Decoding: ~247 ns / message (Framing + parsing)
• Policy Evaluation: ~660 ns / rule (Deterministic logic check)

End-to-End Latency (Windows 10/11, Release Build):

• RPC Overhead (p50): < 0.5ms (Transport + Verification)
• Startup Latency: ~15ms (Process spawn + Handshake)
• Memory Footprint: ~4MB (RSS)
• Throughput: > 1.5M validations/sec (Internal capability)

License

Lilith Zero is released under the Apache License, Version 2.0. Refer to the LICENSE file for the full text.