AEGIS

pip install cognis-aegis
aegis audit manifest.json     # → trifecta findings in milliseconds
aegis scan .                  # → walk a project: MCP + LangChain + secrets + reach

AEGIS answers one question: can a single prompt injection turn this agent into an exfiltration tool? It does so by surfacing the lethal trifecta — when one agent simultaneously has access to (1) private data / credentials, (2) untrusted input, and (3) the reach to act externally. Hold all three and an attacker who controls any untrusted input can read your secrets and send them out. AEGIS finds that combination before it ships.

It is static, passive, and offline — it reads manifests and source, never executes scanned code and never touches the network.

🔎 Example output

Real, reproducible output from the tool — runs offline:

$ aegis-emit --version
aegis 0.1.2

$ aegis-emit --help
usage: aegis [-h] [--version] {audit,scan} ...

AEGIS - AI Agent Permission & Access Auditor. Detects the lethal trifecta
(credentials + untrusted input + external reach) that makes an AI agent
exploitable by prompt injection.

positional arguments:
  {audit,scan}
    audit       Audit an agent manifest (JSON) for trifecta exposure.
    scan        Scan a project directory (MCP/LangChain/OpenAI/CrewAI) for
                risk.

options:
  -h, --help    show this help message and exit
  --version     show program's version number and exit

Blocks above are real aegis output — reproduce them from a clone.

Sample result format (illustrative values — run on your own data for real findings):

{
"findings": [
    {
        "id": "1234567890",
        "title": "Suspicious Network Traffic",
        "description": "Unusual network activity detected from IP 192.168.1.100",
        "categories": ["Network", "Malware"],
        "severity": "Medium"
    },
    {
        "id": "2345678901",
        "title": "Unauthorized System Access",
        "description": "User 'johndoe' accessed system without permission",
        "categories": ["Authentication", "Privilege Escalation"],
        "severity": "High"
    }
]
}

Two ways to run it

AEGIS has two complementary engines, both exposed on the CLI:

Usage — step by step

1. Install (Python 3.10+, zero runtime deps):

   pip install cognis-aegis            # PyPI
   # or from source:
   pip install -e .                    # or: pipx install "git+https://github.com/cognis-digital/aegis.git"
   

2. Audit an agent manifest (human-readable table):

   aegis audit demos/01-basic/agents.json
   

3. Read the output as JSON (findings, axes, per-axis capabilities, fixes):

   aegis audit demos/01-basic/agents.json --format json | jq '.findings'
   

4. Scan a whole project and emit SARIF for GitHub Code Scanning:

   aegis scan . --format sarif -o aegis.sarif
   

5. Interpret the verdict — each finding names the dangerous capability combination and a remediation; the header reports the worst severity and a composite risk score.
6. Gate CI on exposure — exit 1 when any finding at/above the threshold is present, 0 otherwise, 2 on a missing/invalid manifest:

   - run: pip install cognis-aegis && aegis scan . --fail-on high   # non-zero fails the job
   

Contents

• Why aegis? · Features · Quick start · Worked example · Output formats · Architecture · AI stack · Polyglot ports · Edge / air-gap · How it compares · Scope & safety · Integrations · Install anywhere · Related · Contributing

Why aegis?

AI Agent Permission & Access Auditor — surfaces the lethal trifecta of credentials + injection + reach — without standing up heavyweight infrastructure.

aegis is single-purpose, scriptable, and self-hostable: point it at a manifest or a directory, get prioritized results in the format your workflow already speaks (table · JSON · SARIF · HTML · Markdown), gate CI on it, and let agents drive it over MCP. The core is pure Python standard library — no third-party runtime dependencies, no network calls, no telemetry.

Features

• Lethal-trifecta detection — flags agents that combine credential/private-data access + untrusted input + external reach.
• Injection→RCE detection — independently flags agents that route untrusted input into a shell/exec/deploy capability.
• Capability classifier — 100+ keyword signatures plus an explicit-scope map (read:secrets, net:outbound, exec:shell, …) over tool names, descriptions, scopes and permissions.
• Framework parsers — MCP (mcp.json / claude_desktop_config.json), LangChain (@tool + Tool(...)), OpenAI Assistants export, CrewAI YAML.
• Static detectors — prompt-injection seeds (imperative override, role hijack, zero-width / RTL Unicode, system-prompt extraction), hard-coded credentials (OpenAI/Anthropic/GitHub/AWS/GCP/Stripe/Slack), and AST-based shell/eval/subprocess(shell=True)/unsafe-deserialization reach.
• Deterministic 0–100 risk score + a compliance crosswalk (OWASP LLM Top 10, MITRE ATLAS, CWE, NIST 800-53).
• Five output formats — console, json, sarif (2.1.0), html, markdown.
• CI-native — --fail-on {critical,high,medium,low,none} exit gating.
• Polyglot — Python (reference) + Go, Rust, JavaScript/Node, and POSIX-shell ports of the audit command, each verified in CI.
• Runs on Linux/macOS/Windows · Docker · devcontainer.

Quick start

pip install cognis-aegis
aegis --version
aegis audit demos/01-basic/agents.json     # audit one manifest
aegis scan .                               # scan current project
aegis scan . --format json                 # machine-readable
aegis scan . --fail-on high                # CI gate (non-zero exit)

Worked example

The bundled demos/01-basic/agents.json describes four agents. support-bot can read the support inbox (injection — untrusted email), query the billing DB (credentials), and send email (reach) — the full trifecta:

$ aegis audit demos/01-basic/agents.json
AEGIS audit  |  agents scanned: 4  |  findings: 4  |  worst: critical
------------------------------------------------------------------------
[CRIT] support-bot: Lethal trifecta: credentials + injection + reach
        axes: credentials, injection, reach
        credentials  <- billing_db_query
        injection    <- read_email
        reach        <- send_email
        fix: This agent can access sensitive data, ingest untrusted input,
             AND act on the outside world. Break the trifecta by removing one axis.

[HIGH] deploy-agent: Two of three trifecta axes present
        axes: injection, reach
        ...
[CRIT] deploy-agent: Untrusted input can reach code execution
        ...
[HIGH] summarizer: Two of three trifecta axes present
        ...

calculator (a single benign compute capability) produces no finding. Exit code is 1 because a critical is present — perfect for a CI gate.

As JSON:

$ aegis audit demos/01-basic/agents.json --format json | jq '{worst: .worst_severity, n: .finding_count}'
{ "worst": "critical", "n": 4 }

Scanning the intentionally-vulnerable coding-assistant demo (an MCP config + a LangChain agent) surfaces hard-coded keys, a subprocess(shell=True) call, an eval(), an injection seed in a tool docstring, and the trifecta:

$ aegis scan demos/coding-assistant
AEGIS v0.1.2  —  Cognis Digital / Cognis Neural Suite
COMPOSITE SCORE:  100.0 / 100  (CRITICAL)
Findings: 4 critical, 3 high, 0 medium, 0 low, 0 info

⚠️  LETHAL TRIFECTA DETECTED in agents:
     • python:agent.py
   (private data access + untrusted content + external comms = exfil capable)

[CRITICAL] AEG-REACH-002  subprocess with shell=True
[CRITICAL] AEG-SEC-001    Hardcoded credential: OpenAI API key
[CRITICAL] AEG-REACH-001  Shell/eval reach: `eval`
[HIGH    ] AEG-INJ-001    Imperative override
...

Output formats

aegis scan renders the same ScanResult five ways:

The aegis audit command renders table (default) or json.

Architecture

flowchart LR
  M[agent manifest<br/>or project dir] --> P[parsers<br/>MCP · LangChain · OpenAI · CrewAI]
  P --> C[classifier<br/>credentials · injection · reach]
  P --> D[detectors<br/>injection · secrets · AST reach]
  C --> S[scoring<br/>trifecta + 0–100]
  D --> S
  S --> E[exporters<br/>console · json · sarif · html · md]

Everything is read-only and offline: parsers and the AST reach-analyzer parse code, they never run it.

Use it from any AI stack

aegis is interoperable with every popular way of using AI:

• MCP server — aegis mcp (Claude Desktop, Cursor, Cognis.Studio, uncensored-fleet); install the [mcp] extra.
• OpenAI-compatible / JSON — pipe aegis scan . --format json into any agent or LLM.
• LangChain · CrewAI · AutoGen · LlamaIndex — wrap the CLI/JSON as a tool in one line; AEGIS parses these frameworks' configs natively.
• CI / scripts — exit codes + SARIF for non-AI pipelines.

Polyglot ports

The primary aegis audit command is ported to Go, Rust, JavaScript/Node, and POSIX shell so you can drop the trifecta auditor into any stack or ship a single static binary. Every port matches the Python reference — same signatures, same JSON shape, same exit codes — and is built + smoke-tested in CI (.github/workflows/ports.yml).

node ports/javascript/index.js demos/01-basic/agents.json        # Node, zero deps
cd ports/go   && go run . ../../demos/01-basic/agents.json       # Go, zero deps
cd ports/rust && cargo run -- ../../demos/01-basic/agents.json   # Rust, zero deps
sh ports/shell/aegis.sh demos/01-basic/agents.json               # POSIX sh + jq

See ports/README.md for the full matrix.

Edge / air-gap

AEGIS is built to run on disconnected gear. The core is standard-library-only, makes zero network calls, and writes no telemetry — so it works identically in a classified enclave, on a disconnected build agent, or inside a minimal Docker image. The polyglot ports compile to single static binaries (Go/Rust) with no runtime, ideal for sneakernet deployment to an air-gapped CI runner. Nothing in AEGIS phones home; every input (manifest, source tree) is read from local disk.

How it compares

Scope, authorization & safety

AEGIS is a defensive, authorized-use tool. It:

• is strictly passive — it reads manifests and source files; it never executes scanned code and the AST reach-analyzer only parses;
• makes no network connections of its own — there is no active scanning, probing, or network reconnaissance;
• reports no fabricated findings — every rule fires on a real, observable pattern in the input you point it at;
• expects you to run it on code and configs you own or are authorized to audit.

Use AEGIS to harden your agents and supply chain. Findings are advisory — review remediations in context before acting.

Integrations

Pipes into your stack: SARIF for code-scanning, JSON for anything, an MCP server (aegis mcp) for AI agents, and aegis-emit — a native cognis-connect forwarder that maps findings to STIX/TAXII, MISP, Sigma, Splunk, Elastic, Slack/Discord, or a webhook (install the [connect] extra). See docs/INTEGRATIONS.md.

aegis scan . --format json | aegis-emit --to sarif        # or stix / splunk / slack ...

Install — every way, every platform

pip install "git+https://github.com/cognis-digital/aegis.git"    # pip (works today)
pipx install "git+https://github.com/cognis-digital/aegis.git"   # isolated CLI
uv tool install "git+https://github.com/cognis-digital/aegis.git" # uv
pip install cognis-aegis                                          # PyPI (when published)
docker run --rm ghcr.io/cognis-digital/aegis:latest --help        # Docker
brew install cognis-digital/tap/aegis                             # Homebrew tap
curl -fsSL https://raw.githubusercontent.com/cognis-digital/aegis/main/install.sh | sh

Optional extras: pip install "cognis-aegis[mcp]" (MCP server) · [web] (FastAPI dashboard) · [yaml] (CrewAI YAML) · [connect] (SIEM/STIX forwarding) · [all].

Related Cognis tools

• promptmirror — Prompt-injection & indirect-injection scanner for any LLM context input
• ledgermind — Local LLM cost & token forensics proxy with anomaly detection
• adversa — LLM red-team harness — OWASP LLM Top 10 + MITRE ATLAS attack packs
• guardpost — Runtime agent firewall — PII redaction, rate limits, policy enforcement
• hallumark — LLM hallucination & grounding auditor for RAG systems
• aicard — Auto-generated NIST AI RMF / EU AI Act Annex IV model & system cards

Explore the suite → 🗂️ all 170+ tools · ⭐ awesome-cognis · 🔗 cognis-sources · 🤖 uncensored-fleet · 🧠 engram

Contributing

PRs, new rules, and demo scenarios are welcome under the collaboration-pull model — see CONTRIBUTING.md and SECURITY.md. Run the suite with pytest (182 tests, stdlib-only) and the ports with go test ./... / cargo test / node --test / sh ports/shell/test.sh.

⭐ If aegis saved you time, star it — it genuinely helps others find it.

Interoperability

aegis composes with the 170+ tool Cognis suite — JSON in/out and a sharedOpenAI-compatible /v1 backbone. See INTEROP.md for thesuite map, composition patterns, and reference stacks.

License

Source-available under the Cognis Open Collaboration License (COCL) v1.0 — free for personal, internal-evaluation, research, and educational use; commercial / production use requires a license ([email protected]). See LICENSE.