CyberGuard

CyberGuard

[](https://github.com/elsechord/CyberGuard/actions/workflows/ci.yml) [](https://github.com/elsechord/CyberGuard/releases/latest) [](LICENSE) [](https://www.python.org/)

Handling one attack end-to-end (82 s, fresh recording): cyberguard-demo-final.mp4 — release asset of v0.14.1, together with a fresh judge-demo evidence bundle (validation-final-20260919T145335Z.tar.gz).

CyberGuard is an evidence-driven autonomous security operations team built on AgentTeams. It coordinates specialized Agents for alert fusion, threat intelligence, network hunting, endpoint forensics, response planning, controlled execution and independent recovery verification.

The project is designed for the GOAI “Agent Infra 新智基座” track. It intentionally reuses AgentTeams for orchestration, Matrix collaboration, Skill distribution, shared storage and credential brokering, while CyberGuard provides the security-domain application layer.

Signed-in overview: open incidents, actions awaiting approval, evidence volume and guard budget usage.

Three steps to run

Use CyberGuard inside your existing Agent: the [portable investigation Skill](docs/EXTERNALAGENTSKILL.md) can be installed into a Codex or Claude Code project. It includes a copyable setup prompt, an offline first-use exercise, and a read-only client for existing CyberGuard incidents. The calling Agent performs the analysis; this path does not require AgentTeams or execute remediation. See the guide for host requirements and validation limits.

Path A — Docker Compose (recommended):

git clone https://github.com/elsechord/CyberGuard.git && cd CyberGuard
python deploy/init_secrets.py      # writes .env with role-separated random secrets (stdlib only)
docker network inspect agentteams-net >/dev/null 2>&1 || docker network create agentteams-net
docker compose up -d --build       # gateway 127.0.0.1:18100, response executor 127.0.0.1:18105

The network command above uses Bash (Linux/macOS or Windows Git Bash). It creates the external network required by Compose without installing AgentTeams. The read-only audit view is on port 18100; the multi-user operations console is on 18120 and requires first-admin setup. Follow [operations console deployment](docs/OPERATIONS_DEPLOY.md) for setup and HTTPS/session configuration. The baseline executor uses simulation, not production remediation.

Path B — Python venv, no Docker (Windows Git Bash verified):

git clone https://github.com/elsechord/CyberGuard.git && cd CyberGuard
python -m venv .venv
.venv/Scripts/python -m pip install -r services/security-tool-gateway/requirements.txt \
  -r services/response-executor/requirements.txt httpx
export PYTHONPATH="$PWD" CYBERGUARD_API_TOKEN=dev-read-token \
       CYBERGUARD_SCENARIO_DIR="$PWD/scenarios" CYBERGUARD_DATA_DIR="$PWD/tmp/data" \
       CYBERGUARD_KNOWLEDGE_DIR="$PWD/knowledge" && mkdir -p tmp/data
.venv/Scripts/python -m uvicorn app.main:app --app-dir services/security-tool-gateway \
  --host 127.0.0.1 --port 18100

Then open http://127.0.0.1:18100/console. The incident list starts empty; collect the first fixture evidence with POST /tools/alert/snapshot and the Authorization: Bearer header (see the quickstart for the exact curl). Services bind to loopback only.

Measured on a fresh clone (2026-09-18): venv to first evidence in the console in 6 min 07 s, including the full 23-file test suite. Full walkthrough, timings and troubleshooting: [docs/QUICKSTART.md](docs/QUICKSTART.md).

Prebuilt container images

Both services are built and pushed to GHCR by CI on every published release and on manual dispatch ([publish-images.yml](.github/workflows/publish-images.yml), linux/amd64):

docker pull ghcr.io/elsechord/cyberguard-gateway:sha-3b34e4c
docker pull ghcr.io/elsechord/cyberguard-executor:sha-3b34e4c

sha-3b34e4c is the tag pushed by the first verified dispatch run; release tags (vX.Y.Z) and latest are attached automatically on the next published release. The GHCR packages currently require a GitHub login with access to pull — flip visibility to public in the package settings if you are a maintainer.

> GOAI 复赛（v0.13.0）：真实 AgentTeams 原生任务证据包已发布 —— 一条 WebShell 供应链投毒事件（CG-2026-0002）从任务创建、四线并行调查、提案、人工审批（哈希绑定）、执行、双轮独立复测（inconclusive→verified）到回滚演示的完整闭环，含 2,992 条原生 Matrix 事件与 14 条 HMAC 链式审计记录。见 release v0.13.0 与 [复现手册](docs/LIVETASK_EVIDENCE.md)。

What is runnable today

• A read-only security evidence gateway with alert, intelligence, network, boundary-policy, endpoint, asset and recovery tools.
• Evidence 1.0 normalization with OCSF-aligned event classes, STIX 2.1 observable types, ATT&CK mappings, deterministic quality gates and cross-source entity correlation.
• A controlled response executor with an allowlist, idempotency, proposal-bound approval, HMAC-authenticated audit records/checkpoints and rollback. The lab backend persists dispatch intent and reconciles uncertain outcomes; it requires a single executor process.
• A loopback identity laboratory with real SQLite account mutations, separate account-access probes, durable operation receipts and restart/lost-response tests.
• Reproducible credential-compromise and supply-chain compromise scenarios, including adversarial tool output.
• Seven Agent role definitions and ten reusable AgentTeams Skills, including explicit boundary-defense analysis.
• Server-owned live SIEM/NDR/EDR/CMDB connector contracts that keep destinations and credentials away from Agents.
• A read-only evidence audit console for incident status, evidence graphs, approvals, action history and verification.
• Evidence and incident JSON contracts.
• AgentTeams v1.2.2 server configuration and bootstrap instructions.
• Local unit tests and server-side Docker smoke tests.

The response executor defaults to simulation. Opt-in lab mode really disables and restores one account in an isolated local identity service. It does not operate a production identity provider. Live investigation connector contracts are implemented; vendor-specific mutating integrations remain future work.

Operations console

The bundled operations console turns CyberGuard into a deployable multi-user product surface rather than a demo page: server-side sessions with PBKDF2 password hashing, four-tier RBAC (viewer / analyst / approver / admin, deny-by-default), API keys with scoped Bearer access to a versioned JSON API, and an append-only decision audit with CSV export. It ships as a hardened container in the same compose.yaml as the rest of the stack.

Per-incident workflow timeline interleaving agent events, evidence records and response-action state, with the current workflow state derived from the audit trail.

A proposed response action held until an approver records a mandatory closure classification and written justification; approving also advances the gateway workflow so the incident leaves awaiting_approval.

Authentication and decision audit trail: setup, logins, approvals (with action id) and key management, exportable as CSV.

Scoped API keys: cg_live_ secrets shown once, stored as sha256, with expiry and revocation.

Reproduce the real account laboratory

After installing the dependencies in [the lab runbook](docs/LAB_EXECUTION.md), run:

python scripts/lab-demo.py

This starts three loopback services, demonstrates proposal/approval/disable/independent verification/rollback, then stops them. A checksummed evidence directory is written under artifacts/lab/. The harness is deterministic and supplies its own approval credential: it is not an AgentTeams/LLM run or evidence of actual human review. See the runbook for failure semantics and the integration tests for response-loss recovery.

For the isolated Docker version, run docker compose -f compose.lab.yaml up --build --abort-on-container-exit --exit-code-from lab. It uses a non-root container with no external network and a read-only root filesystem. See the runbook to copy out evidence and run fault tests. The console now supports run-scoped evidence, authenticated action snapshots, mode/probe details and JSON exports.

Reproduce incomplete cleanup and process recurrence

docker compose -f compose.host-lab.yaml up --build --abort-on-container-exit --exit-code-from host-lab

The [Linux process lab](docs/HOST_LAB.md) starts harmless real processes in an offline container. An approved process termination is followed by an actual supervisor restart; independent observations reject recovery. A separately approved, version-bound persistence cleanup is then checked over a bounded time window while a control workload keeps progressing. The console and run export retain both outcomes. The workflow is scripted, and automated approval is explicitly labeled; an optional interactive approval mode is available. This is not a real mining intrusion, an AgentTeams run, or proof of autonomous reasoning.

Evidence-bound investigation

The [investigation pipeline](docs/INVESTIGATIONPIPELINE.md) accepts immutable evidence bundles and produces cited reports through a read-only API and a separate report-submission credential. The Linux collector records collection gaps; the fixed-rule baseline preserves uncertainty about malware, initial access and attribution. Three labeled exercise cases and a separate evaluator are included. The [model runner](docs/INVESTIGATIONEVALUATION.md) supports actual bounded single-agent tool calls and retains failed attempts, raw responses and provider usage. AgentTeams task/MCP preparation is separate; neither a direct model call nor an accepted report proves AgentTeams execution.

Run docker compose -f compose.investigation.yaml up --build --abort-on-container-exit --exit-code-from investigation to exercise the HTTP pipeline and collect the current isolated Linux container. The image excludes exercise answer keys and performs no remediation.

For actual local orchestration, see [AgentTeams on Docker Desktop](docs/AGENTTEAMS_LOCAL.md). This deployment uses a documented, locally built controller patch to bind Worker consoles to localhost. It is an integration environment; service health and Worker readiness do not establish task completion or comparative effectiveness.

The experimental [model admission guard](docs/MODELGUARD.md) reserves per-run budgets before provider dispatch, authenticates role-bound model routes, rejects exact duplicate requests, and retains unknown usage after failures. The [fresh-Worker integration procedure](docs/AGENTTEAMSGUARDED_LOCAL.md) verifies native tools and route isolation while the guard is disarmed. Its serial three-Worker harness tests integration; it does not establish autonomous orchestration or a multi-agent performance advantage.

Architecture

Human / SOC analyst
        │ Matrix approval and intervention
        ▼
AgentTeams Team Leader
        │
        ├── Alert Fusion ──┐
        ├── Threat Intel ──┤
        ├── Network Hunter ├── Evidence IDs + competing hypotheses
        └── Endpoint IR ───┘
                           │
             Standard observation + quality gate
                           │
              Entity / observable correlation graph
                           │
                    Response Planner
                           │ proposal
                           ▼
                 Controlled Responder ── human approval gate
                           │
                    Recovery Verifier
                           │
                 Auditable incident report

AgentTeams: orchestration, Matrix, MinIO, Higress, Skills, lifecycle
CyberGuard: security tools, evidence model, response policy, scenarios, evaluation

Agent Infra Primitives

The governance core below is domain-agnostic by construction — security is simply its first tenant. Each layer is reusable for any agent workload that needs controlled side effects, normalized evidence, model budgets or run-bound verification.

| Primitive | What it does | Where | |---|---|---| | Controlled side-effect execution kernel | Proposal → human approval → idempotent allowlisted dispatch → HMAC-chained audit records and checkpoints → rollback, with reconciliation of uncertain outcomes | services/response-executor/app/main.py | | Observation / Evidence contract layer | OCSF/STIX-aligned normalization, deterministic quality gates and cross-source entity correlation behind one read-only tool surface | services/security-tool-gateway/app/normalization.py, contracts/ | | Model admission guard | Reserves per-run token budgets before provider dispatch, authenticates role-bound model routes, rejects exact duplicate requests, retains unknown usage after failures | cyberguard_investigation/model_guard.py | | Run-bound verification harness | Deterministic scenario fixtures, independent recovery probes and repeatable benchmark runs inside isolated Compose labs | benchmark/, compose.lab.yaml, compose.host-lab.yaml |

Upstream

Running CyberGuard on real AgentTeams v1.2.2 deployments surfaced three issues that received substantive maintainer replies: MCP tool-service registration friction (#1284), cumulative Worker input-token budgets (#1285) and driver-policy denial plus Worker console port exposure (#1286). The console-binding patch offered in #1286 became PR #1287, which a maintainer approved and merged into AgentTeams main on 2026-09-18. In #1285 the maintainers confirmed that per-request context limits cannot enforce a cumulative run budget — admission plus reservation, the mechanism CyberGuard's model admission guard already implements, is required.

Local development without Docker

The step-by-step quickstart for the Python-only path — venv, dependency install (the hash lock targets Linux x86_64; Windows falls back to the unhashed service requirements), the one-file-per-interpreter test suite, gateway/executor startup on loopback and port map — lives in [docs/QUICKSTART.md](docs/QUICKSTART.md). On Windows you can also run powershell -ExecutionPolicy Bypass -File scripts/test-local.ps1; on Linux bash scripts/test-local.sh. Run test files one per interpreter: both services expose an app package, so collecting the whole suite in a single pytest tests/ process is not supported.

Fast server deployment

Recommended host: Ubuntu 22.04/24.04 x8664, 8 CPU cores, 16 GB RAM, 100 GB SSD, Docker Engine and outbound access to the selected LLM provider. The current hash-locked Python wheel set intentionally targets Linux x8664.

1. Upload this repository to /srv/cyberguard.
2. Copy deploy/agentteams/agentteams.env.example to /srv/cyberguard/agentteams.env and fill the model API values and strong admin password.
3. Run the single bootstrap and acceptance entry point:

``bash cd /srv/cyberguard chmod +x deploy/*.sh scripts/*.sh tests/*.sh sudo ./deploy/bootstrap-server.sh ``

It checks Linux/Docker/resources, atomically creates .env with five role-separated random secrets and mode 0600, validates both configuration files without exposing secret values, installs the pinned AgentTeams release if needed, builds CyberGuard, proves the response lifecycle and creates a timestamped checksummed archive under artifacts/acceptance/.

1. For a remote server, forward the loop

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: elsechord
• Source: elsechord/CyberGuard
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.