Argus is a self-hosted, multi-tenant security operations platform in which AI agents analyze evidence but never act on the estate. Collectors inventory cloud, identity, code, endpoint, network and Kubernetes assets into an evidence graph; a detection engine evaluates events for swarm, identity, cloud, code and canary signals; a scope-gated test harness runs authorized security tools; governed agents triage, investigate and hunt with read-only tools; and a separate action broker (typed actions, policy, approvals, dry runs, rollback, kill switch) is the only component allowed to change anything.

This README describes what is in the repository today. docs/ARCHITECTURE.md describes the design; docs/ROADMAP.md lists what is implemented versus planned.

Argus is an early open-source foundation, meant to be forked and extended. The platform core (tenancy, auth, RBAC, audit chain, queue, policy and approvals) is tested end to end on SQLite and PostgreSQL. The cloud and identity collectors and the action executors are tested against recorded fixtures and mocked APIs, not yet against live accounts, and the 12 detection rules are an untuned starting set. Expect to adapt collectors and rules to your estate, and run monitoring-only (docs/GO-LIVE.md) before enabling any action. It is not a certified product; see docs/COMPLIANCE.md for what it can and cannot evidence.

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 | +------------------------------------------------------------+ | 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):

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: 12 rules (swarm x4, identity x2, cloud, k8s, code, canary, anomaly, agentic), baselines, canaries implemented app/detections/, app/api/detections.py, app/api/canaries.py

Collectors: AWS, Azure, GCP, Kubernetes, GitHub, Okta, Entra, osquery, netflow implemented with fixtures; cloud SDKs optional app/collectors/, app/api/collectors.py

Test harness: scope policy, rate limits, adapters for web baseline, trivy, nuclei, zap, prowler, caldera, semgrep, gitleaks implemented; tools must be installed separately app/testing/, app/api/tests.py, app/api/scans.py

Agent runtime, providers (Anthropic, OpenAI, Ollama, none), read-only tools, 7 specialists, eval suites implemented app/agents/, app/api/agents.py, app/api/evals.py

Action broker: catalog of 25 typed actions (AWS, Azure, GCP, Kubernetes, GitHub, Okta, Entra, Cloudflare, Argus-internal), policy, approvals, dry run, execute, rollback, kill switch implemented app/actions/, app/api/actions.py

Integrations: 13 inbound parsers 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

Admin, assets, findings, events, investigations, approvals, audit, reports routers implemented app/api/

Alembic migrations (initial revision) 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.

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.

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.

.env: APP_ENV=production COOKIE_SECURE=true BASE_URL=https://host ARGUS_DOMAIN=host ACME_EMAIL=ops@example.com

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:

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

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), 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 tiers are limited to staging and lab environments. 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.

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/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 (evidence support, not certification)

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.

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.