argus README

项目的 README,来自 github.com/thomasunise/argus。合并为一个 markdown 文件:README.md。

Argus

The open-source security operations platform where AI agents do the legwork and you stay in control.

Test License: MIT

Argus watches your cloud, identity, code, endpoints, network and Kubernetes. It catches attacks at machine speed, investigates them with AI agents, and contains them in seconds. Every action is typed, checked against policy, dry-run first and reversible. It is self-hosted, multi-tenant and MIT licensed, so your security data never leaves your hands.

Argus overview

Why Argus

Stop attacks while they are happening, not the next morning. Autonomous response playbooks act the moment a detection fires: block an attacker at Cloudflare, cut a laptop off the network through CrowdStrike or SentinelOne, and more from a catalog of 27 typed actions. They start in shadow mode so you can see what they would do, use only reversible actions, stay within hourly and blast-radius caps, and roll themselves back unless you keep the change.

Approve from Slack in one click. Approve, deny or roll back actions straight from the alert. No console, no context switch.

AI that investigates without taking the wheel. Nine specialist agents triage, investigate and hunt using read-only tools. They can propose a fix but never execute one. Everything they read is treated as untrusted data, so a prompt injection hidden in a log becomes a signal instead of a hijack.

See every AI tool your company is really using. The AI gateway puts OpenAI and Anthropic traffic behind org-held keys, model allowlists, data-loss prevention, prompt-injection flags and budgets. Shadow-AI discovery finds the services people use without approval, using your network, cloud and SSO telemetry.

Catch rogue AI agents in the act. Plant canaries built for agents: hidden prompt injections, agent rules files, a fake MCP server and fake LLM API keys. Any agent that takes the bait trips a detection, with its IP, model and prompt recorded.

Prove your detections work before an attacker tests them. The agentic attack simulator replays 8 AI-driven attack scenarios in an isolated sandbox tenant, with optional evasion variants, and reports exactly which ones you caught, which you missed and which rules were off.

Pentest continuously, not once a year. Autopilot and native autonomous pentesting plan tests, run them through the scope-checked harness, and re-plan from what they find. They only run inside scopes a human has marked for unattended testing.

Fix what attackers are exploiting right now. Every finding with a CVE is enriched with CISA's Known Exploited Vulnerabilities list and EPSS exploit-probability scores, and severity is raised automatically. It works offline for air-gapped installs.

Never lose a day of data. Encrypted backups run on a schedule and land on disk, S3 or Azure. Restore is one command, and it proves itself: row counts and every tenant's audit chain are checked before you switch over. Per-tenant retention keeps the database lean without touching the audit trail.

Audit-ready from day one. A hash-linked, signed audit chain records every action, approval and agent step, mirrored to S3 Object Lock or Azure immutable storage. Control mappings for SOC 2, NIST 800-171 and ISO 27001 are included.

Runs anywhere you do. Docker Compose for a pilot, Helm for Kubernetes, and Terraform for AWS and Azure. Every autonomous feature ships off by default, so you turn on exactly as much autonomy as you trust.

Tested on every push

692 automated tests run on every commit against both SQLite and PostgreSQL, alongside Bandit and pip-audit security scans, a container build and smoke test, a full Compose stack smoke test, and Terraform and Helm validation. docs/GO-LIVE.md walks you through a production rollout: start in monitoring mode, tune detections to your estate, then switch on actions and autonomy when you are ready.

Architecture

  Browser / SDK / sensors
          |
          v  HTTPS (Caddy, ALB, Front Door or your ingress)
  +-------------------------------------------------------------+
  |  API  (FastAPI)  auth: session / OIDC+PKCE / TOTP / API keys |
  |  RBAC (viewer < analyst < operator < admin < owner), CSRF,   |
  |  per-principal rate limits, request ids, security headers    |
  +------+------------------+------------------+----------------+
         |                  |                  |
   PostgreSQL           Redis queue        Audit chain
   (tenant_id on       (leases, retries,   (hash-linked per tenant,
    every table)        python -m          HMAC, JSONL / S3 Object
                        app.worker)        Lock / Azure immutable)
         |                  |
  +------+------------------+----------------------------------+
  |  Worker processes run the same handlers as the API:        |
  |   collectors.run   detections.run / baselines              |
  |   graph.recompute  testing.run   agents.run                |
  |   autoresponse.evaluate   testing.autopilot   pentest.run  |
  |   discovery.run   exploit.execute   simulation.run         |
  |   intel.enrich / refresh   ai.discover                     |
  +------------------------------------------------------------+
         |
         v  agents call propose_action only -> ActionRequest(pending)
  Action broker (separate policy, approvals, dry run, rollback, kill switch)

Trust boundaries, in one sentence each (details in docs/THREAT-MODEL.md):

  1. Agents cannot execute anything; their one write-capable tool creates a pending request. Autonomous response acts only through the broker, as the system principal, with reversible non-critical actions, caps and automatic rollback.
  2. Everything an agent reads is wrapped as untrusted data and the prompt says so.
  3. Active testing runs only inside a recorded authorization and scope, re-checked at run time.
  4. Every domain table carries tenant_id; queries go through a scoped helper; tests assert it.
  5. The audit chain is hash-linked, HMAC-signed (required in production), and mirrored to an external, optionally WORM, sink.

What is in this checkout

Area Status Where
App factory, settings, DB, RBAC, auth (local, OIDC, TOTP, API keys), CSRF, rate limits implemented, tested app/core/, app/api/auth.py, app/api/deps.py
Audit chain with JSONL / S3 Object Lock / Azure immutable blob sinks implemented app/core/audit.py
Job queue (in-memory and Redis, leases, retries, cancellation, reaper) and standalone worker implemented app/core/queue.py, app/worker.py
Prometheus metrics, JSON logging, optional OpenTelemetry tracing implemented app/core/telemetry.py
Evidence graph: nodes, edges, attack paths, exposure scoring implemented app/graph/, app/api/graph.py
Detections: 15 rules (swarm x4, identity x2, cloud, k8s, code, canary, anomaly, agentic x3 including unsanctioned AI service and cross-source attack chain, industrial), baselines, canaries (12 kinds, 4 aimed at AI agents: planted prompt injection, agent rules file, fake MCP server, fake LLM key) implemented app/detections/, app/api/detections.py, app/api/canaries.py
Collectors: AWS, Azure, GCP, Kubernetes, GitHub, Okta, Entra, osquery, netflow implemented; cloud SDKs optional app/collectors/, app/api/collectors.py
Test harness: scope policy (passive, active, intrusive, exploit), rate limits, 28 adapters (web_baseline, browser_xss, caldera, dir_probe, ffuf_dir, gitleaks, idor_probe, js_analyze, js_libs, jwt_analyze, jwt_attack, nmap_sv, nuclei, oob_probe, param_mine, param_probe, payload_fuzz, port_probe, prowler, retire_js, semgrep, sqli_proof, strix, subdomain_enum, trivy, trufflehog_verify, waf_detect, zap) implemented; runs the tools installed on your workers or sandbox app/testing/, app/api/tests.py, app/api/scans.py
Agent runtime, providers (Anthropic, OpenAI, Ollama, none), read-only tools, 9 specialists (including offensive pentest and PoC author), eval suites implemented app/agents/, app/api/agents.py, app/api/evals.py
Action broker: catalog of 27 typed actions (AWS, Azure, GCP, Kubernetes, GitHub, Okta, Entra, Cloudflare, CrowdStrike, SentinelOne, Argus-internal), policy, approvals, dry run, execute, rollback, kill switch implemented app/actions/, app/api/actions.py
Autonomous response: playbooks that act on detections without a human (shadow mode first, reversible actions only, caps, automatic rollback); Slack approve / deny / roll back buttons implemented; off by default app/actions/autoresponse.py, app/api/autoresponse.py, app/api/slack.py, docs/AUTONOMOUS-RESPONSE.md
AI gateway (governed OpenAI / Anthropic proxy: org-held keys, model allowlists, DLP, prompt-injection flags, budgets, usage log) and shadow-AI discovery from network, cloud and SSO telemetry implemented; gateway off by default app/ai/, app/api/ai_gateway.py, app/api/ai_inventory.py, docs/AI-GATEWAY.md
Autonomous pentesting, native pentest orchestrator, recon/browser discovery, and gVisor PoC exploit sandbox implemented; gated by scope, asset authorization and kill switches app/testing/autopilot.py, app/pentest/, app/discovery/, app/exploit/, docs/AUTOPENTEST.md, docs/NATIVE-PENTEST.md, docs/DISCOVERY.md, docs/EXPLOIT-SANDBOX.md
Threat intel: automatic CISA KEV and EPSS enrichment of findings, offline cache implemented app/intel/, app/api/intel.py, docs/INTEL.md
Agentic attack simulator: 8 agent-driven attack scenarios replayed in an isolated sandbox tenant, coverage report, evasion variants implemented app/simulator/, app/api/simulations.py, docs/SIMULATOR.md
Integrations: 15 inbound sources (14 parser modules; network covers Suricata and Zeek) behind POST /api/v1/ingest/{source}, 6 outbound channels (webhook, Slack, Jira, ServiceNow, PagerDuty, email) with deliveries and retries, Wazuh indexer pull implemented app/integrations/, app/api/ingest.py, app/api/integrations.py
Backups and retention: scheduled encrypted backups to disk, S3 and Azure, verified one-command restore, per-tenant retention policies implemented app/ops/, app/api/backups.py, app/api/retention.py, docs/BACKUP.md
Admin, assets, findings, events, investigations, approvals, audit, reports routers implemented app/api/
Alembic migrations (18 revisions, through fail-closed tenant RLS, session revocation and unique action approvals) and scripts/migrate.py implemented alembic/, docs/MIGRATIONS.md
Containers, compose, Helm, Terraform (AWS, Azure), CI, observability, docs implemented Dockerfile, compose*.yaml, infra/, .github/, docs/

Routers are discovered automatically. The full v1 surface is in docs/API.md.

Quick start (development, SQLite, no Docker)

Requirements: Python 3.12 or 3.13.

python -m venv .venv && . .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt
cp .env.example .env
python scripts/generate_secrets.py --write          # fills the three REPLACE_ values, plus AUDIT_SIGNING_KEY and DATA_ENCRYPTION_KEY when they are empty
uvicorn app.main:app --host 127.0.0.1 --port 8080

Open http://127.0.0.1:8080 and sign in as ADMIN_EMAIL / ADMIN_PASSWORD from .env. With REDIS_URL empty, jobs run inside the API process (WORKERS_INPROCESS=true). With DB_AUTO_CREATE=true (the default) tables are created at startup; for Alembic-managed schemas set it to false and run python scripts/migrate.py (see docs/MIGRATIONS.md).

Synthetic demo data in an isolated tenant (never touches the network):

python scripts/seed_demo.py

It prints a demo tenant login and creates DEMO-labelled assets, authorizations, events that trip cloud.public_exposure_change and swarm.machine_speed_sequence, findings, a canary and an agent run record. Refuses to run when APP_ENV=production.

Tests:

python -m pytest -q

Pilot (Docker Compose: API, worker, PostgreSQL, Redis)

cp .env.example .env && python scripts/generate_secrets.py --write
docker compose up --build -d
docker compose logs -f api

compose.yaml binds the API to 127.0.0.1:8080 only, runs the API and worker from one image with a read-only root filesystem, no capabilities and no Docker socket, mounts ./targets read-only, and applies the schema at API start (RUN_MIGRATIONS=true). Add --profile observability for an OpenTelemetry collector, Prometheus (scraping /metrics) and Grafana with the dashboard in infra/grafana/argus.json.

TLS termination for a single host:

# .env: APP_ENV=production COOKIE_SECURE=true BASE_URL=https://host ARGUS_DOMAIN=host [email protected]
docker compose -f compose.yaml -f compose.prod.yaml up -d

Production

Kubernetes: infra/helm/argus (API + worker deployments, HPA, PDB, default-deny NetworkPolicy, ingress with TLS, optional ServiceMonitor). AWS: infra/terraform (ECS Fargate, RDS, ElastiCache, S3 Object Lock audit bucket, Secrets Manager, ALB + WAF). Azure: infra/terraform-azure (Container Apps, Flexible Postgres, Azure Cache, immutable blob container, Key Vault, Front Door + WAF).

The production checklist is in docs/DEPLOYMENT.md. The short version, enforced partly by assert_safe_config() at startup:

Roles

Roles are cumulative (app/core/rbac.py):

Role Adds
viewer read everything in the tenant, including autoresponse playbooks and the AI inventory
analyst edit findings and detections, run agents and evals, manage canaries, record approvals, use the AI gateway
operator manage and authorize assets, run tests, scans, autopilot and collectors, request, approve, execute and roll back actions, run detections and simulations
admin users, API keys, settings, collector and integration configuration, the actions kill switch, test scopes (including marking one autonomous), autoresponse playbooks, AI gateway policy
owner tenant settings, approving critical actions; owners of the bootstrap tenant also manage backups

API keys carry a role and optional scopes (for example ingest) that further restrict them. A system principal is used only inside queue handlers.

How agents, testing and actions are governed

Agents (app/agents/runtime.py). A specialist is an AgentSpec with a system prompt, a list of tool names, an output schema and budgets (AGENT_MAX_STEPS, AGENT_MAX_TOKENS, AGENT_MAX_SECONDS, AGENT_COST_CEILING_USD, with AGENT_MODEL_PRICES for models outside the built-in Claude price table). Tools are read-only views over Argus data; the only propose tool creates a pending ActionRequest through the broker. Every tool result is redacted, truncated and wrapped as <untrusted_data source=...>; the guardrail prompt tells the model that instructions inside evidence are indicators of injection. Each model and tool step is persisted (agent_steps) with input hash, tokens and latency. With AI_PROVIDER=none, specialists run deterministic fallbacks. Prompt-injection and precision eval suites live in app/agents/evals/suites/.

Testing (app/testing/). A TestScope lists assets, allowed tiers (passive, active, intrusive, exploit), environments, a UTC window, a rate limit and a concurrency limit (runs beyond max_concurrency wait in the queue). A run is allowed only if the asset has a current AssetAuthorization whose flags permit the tier, the scope permits it, the window is open and the target passes policy validation. scope.check() runs at request time and again inside the worker; intrusive and exploit tiers are limited to staging and lab environments by default. External tools run through run_tool() with a fixed argv, a timeout, bounded output and a minimal environment.

Actions (app/actions/). Typed actions declare risk, reversibility and a parameter schema, and implement dry_run, execute and rollback. A request (from an operator or an agent's propose_action) goes through policy (app/actions/policy.py: kill switch, tenant actions_enabled, deny-lists, maintenance window, auto-approval only for low-risk reversible actions when ACTIONS_AUTO_APPROVE_LOW), approvals (approver differs from requester; high risk needs two when ACTIONS_REQUIRE_TWO_FOR_HIGH; critical additionally needs a principal with actions:approve_critical), a dry run with blast radius, execution as the actions.execute queue job with a stored rollback payload, and an audit entry at every transition. ACTIONS_KILL_SWITCH=true (global, environment) or POST /api/v1/actions/kill-switch (per tenant, sets actions_enabled=false) rejects every request and execution.

Autonomy (docs/AUTONOMOUS-RESPONSE.md, docs/AUTOPENTEST.md). Both autonomous features need a global switch and a tenant opt-in, and both are off by default. Autonomous response playbooks start in shadow mode (they record what they would have done), may only use reversible, non-critical actions, are capped per hour and by blast radius, roll actions back automatically unless a human keeps them, and ignore detections from the simulator. Autopilot runs only in scopes a human has marked autonomous; the red-team agent plans, and every test it proposes is re-checked by the normal scope machinery before and during execution. AUTOPENTEST_KILL_SWITCH and the actions kill switch stop each one at once.

Documentation

Document Content
docs/ARCHITECTURE.md design: packages, interfaces, data model, API table
docs/API.md v1 route summary with status
docs/DEPLOYMENT.md dev, compose, Kubernetes, AWS, Azure; production checklist
docs/AUTONOMOUS-RESPONSE.md autonomous response playbooks, safety limits, Slack buttons
docs/AUTOPENTEST.md autonomous pentesting gates and how runs proceed
docs/AI-GATEWAY.md AI gateway policy, DLP, budgets and shadow-AI discovery
docs/SIMULATOR.md agentic attack simulator scenarios and coverage reports
docs/INTEL.md CISA KEV and EPSS enrichment, caching and offline mode
docs/BACKUP.md backups, restore procedure and drill, data retention policies
docs/MIGRATIONS.md Alembic workflow
docs/GO-LIVE.md step-by-step production rollout in monitoring-only mode
docs/SECURITY.md security model as implemented, reporting
docs/THREAT-MODEL.md STRIDE per trust boundary, prompt injection, SSRF, tenancy, credentials, broker abuse, supply chain
docs/RUNBOOKS.md incident procedures
docs/COMPLIANCE.md SOC 2 / NIST 800-171 / ISO 27001 control mapping and the evidence Argus produces for each control
docs/ROADMAP.md implemented versus next
CONTRIBUTING.md contributing guide

Security

Please report vulnerabilities privately through GitHub's private vulnerability reporting (Security tab), not in public issues. Details in docs/SECURITY.md.

License

MIT for this repository. Third-party tools (nuclei, ZAP, Prowler, CALDERA, Semgrep, Gitleaks, Trivy), cloud SDKs and model providers are governed by their own licenses and terms.

argus (thomasunise/argus)

正在搜索数据库…

152 ·GitHub
这是什么?Argus 是一个开源的自托管安全运营平台。AI 智能体会在云、身份、代码、终端、网络和 Kubernetes 等领域调查告警,而它提出的任何操作都需要由人工批准或拒绝。
这是 SIEM、渗透测试工具,还是别的什么?它在一个平台中整合了多种角色:类似 SOC 工具的检测功能和证据图谱、只读的 AI 调查智能体、可选的自主响应代理、面向 OpenAI/Anthropic 流量的受管 AI 网关,以及持续运行的自动渗透测试框架。
我该如何让它运行起来?本地开发时,请安装 Python 3.11 或 3.12,并直接基于 SQLite 运行,无需 Docker;试点部署时,使用随附的 compose.yaml,通过 Docker Compose 运行 API、worker、PostgreSQL 和 Redis;生产环境则使用 Kubernetes 上的 Helm,或 AWS/Azure 上的 Terraform。
使用它是否需要 Anthropic 或 OpenAI 的 API 密钥?只有在你需要调查智能体或 AI 网关功能时才需要。智能体运行时支持 Anthropic、OpenAI、Ollama,也可以不使用任何模型服务商,因此核心的检测与响应功能无需任何大模型密钥即可工作。
自主响应和自动渗透测试默认是开启的吗?不是。自动响应、AI 网关和自动渗透测试默认都处于禁用状态。自动响应会先以影子模式启动,让你在允许它执行操作之前,先看到它会做什么。
我的安全数据会流向哪里?不会流向你自身部署之外的任何地方。Argus 是自托管且支持多租户的,你对数据拥有完全的控制权。
AI 网关是做什么的?它是一个受管的代理,用于转发 OpenAI 和 Anthropic 的流量,并执行组织持有的 API 密钥、模型白名单、数据防泄露、提示词注入标记和支出预算等策略;同时还能从网络、云和 SSO 遥测数据中发现未经批准的(影子)AI 使用情况。
什么是智能体攻击模拟器?它会在隔离的沙箱租户中回放 8 个由 AI 驱动的攻击场景(可选择加入规避变体),并准确报告哪些攻击被拦截、哪些被漏过,以及哪些规则配置有误。
Argus 如何识别失控的 AI 智能体?它会布设针对 AI 的诱饵,例如隐藏的提示词注入、智能体规则文件、一个假的 MCP 服务器和假的大模型 API 密钥;任何上钩的智能体都会触发检测,并记录其 IP、模型和提示词。
这个代码库的测试做得怎么样?超过 460 项自动化测试,每次提交都会在 SQLite 和 PostgreSQL 两种数据库上运行,同时还包括 Bandit 和 pip-audit 安全扫描、容器构建与冒烟测试,以及 Terraform/Helm 验证。
大小
6.8 MB
星标
152
更新
提交Nov 05
时长
25天
提交 · 90 天