AL-MUNAA — Collective Immune System for AI Agents

A local immunity layer that wraps any AI agent: it scans what the agent reads, verifies what it intends to do, and reviews what it outputs — then turns any detected attack into a signed "antibody" that protects other agents from the same attack without ever sharing the raw prompt, secrets, or conversation.

Track: Developer Tools · Built with: Codex (GPT-5.6-Sol) + GPT-5.6

Public demo: Watch the 2:43 narrated video on YouTube

Project owner: CARBONFLOWS.STORE | FARHAN ALMUTAIRI
Mobile: +966504211844 | Email: FAR7AN.O88@GMAIL.COM
Portfolio: portfolio.carbonflows.store | LinkedIn: linkedin.com/in/carbonflows | GitHub: Farhanward

---

The problem

Every agent that reads untrusted content — a README, a web page, tool output, an MCP response, or its own memory — can be hijacked by an indirect prompt injection into leaking secrets or running dangerous tools. Existing agent firewalls filter a single agent's prompts. They do not let a fleet of agents share what they learned about a live attack, because sharing usually means shipping the raw malicious text (and often the secrets caught alongside it).

What AL-MUNAA does

One pipeline, one decision, one signed audit trail:

Untrusted content
      │
      ▼  ① input & memory scan        (almunaa)      ── prompt injection, exfiltration, jailbreak
      ▼  ② antibody match             (NEW)          ── blocks KNOWN threats & mutated variants, cross-agent
      ▼  ③ action gate ALLOW/REVIEW/BLOCK (aegis)    ── policy + dangerous-command scan
      ▼  ④ output verification        (almunaa)      ── secret / PII leak before it leaves
      ▼  ⑤ signed audit event + privacy-safe antibody

Gray/ambiguous cases are escalated to GPT-5.6 for a structured intent analysis (JSON: intent, risk path, verdict, confidence). The final decision stays governed by auditable policy — the model advises, it is never the sole point of trust.

The novelty — Threat Antibody Protocol

When an attack is detected, AL-MUNAA does not store or share the raw text. It builds a Threat Antibody:

• a mutation-resistant fingerprint — up to 512 HMAC-hashed, normalized character k-gram shingles, so a reworded/padded variant of the same attack still matches;
• a precision-first dual matcher — legacy Jaccard stays at 0.30, while a stricter containment gate at 0.35 detects a retained attack payload surrounded by padding;
• Trust Envelope v2 — every security-relevant field is canonicalized and signed, including publisher, id, issue/expiry times, schema version, and pinned key_id;
• a Trusted Publisher Registry — consumers explicitly pin publisher keys, support overlapping rotation, and never trust a public key carried by the envelope itself;
• Unicode hardening — NFKC plus a small versioned homoglyph map catches the visible Cyrillic mutation used in the demo without claiming complete Unicode coverage;
• categorical metadata — injection type, entry vector, target tool, severity;
• an Ed25519 signature — a second agent verifies authenticity before trusting it.

Because the fingerprint is a set of keyed hashes, the raw prompt, secrets, and PII are not recoverable from the antibody. Agents in the same trust family share immunity, not data. This is what makes "collective immune system" a real mechanism, not a slogan.

Quickstart (no API key needed)

Requires Python 3.10+ (cryptography is the only runtime dependency).

Supported platforms: Windows 10/11, macOS, and Linux on CPython 3.10 or newer. The core demo and all deterministic tests run offline; an OpenAI API key is needed only to reproduce the optional live GPT-5.6 evidence paths.

pip install cryptography          # or: pip install -e .
python demo/run_demo.py

The installed wheel also carries a self-contained success gate, so it does not depend on repository-only demo files:

pip install ".[dev]"
pytest -q
python -m munaa_immune            # or: munaa-demo

Judges can test the packaged release without rebuilding from source:

pip install https://github.com/Farhanward/al-munaa/releases/download/v0.1.1/munaa_immune-0.1.1-py3-none-any.whl
python -m munaa_immune

You will see, end-to-end from a fresh checkout:

1. Agent A reads a poisoned README → BLOCK, an antibody is minted.
2. Agent A tries the shell command the injection wanted → BLOCK at the action gate.
3. The exported antibody is shown to contain no raw text (privacy check).
4. Agent B explicitly pins Agent A in its Registry, imports the v2 envelope using the Registry key, then receives a Cyrillic homoglyph mutation → BLOCK via the strongest antibody match, before full re-analysis.
5. A benign task passes ALLOW (no over-blocking).
6. GPT-5.6 gray-case analysis is shown (recorded fixture — keyless).

Final gate report (demo/demo_report.json):

{ "blocked": true, "antibody_created": true, "second_agent_blocked": true, "benign_allowed": true }

Reproducible calibration and false-positive control

The thresholds are measured, not guessed. The checked-in synthetic matrix contains four close attack mutations (padding, leetspeak/case, markup, and the demo mutation) plus five benign hard negatives, including defensive security prose that shares attack vocabulary. It contains no real user prompt, credential, or secret.

python scripts/calibrate_antibody.py

Matcher	TP / FN	FP / TN	Precision	Recall	Demo margin
Legacy: capped Jaccard 0.30, 256 hashes	3 / 1	0 / 5	1.00	0.75	0.3264 - 0.30 = 0.0264
Calibrated: Jaccard 0.30 or containment 0.35, 512 hashes	4 / 0	0 / 5	1.00	1.00	0.4974 - 0.35 = 0.1474

The calibrated matrix has a minimum attack margin of 0.0579 and a minimum benign margin of 0.1301. Repeating all nine cases across 64 deterministic synthetic family keys produced 576 evaluations with zero fixture errors. These are small synthetic calibration results, not a claim of production-wide recall or zero false positives.

SDK

from munaa_immune import Guard

guard = Guard(
    family="acme", family_key=b"shared-family-secret",
    workdir="./agent-a", publisher="agent-a",
)
other_guard = Guard(
    family="acme", family_key=b"shared-family-secret",
    workdir="./agent-b", publisher="agent-b",
)

guard.inspect_input(untrusted_text, source="readme")          # ① + ②
guard.before_tool_call(tool="shell", command=cmd, cwd=".")    # ③
guard.after_model_output(model_reply)                          # ④

# collective immunity
antibodies = guard.export_antibodies()                         # signed, privacy-safe
other_guard.registry.register(guard.publisher, guard.public_key_pem)  # explicit trust
result = other_guard.import_antibody(antibodies[0])             # ImportResult
assert result.accepted and result.reason == "accepted"

The exported v2 envelope contains key_id, never a self-authenticating public_key. Imports fail fast with auditable reasons such as schema, expired, future_dated, untrusted_publisher, bad_signature, foreign_family, and replay.

Enabling live GPT-5.6

The gray-case analyzer and defensive vaccine generator use GPT-5.6 through the Responses API when a key is present; otherwise they use deterministic fixtures so judges can run the core demo offline. The live evidence runner uses a synthetic canary and an in-memory sink, never a production credential or a network exfiltration endpoint.

pip install "openai>=1.40"
# Set OPENAI_API_KEY through your environment or secret manager first.
$env:MUNAA_GPT_MODEL = "gpt-5.6-sol"
$env:MUNAA_AGENT_PROFILE = "controlled_runbook"
python examples/real_gpt56_agent.py

Verified live evidence from 18 July 2026:

• Neutral indirect-injection profile: GPT-5.6 called no tools, so the result is recorded honestly as inconclusive for the action gate (docs/GPT56_NEUTRAL_RESULT.json).
• Authorized unsafe-runbook profile: unprotected read=1/sink=1; protected guard_blocks=1/read=0/sink=0; five API responses, estimated $0.014685 (docs/GPT56_LIVE_RESULT.json).
• In-product gray-case and vaccine paths both returned gpt-5.6-sol response IDs (docs/GPT56_PRODUCT_PATHS_RESULT.json).
• Full chronology and limitations: docs/GPT56_TEST_RUN_LOG.md.

Tests

python tests/test_antibody.py      # 10 tests (matching, calibration, signing, privacy)
python tests/test_pipeline.py      # pipeline, packaged gate, Registry-backed import
python tests/test_envelope_v2.py   # canonical signing, trust, time/replay, homoglyphs
# or, with pytest:  pip install pytest && pytest

Current full-suite result: 74 tests passed. The calibration dataset remains synthetic and small; passing it is reproducible evidence, not a production-wide recall claim. The GitHub Actions matrix repeats the suite on Windows and Linux with supported Python versions, and a separate workflow reruns Gitleaks on every push and pull request.

Secret handling and security audit

AL-MUNAA never requires a credential to be committed to the repository. Optional API credentials are read from environment variables, and the live demonstration uses a synthetic canary plus an in-memory sink instead of a production secret or exfiltration endpoint. Before publication, the complete working tree was scanned with Gitleaks v8.30.1 and a second credential-pattern scan; both found no committed or publishable secrets. See SECURITY.md for the audit boundary and reporting contact.

How Codex and GPT-5.6 were used

• Claude (Fable 5) — produced the initial working scaffold and first green end-to-end slice from the jointly agreed Build Week plan when the earlier Codex sandbox could not execute locally.
• Codex (GPT-5.6-Sol) — used test-first development on the core protocol in this build thread: reproduced the 0.3264 near-threshold match, added padding-resistant containment, doubled the bounded sketch to reduce family-key variance, added cross-family import rejection in Guard, authored the calibration matrix/runner, and implemented Trust Envelope v2 with canonical full-field signing, publisher key pinning, replay/expiry gates, strongest-match selection, and bounded homoglyph normalization. Codex /feedback Session ID: 019f72df-5fa7-7cf1-95f4-265467d02099.
• GPT-5.6 — runs inside the product through the Responses API as both the gray-case intent analyzer and defensive vaccine generator. Live response IDs and sanitized usage evidence are recorded in docs/GPT56_PRODUCT_PATHS_RESULT.json.

Before Build Week / Built During Build Week

Component	Status
src/almunaa/ (input/memory scan engine)	Pre-existing (built 8 Jul 2026), vendored, read-only
src/aegis/ (action gate + policy)	Pre-existing (built 8 Jul 2026), vendored, read-only
src/munaa_immune/antibody.py — Threat Antibody Protocol	Built during Build Week
src/munaa_immune/guard.py — unified pipeline + SDK	Built during Build Week
src/munaa_immune/signing.py — Ed25519 antibody signing	Built during Build Week
src/munaa_immune/gray_case.py — GPT-5.6 analyzer	Built during Build Week
src/munaa_immune/envelope.py — canonical Trust Envelope v2	Built during Build Week
src/munaa_immune/registry.py — pinned publisher keys + rotation	Built during Build Week
demo/, tests/ — fixtures, runner, test suites	Built during Build Week
scripts/calibrate_antibody.py + calibration matrix	Built during Build Week

The novelty and integration — the antibody protocol, the single-decision pipeline, the SDK, GPT-5.6 escalation, and the cross-agent collective-immunity demo — are all new work.

What this does NOT protect against

This is a risk-reduction layer with an auditable policy and human-approval hook — not a guarantee of safety. It does not:

• stop a determined attacker with local machine access or the family key;
• defend against attacks with no textual signal (pure binary/side-channel);
• replace sandboxing, least-privilege, or secret management — it complements them;
• guarantee zero false negatives; novel attacks may pass until an antibody exists;
• reliably match a deep semantic paraphrase with little character-shingle overlap;
• distinguish an attack from a document that quotes most of that exact attack payload — such content should remain untrusted and may require human review;
• provide distributed revocation, persistent Registry storage, or complete Unicode confusable coverage in v2; those remain explicit future work.

We deliberately report these limits: an honest boundary raises trust rather than lowering it.

License

License: This project is licensed under the CARBONFLOWS Non-Commercial Public License. Commercial use or integration into other products is strictly prohibited without written permission. See the ⁠LICENSE⁠ file for more details.