lilith-zero

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 23 Open GitHub ↗

⚸ Lilith Zero - Security Middleware for MCP tool calls written in Rust.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Lilith-Zero

**Deterministic Security Middleware for MCP tool calls written in Rust.**

<br/>

[![CI](https://github.com/BadC-mpany/lilith-zero/actions/workflows/ci.yml/badge.svg)](https://github.com/BadC-mpany/lilith-zero/actions)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/BadC-mpany/lilith-zero/main/LICENSE)
[![Version](https://img.shields.io/badge/Version-0.2.2-green.svg)](https://github.com/BadC-mpany/lilith-zero/releases)

<br/>

![Linux](https://img.shields.io/badge/Linux-FCC624?style=flat&logo=linux&logoColor=black)
![Windows](https://img.shields.io/badge/Windows-0078D6?style=flat&logo=microsoft-windows&logoColor=white)
![macOS](https://img.shields.io/badge/macOS-FFD700?style=flat&logo=apple&logoColor=black)

</div>

Lilith Zero is a high-performance security runtime that mitigates data exfiltration and unauthorized tool invocation in LLM-based agent systems. It interposes at the transport layer, enforcing security invariants through deterministic policy evaluation and strictly framed execution.

OS, framework, and language agnostic: uniform security primitives across all implementation environments.

---

## Technical Fundamentals

- **Fail-Closed Architecture**: defaults to `DENY`. Missing policy, parse error, or internal fault → all traffic blocked.
- **Zero-Trust Transport**: stdio and network payloads treated as potentially malicious; strict `Content-Length` framing prevents JSON smuggling.
- **Type-Safe Invariants**: Rust type system makes invalid security states (e.g. unverified taint propagation) unrepresentable at compile time.
- **Deterministic Classification**: tool classes are declared explicitly in policy; no runtime heuristics.

---

## Core Capabilities

---

## System Architecture

```mermaid
graph LR
    Agent["AI Agent / LLM"] -->|stdio| Codec

subgraph lz["Lilith Zero &lpar;Rust&rpar;"]
        Codec["Hardened Codec"] --> Coord["Session Coordinator"]
        Coord --> Policy["Policy Engine"]
        Coord --> Taint["Taint Tracker"]
        Coord --> Audit["Audit Logger"]
        Coord --> Proc["Process Supervisor"]
    end

Proc -->|stdio| ToolLocal["MCP Server &lpar;local&rpar;"]
    Coord -.->|Streamable HTTP| ToolRemote["MCP Server &lpar;remote&rpar;"]
```

The agent always communicates with Lilith Zero over stdio: the transport setting only changes how Lilith Zero connects *upstream*: spawning a local child process (stdio mode) or acting as an HTTP client to a remote MCP server (Streamable HTTP mode). Policy enforcement, taint tracking, and audit logging apply in both cases.

### Components

---

## Agent Integrations

All adapters share the same policy engine, taint tracker, and audit layer: only the I/O contract differs.

### Claude Code

Hooks fire on every tool call. Lilith reads the JSON event from stdin and signals via exit code: `0` = allow, `2` = block.

**`.claude/settings.json`** (project) or `~/.claude/settings.json`:
```json
{
  "hooks": {
    "PreToolUse":  [{"matcher": "", "hooks": [{"type": "command", "command": "lilith-zero hook --policy /path/to/policy.yaml"}]}],
    "PostToolUse": [{"matcher": "", "hooks": [{"type": "command", "command": "lilith-zero hook --policy /path/to/policy.yaml"}]}]
  }
}
```

See `scripts/hooks.json` for a ready-to-use template.

### GitHub Copilot CLI

Copilot reads `{"permissionDecision":"allow"|"deny"}` from stdout; exit code is always `0`.

**`~/.config/github-copilot/hooks.json`**:
```json
{
  "preToolUse":  {"command": "lilith-zero hook --format copilot --event preToolUse --policy /path/to/policy.yaml"},
  "postToolUse": {"command": "lilith-zero hook --format copilot --event postToolUse --policy /path/to/policy.yaml"}
}
```

See `examples/gh-copilot/` for complete policy examples (`bash`, `view`, `rg`, `glob`, `report_intent`).

### VS Code Copilot Sidebar

Event type is inferred from the payload: no `--event` flag required.

**`.vscode/settings.json`**:
```json
{
  "github.copilot.chat.agent.hooks": {
    "PreToolUse":  {"command": "lilith-zero hook --format vscode --policy /path/to/policy.yaml"},
    "PostToolUse": {"command": "lilith-zero hook --format vscode --policy /path/to/policy.yaml"}
  }
}
```

See `examples/vscode/` (`editFiles`, `runTerminalCommand`, `#fetch`, `#codebase`, MCP tools).

### OpenClaw

OpenClaw uses stdio MCP only. Wrap each MCP server via `lilith-zero run` in `~/.openclaw/openclaw.json`:

```json
{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "lilith-zero",
        "args": ["run",
                 "--upstream-cmd", "npx -y @modelcontextprotocol/server-filesystem /home/user/projects",
                 "--policy", "~/.lilith/openclaw-policy.yaml"],
        "transport": "stdio",
        "env": {"LILITH_ZERO_PIN_FILE": "~/.lilith/pins/filesystem.json"}
      }
    }
  }
}
```

See `examples/openclaw/` for `policy-base.yaml` (conservative) and `policy-paranoid.yaml` (read-only).  
The `examples/openclaw/CVE-COVERAGE.md` maps all 139 OpenClaw advisories to the corresponding lilith-zero controls.

> **Forward-looking:** once OpenClaw ships its hook system ([#60943](https://github.com/openclaw/openclaw/issues/60943)), replace the `run` wrapper with:  
> `lilith-zero hook --format openclaw --policy ~/.lilith/openclaw-policy.yaml`

### Copilot Studio Webhook

REST server implementing the Microsoft Copilot Studio External Threat Detection API.

```bash
# Dev: no auth
lilith-zero serve --bind 127.0.0.1:8080 --auth-mode none --policy policy.yaml

# Production: Microsoft Entra ID (RS256)
lilith-zero serve --bind 0.0.0.0:8443 \
  --auth-mode entra \
  --entra-tenant-id <TENANT_GUID> \
  --entra-audience https://security.contoso.com \
  --policy policy.yaml
```

Endpoints: `POST /validate` (health), `POST /analyze-tool-execution` (policy evaluation).

### Session Persistence

Hook mode maintains taint state **across binary restarts** within a session. State is stored in `~/.lilith/sessions/<session-id>.json` under a cross-process file lock (`LockFileEx` on Windows, `flock` on Unix). Taints accumulated in one tool call are visible to the next invocation.

---

## Transports

### stdio (default)
```bash
lilith-zero run --upstream-cmd "python mcp_server.py" --policy policy.yaml
```
Wraps a child MCP server process. Lilith Zero sits between agent and server on stdin/stdout.

### Streamable HTTP (MCP 2025-11-25)
```bash
lilith-zero run --transport http --upstream-url http://localhost:9000/mcp --policy policy.yaml
```
Connects to a remote MCP server; no child process spawned.

---

## SDKs

### Python
```bash
uv add lilith-zero          # auto-downloads the correct binary for your platform
# or: pip install lilith-zero
```
```python
from lilith_zero import Lilith

async with Lilith("python mcp_server.py", policy="policy.yaml") as lz:
    result = await lz.call_tool("read_file", {"path": "/data/report.txt"})
```

### TypeScript / Node.js
```bash
bun add @badcompany/lilith-zero
# or: npm install @badcompany/lilith-zero
```
```typescript
import { Lilith } from "@badcompany/lilith-zero";

await using lz = new Lilith({ upstream: "bun mcp_server.ts", policy: "policy.yaml" });
const result = await lz.callTool("read_file", { path: "/data/report.txt" });
```

---

## Setup

### 1. Install

**Python SDK** (manages the binary automatically):
```bash
uv add lilith-zero
# or: pip install lilith-zero
```

**Shell (Unix/macOS)**:
```bash
curl -sSfL https://badcompany.xyz/lilith-zero/install.sh | sh
```

**PowerShell (Windows)**:
```powershell
irm https://badcompany.xyz/lilith-zero/install.ps1 | iex
```

### 2. Write a policy

```yaml
id: my-policy
customer_id: my-org
name: "My Agent Policy"
version: 1

protect_lethal_trifecta: true   # auto-blocks ACCESS_PRIVATE + UNTRUSTED_SOURCE → EXFILTRATION

# Declare tool classes explicitly: Lilith performs no heuristic inference.
tool_classes:
  curl:         [EXFILTRATION]
  send_email:   [EXFILTRATION]

static_rules:
  read_file:   ALLOW
  calculator:  ALLOW
  bash:        DENY

taint_rules:
  - tool: read_file
    action: ADD_TAINT
    tag: ACCESS_PRIVATE

- tool: curl
    action: ADD_TAINT
    tag: UNTRUSTED_SOURCE

resource_rules: []
```

`protect_lethal_trifecta: true` injects a rule that blocks any tool declared as `EXFILTRATION` class when both `ACCESS_PRIVATE` **and** `UNTRUSTED_SOURCE` taints are simultaneously active. Tool class assignments are always explicit in the policy: no name-based inference.

### 3. Wire it to your agent

```bash
# Claude Code: one-liner setup
echo '{"hooks":{"PreToolUse":[{"matcher":"","hooks":[{"type":"command","command":"lilith-zero hook --policy $(pwd)/policy.yaml"}]}]}}' \
  > .claude/settings.json
```

### 4. Environment variables

---

## Observability

### Audit Logs

Every decision: ALLOW and DENY: emits a tamper-evident JSONL line to stderr:

```
[AUDIT] <HMAC-SHA256-base64url> {"session_id":"…","timestamp":…,"event_type":"Decision","details":{"decision":"DENY","tool_name":"curl"}}
```

Verifying the signature against the session key proves the log was not altered after the fact.

### lilith-telemetry

`lilith-telemetry` is a companion sidecar that aggregates Lilith Zero security events into structured, distributed traces. It implements the `TelemetryHook` trait and routes spans through a configurable Flock dispatch pipeline.

```bash
# Run with telemetry enabled (Flock link from your dashboard)
lilith-zero-telemetry run \
  --upstream-cmd "python mcp_server.py" \
  --policy policy.yaml \
  --flock-link "lilith://collector:7700?key_id=0x<hex>"
```

Each tool call produces a parent span with child spans for codec framing, policy evaluation, and the upstream call. Decisions are tagged `LEVEL: ROUTINE` (allow) or `LEVEL: CRITICAL` (deny/violation):

```
SESSION: 189e9a3a…  TRACE: 189e9a44…  SPAN: 189e9a44…  LEVEL: CRITICAL  KIND: Server
MSG: Blocked tool web_search: Web search prohibited after database access (exfiltration prevention)
```

Multi-tool interactions from a single LLM reasoning step are grouped into unified trace spans, enabling precise audit of the full agent decision chain.

---

## Security & Assurance

[View full SECURITY.md](SECURITY.md) for proof harnesses and audit logs.

---

## Performance

**Micro-benchmarks (core logic):**
- Codec decoding: **~247 ns** / message
- Policy evaluation: **~660 ns** / rule

**End-to-end (Windows, release build, p50):**
- RPC overhead: **< 0.5 ms**
- Startup: **~15 ms** (process spawn + handshake)
- Memory: **~4 MB** RSS
- Throughput: **> 1.5 M** validations/sec

---

## Development

See **[docs/development.md](docs/development.md)** for full setup.

```bash
# Rust core (from lilith-zero/)
cargo build && cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings

# Python SDK (from sdk/)
uv venv && uv pip install -e ".[dev]" && uv run pytest tests -v
```

---

## License

Apache License, Version 2.0. See [LICENSE](LICENSE).

lilith-zero

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README