EMO-Cyber-Agent — the security subagent your AI stack can actually trust

Stop letting your coding agent guess about security. Give it a specialist: scoped read-only audits, evidence-backed findings, and verification plans — over CLI, MCP, or Python, with zero code changes and zero invented results.

Get value in 60 seconds

pip install emo-cyber            # requires Python >= 3.11
cyber-agent audit . --format json > result.json

That's it — a machine-checkable security audit of your project. No API keys, no provider lock-in, no code changes. Then wire it into your agent:

{ "mcpServers": { "emo-cyber-agent": { "command": "cyber-agent", "args": ["mcp"] } } }

⭐ If this saves you one bad merge, star the repo — it keeps the project alive.

Who it's for

• AI agent builders — your Codex/Cline/OpenCode agent writes fast and breaks things fast. Delegate every security question to a governed specialist instead of a confident guess.
• CI / platform teams — gate merges on stable JSON contracts and machine-readable exit codes, not on prose opinions.
• Security reviewers — triage evidence-linked findings (with provenance and verification plans) instead of chasing hallucinations.

Why governed security for agents

AI coding agents ship code fast — and every generated diff, prompt, dependency, and tool call is a new attack surface. Generic assistants will happily opine about security, but their answers are ungrounded, unverifiable, and bound to no policy. EMO-Cyber-Agent exists for the gap in between: a specialist subagent that owns the security workflow, runs deterministic checks around probabilistic reasoning, and returns findings your pipeline can actually act on.

What it does

• Scoped security audits of a project tree (quick, standard, deep), with focus areas (auth, secrets, deps, …).
• Focused reviews of a target, verification planning for a candidate finding (plans, never exploits), and evidence-linked reports in JSON, JSONL, or Markdown.
• Threat-intel lookups (leak monitor, feed triage, ATT&CK mapping — defensive knowledge only, no network calls, no execution) via MCP.
• Stable JSON contracts across CLI, MCP, and the Python API, so results are machine-checkable in CI.

What it does not do

• No auto-remediation and no production changes by default.
• No exploit development and no offensive operations.
• Not a replacement for SAST, SCA, secret scanners, DAST, runtime security, or human security review.
• No scores-as-verdicts: findings carry evidence and provenance, not ratings.

EMO-Cyber vs the alternatives

Why it is different

1. Model-agnostic. No weights, no provider lock-in. The product is the methodology, control loop, tool contracts, and evidence model — bring any model or run it model-free in CI.
2. Policy-enforced, not prompt-suggested. A default-deny PolicyEngine in Core decides; CLI and MCP are thin adapters that cannot widen capabilities, whatever a prompt or tool description claims.
3. Evidence-first. No material finding without evidence; tool outputs are data, never instructions; repository content is untrusted by default.
4. Verification before confirmation. Candidates become plans with methods, locators, and rationale — confirmation requires evidence.
5. Read-only by default. Destructive actions need an explicit permission transition; progress is advisory-only and recovery is bounded and fail-closed.

Architecture

Host / CI / You ──▶ CLI · MCP (stdio + Streamable HTTP) · Python API
                          │  thin adapters, no authority
                          ▼
                   Core: Policy → Tools → Evidence → Reasoning
                              → Verification → Findings → Reporting

Core owns every security decision. Deterministic tool adapters (argv-only, confined, secret-free execution) surround the reasoning loop; the evidence graph correlates deterministically; the finding lifecycle gates promotion. Details: docs/02-architecture.md, docs/03-security-methodology.md.

Quick start

pip install emo-cyber            # requires Python >= 3.11
cyber-agent --help
cyber-agent doctor               # presence checks; never prints secrets
cyber-agent audit . --format json > result.json

From source (developers):

pip install -e '.[all]'

Docker (reproducible runtime and test target):

make docker-build
make docker-run
make docker-test
make docker-unit

The runtime runs as an unprivileged user with a read-only filesystem, no Linux capabilities, and no network access. See docs/docker.md for the security model and release-image pinning requirements.

MCP and integrations

Register once as an MCP server, then delegate from any compatible host:

{ "mcpServers": { "emo-cyber-agent": { "command": "cyber-agent", "args": ["mcp"] } } }

Seven tools (the last opt-in): cyber_audit, cyber_review, cyber_verify, cyber_report, cyber_status, cyber_extensions, cyber_threat_intel. Transports: stdio plus Streamable HTTP (localhost by default, with Host/Origin/session validation). Per-host guides: docs/integrations/ (OpenCode, Pi, Hermes, Jan, AnythingLLM, generic MCP, delegation rules, security model).

Levels: Supported = config + mapping shipped; Contract Tested = in-repo contract tests; Environment Tested = live binary exercised (where available); otherwise Not Tested — see docs/integrations/ per host.

Example workflow: an authorized audit, end to end

# 1. Check operational presence (no secrets printed).
cyber-agent doctor

# 2. Run a scoped, read-only audit; findings never change the exit code.
cyber-agent audit ./my-service --mode standard --format json > audit.json
python -c "import json; print(json.load(open('audit.json'))['result']['status'])"

# 3. Request a verification plan for a candidate (input is never authorization).
cyber-agent verify --candidate cand.json --method static-review \
  --kind sast --locator src/auth/login.py:42 --rationale "unverified input reaches query" \
  --audit-id <id-from-audit.json>

# 4. Render the evidence-backed report for humans or the pipeline.
cyber-agent report --findings findings.json --audit-id <id> --format markdown

Exit codes stay machine-readable and separate from findings: 0 success · 1 audit/domain failure · 2 invalid input · 3 policy denied · 4 security blocked · 5 provider/tool unavailable · 6 verification inconclusive · 7 internal error.

Commands

cyber-agent doctor | audit | review | verify | status | report | extensions | mcp

audit takes --mode quick|standard|deep, --focus a,b, --format human|json, and --output PATH. Only implemented options exist — there are no --shell, --exec, --grant, --sudo, --allow-write, or --bypass-policy flags, and no secret-valued flags (use environment or secret providers).

Platform parity (evidence-first)

Live runtime proof, not CI-smoke claims. Method: real runners, real installs, real CLI/MCP/HTTP/security batteries — green run #37866150660. Per-platform evidence lives in docs/evidence/:

Honestly open (never inflated to PASS): Pi/Jan native delegation and AnythingLLM adversarial-via-host are ENVIRONMENT-BLOCKED with reproducible reasons; test-key rotation is LOW / OPEN (operator step). See docs/evidence/POST-T021-final-review.md.

Limitations

Read-only analysis; no auto-remediation, no exploit capabilities, no scores-as-verdicts. Live-host interop beyond contract tests is environment-dependent (see host docs). Progress never gates security decisions; recovery never mutates policy, evidence, or findings.

FoundationSecurityAuditor.audit currently invokes locally installed Gitleaks through the strict read-only tool boundary and returns redacted scanner observations as evidence. It remains partial: Semgrep is intentionally not run until offline rule configuration is verified, Trivy and OSV-Scanner are not part of this local path, and finding classification/full control coverage are not implemented. review and verify remain partial stubs. A successful CLI process or an empty findings list is not a completed security assessment.

Verification and tests

make test                         # full suite (pytest, ~2 min)
python -m pytest tests/unit -q    # unit scope only

Release-gate checks live in tests/release/; benchmark corpus sanity in tests/unit/test_benchmark_*.py. Every material finding requires evidence; verification precedes confirmation — see docs/03-security-methodology.md.

Reference documentation

• Specs and contracts: docs/ (02-architecture.md, 05-mcp-interface.md, 06-cli-interface.md, 07-python-api.md, 08-tool-contracts.md).
• Host guides: docs/integrations/ (OpenCode, Pi, Hermes, Jan, AnythingLLM, generic MCP, delegation rules, security model).
• Threat model and guardrails: docs/13-threat-model.md, docs/14-safety-guardrails.md, docs/policies/.
• Release provenance: CHANGELOG.md and docs/evidence/.
• Contributing: CONTRIBUTING.md.

Security vulnerabilities

Do not open a public issue for a suspected vulnerability. Report it privately as described in SECURITY.md.

Contribute — help secure the agent era

Good first issues: host guides, benchmark cases, docs. PRs are reviewed against the same evidence bar the product enforces.

git clone https://github.com/SE-Emam/EMO-Cyber-Agent.git
cd EMO-Cyber-Agent && make check

See CONTRIBUTING.md. If the project helps you, ⭐ star it — discoverability is our growth engine.

License

Apache-2.0 — see LICENSE.