aegis-crew

A multi-agent analyst crew — Researcher, Writer, Reviewer on LangGraph — wrapped in a defence-in-depth security envelope. Agents cannot import their tools: every tool call crosses a real MCP boundary and is capability-checked by a zero-trust CapabilityBroker, input and output pass deterministic OWASP LLM Top-10 guardrails, and the one side-effecting action (publishing the report) is held at a human-in-the-loop gate. The thesis: the security layer is constant and the orchestrator is swappable — CrewAI, AutoGen, BeeAI, Microsoft Agent Framework, and Google ADK all drive the same secured tools through the same broker.

On top of the always-on envelope sit four opt-in security tiers, each independently switchable and composable:

Everything is testable without an API key: 351 deterministic safety tests cover every control with negative-control discipline, and a separate live tier sends real adversarial probes through a real model.

Start with the design rationale: docs/ARCHITECTURE-DEEP-DIVE.md — a full walkthrough of the architecture, the trade-offs, and the threat model behind it.

Quickstart

This project requires uv: [tool.uv] override-dependencies resolves a metadata-only json-repair pin conflict that plain pip cannot apply, so pip install fails where uv sync succeeds.

uv sync --extra dev
cp config.example.toml config.toml    # edit provider/security settings
cp .env.example .env                  # set ANTHROPIC_API_KEY for live runs

# Key-free demo — scripted provider, full pipeline, no network:
uv run aegis run "grid storage policy" --provider fake --auto-approve

# Deterministic safety suite (no API key):
uv run --extra dev pytest tests/safety -q

The report lands in out/report.md, written only after the HITL gate approves.

Live interactive run

uv run aegis run "renewable energy subsidies" --provider anthropic

The crew runs against the real model. When the reviewer approves the draft, the run parks at the HITL gate and prints the proposed report. You are prompted to approve (y) or reject (n) before out/report.md is written.

Providers: fake (scripted, deterministic), anthropic, ollama, plus first-party openai, gemini, mistral, and watsonx adapters. config.toml keys of interest:

[provider]
default = "anthropic"   # anthropic | ollama | fake | openai | gemini | mistral | watsonx
anthropic_model = "claude-sonnet-4-6"

[security]
output_dir = "out"
corpus_dir = "corpus"
reflexion_max_retries = 2

The kb_search tool reads .md/.txt documents from corpus/ (example policy documents ship in the repo).

Standalone MCP tool server (stdio)

uv run aegis serve-mcp

Starts the FastMCP tool server on stdio. Any MCP-compatible client (e.g. Claude Desktop) can connect and call the three tools (kb_search_tool, read_doc_tool, publish_report_tool) through the zero-trust broker.

Note on retrieval quality: MockEmbedding (offline, deterministic) is the default so all tests and the --provider fake demo work without API keys. Retrieval is illustrative in this mode — pass a real embedding model via build_index(embed_model=...) for production-grade semantic search.

Related MCP server: production-grade-mcp-agentic-system

Architecture

User topic
    |
    v
[scan_input / LLM01]          ← guardrail: prompt-injection / jailbreak
    |
    v
  StateGraph (LangGraph)
  ┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │  START → researcher ──────────────────────────────────► │
  │              (ReAct loop)                                │
  │                  │ MCP boundary (MCPToolClient)          │
  │                  │   └── CapabilityBroker.authorize()    │
  │                  │   └── check_tool_args / LLM06        │
  │                  ▼                                       │
  │              writer                                      │
  │                  ▼                                       │
  │              reviewer  ──"retry"──► writer               │
  │              (Reflexion)                                 │
  │                  │ "ok"                                  │
  │                  ▼                                       │
  │           hitl_gate  ── reject ──► END                  │
  │           (interrupt())                                  │
  │                  │ approve                               │
  │                  ▼                                       │
  │           publisher  ── MCP ──► publish_report_tool      │
  │                  │   └── check_egress / LLM02           │
  │                  ▼                                       │
  │                 END                                      │
  └──────────────────────────────────────────────────────────┘
    |
    v
  out/report.md    (written only after HITL approval)

Key components:

Full threat analysis: docs/THREAT_MODEL.md (STRIDE per component).

The always-on envelope

• Zero-trust CapabilityBroker (src/aegis/security/zero_trust.py:45) — every tool call is explicitly authorized against a per-tool capability set; denials are recorded in the AuditLog (zero_trust.py:26). No tool runs without explicit allowance.

• OWASP LLM Top-10 guardrails (src/aegis/security/guardrails.py) — four guards mapped to four controls:

  • scan_input → LLM01 (Prompt Injection / Jailbreak)

  • check_egress → LLM02 (Sensitive Information Disclosure)

  • validate_output → LLM05 (Improper Output Handling)

  • check_tool_args → LLM06 (Excessive Agency)

  • Full mapping: docs/OWASP_MAPPING.md

• Human-in-the-loop gate (src/aegis/graph.py:257) — LangGraph interrupt() parks the run before the one side-effecting tool (publish_report_tool). A rejected decision routes to END without writing any file.

• Audit log (src/aegis/security/zero_trust.py:26) — all broker allow/deny decisions are recorded with tool, action, target, verdict, and reason.

• MCP choke point — tools are exclusively reachable via the MCPToolClient boundary; agents have no direct function references. The broker enforces authorization at the server side of that boundary.

The spine files behind these controls are byte-frozen: tests/safety/test_no_security_regression.py guards them with a git-diff check plus SHA-256 digest pins, so every later capability had to compose on top of the controls instead of editing them. The frozen guardrails are also mutation-tested — see docs/mutation-testing.md.

The four security tiers

Rule of Two (session policy, --rule-of-two)

Meta's "Agents Rule of Two": an agent session may combine at most two of [A] untrustworthy inputs, [B] sensitive-system/private-data access, [C] state-change/external communication. Needing all three means the session must not run autonomously — human approval is the mandated minimum.

aegis enforces this mechanically: a SessionLedger accumulates factors as the broker authorizes calls (read→B, write→C, network→A+C, unknown→all three, fail-closed; carve-outs are explicit declarations), and RuleOfTwoBroker (a drop-in subclass of the frozen CapabilityBroker) denies, at authorize-time, any call whose factors would complete the triple without a human grant. The HITL gate's approval is the grant: approving the publish unlocks EXTERNAL_WRITE for the session; rejecting leaves the third factor locked even if graph routing were bypassed. Every decision lands in the same audit log.

Enforcement is in-process: in aegis run (in-memory MCP) the server and graph share one broker and one ledger, so enforcement is end-to-end. In serve-mcp stdio mode the ledger lives inside the server process: tool-side factor accumulation and denial are enforced there, but graph-side marks and HITL grants cannot reach it — a cross-process grant channel is future work, not claimed. Classification is structural, not semantic: Rule of Two bounds blast radius; it does not detect injection — the guardrails do that, and neither subsumes the other.

Dual-LLM quarantine (semantic tier, --quarantine)

"Design Patterns for Securing LLM Agents against Prompt Injections" (arXiv:2506.08837) states the principle: once an agent has ingested untrusted input, it must be impossible for that input to trigger consequential actions. --quarantine turns the crew into the paper's Dual LLM pattern (with CaMeL as the data-flow lineage):

• the privileged researcher keeps its tools but never sees untrusted bytes — tool results are parked in a QuarantineStore and appear to the model only as opaque refs (⟦Q1⟧ from kb_search (1204 chars)) plus validated signals;

• a quarantined model (never given tools) reads the untrusted text and answers only schema-validated primitives (bool / bounded int / fixed choice); a reply that fails strict validation is re-asked once, then rejected fail-closed — free text never crosses back;

• the writer and reviewer see the content but are quarantined roles: structurally tool-less (a regression-pinned property, not an accident);

• the publisher boundary is unchanged: HITL + broker + egress guards + Rule of Two when enabled.

The enforced, tested invariant: no provider call ever carries both tool access and untrusted bytes. Default-off; [security] quarantine_provider optionally routes the quarantined model to a cheaper local provider.

Honesty notes, verbatim from the design review: "Quarantine bounds capability and data flow, not signal truthfulness: extracted signals are derived from untrusted content and remain adversary-influenceable. An attacker can lie to the relevance check; they cannot make the privileged model see their text or invoke a tool with it." "The quarantined model can still be prompt-injected. The guarantee is that injection there is inconsequential by construction: the quarantined call carries no tool access, and its only output channel is a schema-validated primitive — free text never crosses back to the privileged side." "Writer and reviewer see untrusted content by design; they are quarantined roles — structurally tool-less. The consequential boundary remains the publisher path (HITL + broker + egress guards + Rule of Two when enabled). Detection (guardrails) and structure (quarantine) are complementary; neither subsumes the other."

Stretch rung — --quarantine-mode plan (CTE-lite): the privileged model emits a full typed plan (pydantic-validated verbs: search / read / extract) from the topic alone, before any untrusted data exists; a deterministic executor walks it through the same broker-checked MCP path. Honest label, verbatim: "This is Plan-Then-Execute with typed steps and capability-checked execution (CTE-lite). Full CaMeL-style data-flow labels on variables are future work, not claimed."

Sandboxed tool execution (sandbox tier, --sandbox)

uv run aegis run "renewable energy subsidies" --sandbox --provider fake --auto-approve

OWASP ASI02 ("Tool Misuse") calls for two layers: the broker that authorizes a tool call, and a runtime boundary that survives the broker being wrong. aegis run --sandbox adds the second layer: the serve-mcp tool server is launched inside a macOS sandbox-exec (Seatbelt) subprocess under a caps-derived deny-by-default profile (security/sandbox.py, SandboxPolicy.from_caps) — filesystem access is scoped to exactly the read/write paths the broker's capabilities declare, and network is denied outright. The broker remains the policy decision point inside that subprocess; the sandbox bounds the blast radius if the broker is wrong or the tool runtime is compromised.

The launch writes two inspectable artifacts under out/sandbox/: profile.sb (the actual Seatbelt profile text) and config.toml (the secrets-free config the sandboxed server reads). Only the profile's sha256_16 enters the shared AuditLog as a sandbox/launch record (security/sandbox.py:launch_audit_record) — the content lives on disk for inspection, not duplicated into the audit trail.

--sandbox composes with --quarantine and --auto-approve. It refuses --rule-of-two: with --sandbox, tool-side capability decisions are made and audited inside the sandboxed server process, and Rule of Two's session ledger — an in-process object — cannot span that process boundary, so the combination is rejected at the CLI rather than silently downgraded to graph-side marks only.

Honesty guards, verbatim from the design review:

1. "Broker authorizes, sandbox contains. The broker remains the policy decision point; the sandbox bounds the blast radius of a tool-runtime compromise or a broker misconfiguration. Neither subsumes the other, and neither makes tool OUTPUT trustworthy — untrusted-content handling remains the quarantine and guardrail tiers' job."

2. "sandbox-exec is deprecated as a public CLI but is the OS-shipped Seatbelt mechanism that still underpins macOS app sandboxing. This tier is best-effort local containment on a developer machine, not a certified security boundary and not E2B: no microVM, no snapshotting, no network allowlisting — egress is simply denied."

3. "The sandbox tier is darwin-only and fails closed: on any other platform --sandbox is an error, never a silent downgrade to unsandboxed execution. A Linux backend (namespaces/containers) is future work."

Behavioral baseline (egress drift tier, --baseline)

uv run aegis baseline-fit ./known-good-reports -o profile.json
# config.toml: [security] baseline_profile = "profile.json"
uv run aegis run "renewable energy subsidies" --baseline --provider fake --auto-approve --config config.toml

security/baseline.py wires portcullis's BaselineMonitor into the publisher boundary as an optional, default-off egress tier, run after check_egress and before the MCP publish call: the outgoing report is embedded and scored against a profile fitted offline on known-good reports. This is a behavioral tier, not a content tier — it complements the existing guardrail and egress checks, it does not replace them.

Fit → enforce lifecycle: aegis baseline-fit <known-good-dir> [-o profile.json] [--threshold-percentile 95.0] fits a profile on *.md/*.txt reports and saves it as JSON; [security] baseline_profile = "profile.json" in the config points aegis run --baseline at it. Needs the [baseline] extra (pip install 'aegis-crew[baseline]'), lazy-imported inside security/baseline.py so the core install and the deterministic safety suite never need it.

Warn vs. block: --baseline alone runs in warn mode — drift is recorded on the audit trail and the run still publishes. --baseline-mode block refuses an off-profile publish with a content-free BLOCKED: ... critique, same shape as an egress denial. Audit records land on the same ledger as every other tier: baseline / egress / report.md / allow|deny, with reasons carrying distance/threshold/destination — never report text.

Composition: --baseline composes with --rule-of-two, --quarantine, and --sandbox — verified end-to-end by tests/safety/test_baseline.py::test_baseline_composes_with_rule_of_two, ::test_baseline_composes_with_quarantine, and ::test_baseline_composes_with_sandbox respectively (the monitor and embedder run in the graph process; --sandbox contains a disjoint layer, the serve-mcp subprocess).

Honesty guards, verbatim from the design review:

1. "A behavioral baseline is anomaly detection, not attack detection: it flags conversations that drift from the fitted profile. A novel-but-benign topic can flag; an attack phrased on-profile will not. It bounds drift — it does not detect prompt injection or PII. Run it alongside the content gate, never instead of it."

2. "Fail posture is fail-closed with no override exposed: an embedder failure blocks the publish even in warn mode. Errors never downgrade to a warning silently."

3. "HashingEmbedder is deterministic and content-sensitive but NOT semantic: it demonstrates the wiring and the fit/enforce lifecycle, not detection quality. Hand a real embedding model to LlamaIndexEmbedder for any real deployment, and fit and enforce with the SAME embedder — profiles are embedder-specific."

The default no-key path uses HashingEmbedder (stdlib token-hash bag, unit vector) — deterministic and content-sensitive, but not semantic (guard 3 above). LlamaIndexEmbedder adapts any llama-index BaseEmbedding for a real deployment. Fit and enforce must use the same embedder: profiles are embedder-specific.

Capabilities

Everything below composes on the frozen spine; each item names the module that implements it and the test or CLI command that exercises it.

Broker & policy

• Zero-trust broker + audit log (security/zero_trust.py) — deny-by-default per-tool capability sets; every allow/deny audited. Exercised by tests/safety/test_zero_trust.py.

• Rule-of-Two session ledger (security/rule_of_two.py, security/policy.py) — factor accumulation + authorize-time denial, HITL approval as the human grant. Exercised by tests/safety/test_rule_of_two.py.

• Sandbox policy derivation (security/sandbox.py) — a Seatbelt profile generated from the broker's capability set, deny-by-default, network denied. Exercised by tests/safety/test_sandbox.py.

• HITL gate (graph.py, security/hitl.py) — interrupt() before the one side effect; resume via Command(resume=...). Exercised by tests/safety/test_graph_hitl.py.

Guardrails & spine

• OWASP LLM Top-10 guards (security/guardrails.py) — LLM01/02/05/06, deterministic, mutation-tested (docs/mutation-testing.md). Exercised by tests/safety/test_guardrails.py with negative controls.

• Dual-LLM quarantine (security/quarantine.py, security/plan_execute.py) — the semantic tier above. Exercised by tests/safety/test_quarantine.py.

• Behavioral baseline (security/baseline.py) — the egress drift tier above. Exercised by tests/safety/test_baseline*.py (skips cleanly without the [baseline] extra).

• NeMo Guardrails integration (security/nemo_rails.py) — an LLMRails input rail delegating to the frozen scan_input; blocks injection with no model in the deterministic test, and with a live Ollama in the live test.

• Adversarial hardening (adversarial/defense.py) — prompt-space evasion bench against the LLM01 guardrail; measured attack success rate 0.78 bare → 0.00 with harden (obfuscation-folding normalize), guardrails.py untouched. CLI: aegis adversarial bench.

• MCP tool-poisoning defense (mcp/tool_scan.py) — vet_tools scans advertised tool metadata for smuggled instructions; ToolPin/detect_rugpull catch post-approval description swaps. CLI: aegis mcp scan.

• Data-poisoning attack + detector (adversarial/poison.py) — plants a poisoned corpus doc and detects it by reusing the frozen LLM01 guardrail plus a duplication check. CLI: aegis adversarial poison-scan.

• Model-extraction attack + defense (adversarial/extraction.py) — a surrogate fit on victim queries; measured fidelity degradation 0.96 → 0.57 under the perturbation/budget defense.

Orchestration & interop

• The crew (graph.py, agents/) — ReAct researcher, writer, Reflexion reviewer with bounded retry, HITL publisher, on a LangGraph StateGraph.

• Swappable orchestrators (orchestrators/) — CrewAI, AutoGen, BeeAI, Microsoft Agent Framework, and Google ADK each drive the same secured MCP tools over the serve-mcp stdio contract via their native adapters; none re-implements a tool. Structural tests are model-free; live smoke tests run against local Ollama (qwen3:8b).

  uv run aegis run "grid storage policy" --orchestrator crewai   # | autogen | beeai

• Five orchestration topologies (topologies/) — supervisor, plan-and-execute (replan-on-failure), routing/handoffs, swarm (decentralized Command(goto=...)), and debate (judge sides with either debater), each a separate LangGraph over the same secured boundary. CLI: aegis topo run --pattern <name> TOPIC.

• A2A protocol (protocols/) — the crew is callable as a Google Agent2Agent agent (aegis serve-a2a) and can delegate to peers (aegis a2a-call); inbound messages are guardrail-scanned, outbound peer calls are deny-by-default and audited. Needs the [a2a] extra.

• Computer use (agents/computer_use.py, mcp/tools/browser.py) — a bounded perceive→decide→act loop over a gated Playwright BrowserTool; origins and action verbs are allowlisted, sensitive actions (e.g. submit) park at HITL. CLI: aegis browse URL TASK. Needs the [browser] extra.

• Evaluation harness (eval/harness.py) — aegis eval runs each task through the real crew and scores trajectory + safety-held + LLM-judge (deterministic StubJudge by default, --live for an Ollama judge); --metric tool-accuracy scores F1 over expected-vs-actual tool-call sets, and topology runs take a caller-supplied success predicate.

Memory & privacy

• Three-tier memory (memory/store.py) — episodic/semantic/scratch over SQLite; remember/recall are capability-checked through the same broker (memory paths are scoped under the run's output dir). Exercised by tests/safety/test_memory.py and the crew-wiring tests.

• Semantic fact store + consolidation (memory/semantic_store.py, memory/consolidate.py) — fact/preference store with dedup on (subject, predicate); consolidate() extracts durable facts from the episodic log and shrinks event volume while preserving knowledge. CLI: aegis memory facts.

• Context engineering (context/assembler.py) — ContextAssembler packs prioritized sections into a token budget, compressing lowest-priority first; counter and summarizer are dependency-injected, so it tests deterministically.

• PII redaction (privacy/redaction.py) — Redactor with redact and block policies. CLI: aegis privacy redact PATH.

• Differential privacy (privacy/dp_train.py) — a real Opacus DP-SGD micro-train reporting the spent budget (ε≈2.25, δ=1e-5; CPU — Opacus grad-sample hooks are MPS-incompatible). CLI: aegis privacy dp-train. Needs the [privacy] extra.

• Federated learning simulation (privacy/federated.py) — a labeled FedAvg simulation (honestly labeled: simulation, not a distributed deployment).

Supply chain & governance

• Artifact attestation (supplychain/provenance.py, supplychain/verify.py) — Ed25519 in-toto-style sign + verify-on-load; a tampered artifact is blocked before use. In-house local signing, NOT keyless sigstore. CLI: aegis attest, aegis verify.

• SBOM (supplychain/sbom.py) — CycloneDX-style SBOM for installed packages. CLI: aegis sbom.

• cosign signing (supplychain/cosign.py) — key-based blob sign/verify via the cosign CLI (key-based, NOT keyless-OIDC). CLI: aegis provenance cosign-sign.

• C2PA content provenance (provenance/c2pa.py) — signs images with a local self-signed ES256 credential; verify_image performs real tamper-detection on the manifest. CLI: aegis provenance c2pa-sign / c2pa-verify. Needs the [c2pa] extra.

• Governance gate (governance/policy_engine.py) — deny-by-default GovernanceGate over a NIST/ISO/EU-AI-Act risk register mapped to real callables; exits 1 on violation. Scope: an executable pre-flight / CI gate, not a runtime interceptor wired into graph.py. CLI: aegis govern check / report. Mapping: docs/AI_GOVERNANCE.md.

• ISO/IEC 42001 (governance/aims.py) — AimsGate binds 5 clauses to real callables and blocks on nonconformity. CLI: aegis govern aims-check. Mapping: docs/ISO_42001_AIMS.md.

• OWASP Agentic Top-10 map (security/agentic_map.py) — an executable threat→control map over 8 threats: 6 controlled, 2 documented gaps (T4 Resource Overload, T7 Cascading). CLI: aegis agentic map / check. Mapping: docs/OWASP_AGENTIC_TOP10.md.

• Executable attack trees (threat/attack_tree.py) — extends the STRIDE model; every leaf must resolve to a real aegis control or the test fails. CLI: aegis threat tree.

• Confidential computing (confidential/) — a design study, not built: I have no TEE hardware. An attestation-gated inference stage refuses to run without a TEE quote (aegis confidential attest exits nonzero here); nothing is simulated. Design doc: docs/CONFIDENTIAL_COMPUTING.md.

Optional extras

Heavy dependencies are lazy-imported inside the functions that need them, so the core install and the deterministic safety suite never require any of these:

pip install 'aegis-crew[a2a]'       # a2a-sdk — serve-a2a / a2a-call
pip install 'aegis-crew[browser]'   # playwright — browse (then: python -m playwright install chromium)
pip install 'aegis-crew[privacy]'   # torch + opacus — privacy dp-train
pip install 'aegis-crew[agentic]'   # agent-framework-core — the MAF orchestrator
pip install 'aegis-crew[adk]'       # google-adk[mcp] + litellm — the Google ADK orchestrator
pip install 'aegis-crew[rails]'     # nemoguardrails — the NeMo rail layer
pip install 'aegis-crew[c2pa]'      # c2pa-python — provenance c2pa-sign / c2pa-verify
pip install 'aegis-crew[baseline]'  # portcullis — the behavioral-baseline tier
pip install 'aegis-crew[platform]'  # convenience bundle: a2a + browser

Testing

Two tiers, intentionally separated:

Deterministic safety suite (no API key)

uv run --extra dev --extra baseline --extra adk pytest tests/safety -q

351 tests cover every security control, the guardrail negative-control discipline, HITL interrupt/resume, the MCP boundary, the zero-trust broker, all four tiers and their compositions, and CLI smoke. If a control is removed, its corresponding test fails — the suite is written as a regression harness, not just coverage. tests/safety/test_baseline*.py skip cleanly (via pytest.importorskip) when the [baseline] extra is not installed — the suite stays green either way.

Live adversarial red-team suite (requires ANTHROPIC_API_KEY)

ANTHROPIC_API_KEY=sk-... uv run --extra dev pytest -m redteam -q

Sends real adversarial probes through a live crew run:

• A corpus document with a planted prompt-injection comment must not cause scope escape.

• A jailbreak topic must be blocked at scan_input before the model or tools see it.

Further live markers: -m live (orchestrator + topology smoke against local Ollama) and per-provider markers (openai_live, gemini_live, mistral_live, watsonx_live).

Honest limitations

• Confidential computing is a design study — no TEE hardware here, so it ships as a fail-closed attestation gate plus a design doc; TEE-backed deployment is not claimed.

• The sandbox tier is darwin-only best-effort local containment (Seatbelt), not a certified security boundary; it fails closed on other platforms.

• Rule of Two in serve-mcp stdio mode enforces tool-side only; the cross-process HITL grant channel is future work, not claimed.

• Default retrieval and baseline embedders are illustrative — MockEmbedding and HashingEmbedder are deterministic, not semantic; swap in real embedding models for deployment.

• cosign signing is key-based, not keyless-OIDC; the Ed25519 attestation is in-toto-style, not sigstore.

• OWASP Agentic Top-10 coverage is 6 of 8 mapped threats, with T4 (Resource Overload) and T7 (Cascading) as documented gaps.

• The governance gates are pre-flight/CI gates, not runtime interceptors.

• FedAvg is a simulation, not a distributed deployment.

Project history

The wave-by-wave build ledger — what was added when, with the full capability-to-evidence tables — lives in docs/BUILD-NOTES.md.