DieAudit

DieAudit is a local-first, Docker-orchestrated multi-agent code audit platform. It is designed to run practical security review workflows against real source projects with ACP agents, MCP tool sidecars, codebase-memory graph analysis, Semgrep, SCA, finding-specific markdown workspaces, validator fan-out, PoC generation, verification, judgement, and report artifacts.

The project is still early, but the repository is intentionally structured as a runnable open-source platform rather than a one-off demo.

What DieAudit Does

• Imports projects from Git URLs or zip uploads.
• Creates isolated workspaces and local artifact directories.
• Injects codebase-memory-mcp into ACP sessions for architecture, symbol, route, call-chain, and graph-backed trace evidence.
• Runs Agent Client Protocol runtimes through registered adapter templates.
• Starts Agent containers and MCP sidecars through Docker orchestration.
• Assigns each finding its own persistent folder and finding.md handoff file.
• Lets Whiteboard Swarm coordinate Trace Worker, Validator, Judger, PoC Writer, and PoC Verifier work against the same finding markdown.
• Runs per-finding Agent Swarm stages in parallel with configurable concurrency.
• Records Findings, Evidence, ValidationAttempts, AgentRuns, ContainerRuns, and report artifacts.
• Provides a React + Ant Design web UI for projects, audit runs, findings, reports, runtime state, sandbox controls, knowledge documents, and admin keys.

Architecture

For the detailed service and runtime design, see docs/architecture.md.

flowchart LR
  UI["React / Ant Design Web UI"] --> API["FastAPI Web API"]
  API --> DB["Postgres"]
  API --> Worker["Workflow Worker"]
  Worker --> Gateway["Agent Gateway"]
  Worker --> Workspace["Workspace Engine"]
  Worker --> Sandbox["Sandbox Runner"]
  Gateway --> DockerProxy["docker-socket-proxy"]
  Sandbox --> DockerProxy
  DockerProxy --> Docker["Docker Engine"]
  Docker --> Agents["ACP Agent Containers"]
  Docker --> MCP["MCP Sidecar Containers"]
  Agents --> MCP
  Agents --> CBM["codebase-memory-mcp stdio"]
  MCP --> Tools["Semgrep / SCA / Code Search / KB"]
  API --> Artifacts["Local Artifact Directory"]
  Worker --> Artifacts
  API --> Qdrant["Qdrant Knowledge Index"]

Loading

Core services in docker-compose.yml:

• nginx: Web/API gateway.
• web-ui: React frontend.
• web-api: FastAPI backend.
• workflow-worker: audit pipeline worker.
• agent-gateway: Agent, ACP, MCP, and runtime package orchestration.
• workspace-engine: project import, snapshots, and static workspace work.
• sandbox-runner: controlled target/PoC Docker execution.
• kb-indexer: document parsing and vector indexing.
• postgres, redis, nats, qdrant.
• docker-socket-proxy: limited Docker Engine API proxy.

Default artifact storage is local directory mounts under data/artifacts. MinIO is not part of the default Compose topology.

Current Production Path

The intended audit flow is:

project import
  -> snapshot
  -> structure discovery
  -> recon / orchestrator
  -> codebase-memory repository indexing inside ACP agents
  -> code-auditor fan-out
  -> Semgrep + SCA
  -> AuditRun Whiteboard Swarm
     -> selectively schedules Trace Worker, Validator, Judger, PoC Writer,
        and PoC Verifier work as needed
  -> per-finding Validator
  -> per-finding Judger
  -> per-finding PoC Writer
  -> per-finding PoC Verifier
  -> markdown/json reports
  -> runtime cleanup

CodeQL is not required by the default production path. Code graph context is provided by codebase-memory-mcp as an ACP stdio MCP server injected into agent sessions; no separate graph sidecar or pre-agent graph build is required.

Split-Service Architecture Baseline

The current architecture is moving to independent service images for web-api, workflow-worker, agent-gateway, workspace-engine, sandbox-runner, and kb-indexer, with shared domain and persistence code in services/platform-common. New deployments use the Alembic baseline under services/database/alembic.

This baseline intentionally does not migrate old development data from the earlier single-platform-image schema. Before starting the split-service stack against an existing local checkout, reset the Postgres volume or point POSTGRES_DB at a fresh database.

Quick Start

Requirements:

• Docker Desktop or Docker Engine with Compose v2.
• PowerShell on Windows, or Bash on Linux/macOS.
• Optional: a local Docker/HTTP proxy. This repository defaults to:
  • host-side pulls: http://127.0.0.1:7897
  • container build args: http://host.docker.internal:7897

Windows:

copy .env.example .env
.\scripts\bootstrap.ps1
docker compose --profile core up -d

Linux/macOS:

cp .env.example .env
./scripts/bootstrap.sh
docker compose --profile core up -d

Open:

• Web UI: http://localhost:8080
• Web API health: http://localhost:18000/health
• Agent Gateway health: http://localhost:18001/health

Create a persisted admin API key:

.\scripts\create-api-key.ps1 -Name bootstrap-admin -Scope admin

NAME=bootstrap-admin SCOPES=admin ./scripts/create-api-key.sh

The command prints the API key once. Use it as X-DieAudit-Api-Key in the UI or API clients.

Tool Images

Build the default tool images before real audits:

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
docker compose --profile tools build tool-mcp-image kimi-code-agent-image

Linux/macOS:

HTTP_PROXY=http://127.0.0.1:7897 \
HTTPS_PROXY=http://127.0.0.1:7897 \
docker compose --profile tools build tool-mcp-image kimi-code-agent-image

If you do not use a proxy, leave the proxy variables empty.

Running An Audit

1. Start the core profile.
2. Open the Web UI.
3. Add an API key if authentication is enabled.
4. Import a Git project or upload a zip project from the Projects page.
5. Go to Audit Runs.
6. Click 启动审计.
7. Configure:
   • enabled Agent stages,
   • Validator rounds,
   • per-stage concurrency,
   • Agent template names,
   • pre-guidance prompt,
   • runtime retention and network options.
8. Create the AuditRun.
9. Click 一键闭环 to run the full pipeline.
10. Review Findings, per-finding markdown, Evidence, ValidationAttempts, PoC results, and Reports.

Each finding has a stable artifact folder and a finding.md file. Finding scoped agents are instructed to read and update that markdown file, so the finding history is preserved across Whiteboard Swarm scheduled Trace Worker, Validator, Judger, PoC Writer, and PoC Verifier work.

Runtime Safety Model

• The application services do not mount /var/run/docker.sock directly.
• agent-gateway and sandbox-runner access Docker through docker-socket-proxy.
• Dynamic containers are labeled with dieaudit.managed=true, dieaudit.audit_run_id, dieaudit.project_id, dieaudit.role, and dieaudit.ttl.
• Each AuditRun gets a dedicated Docker network named dieaudit-run-{audit_run_id}.
• Workspaces are mounted read-only for agents and tools where possible.
• PoC containers default to no external network unless explicitly allowed.
• retain_runtime_on_failure=true keeps failed runtime state for debugging.

DieAudit executes untrusted code and AI-generated PoCs inside Docker containers. Do not expose a local deployment to untrusted users without additional network, host, authentication, and resource isolation.

Knowledge Base

The knowledge base accepts PDF, MHTML, HTML, Markdown, and text documents. Documents are chunked and indexed into Qdrant.

Default embeddings use a deterministic local hash provider so development Compose can run without an external embedding service. For semantic retrieval, configure an OpenAI-compatible embedding endpoint:

KNOWLEDGE_EMBEDDING_PROVIDER=openai-compatible
KNOWLEDGE_EMBEDDING_BASE_URL=https://embedding-provider.example/v1
KNOWLEDGE_EMBEDDING_API_KEY=...
KNOWLEDGE_EMBEDDING_MODEL=text-embedding-3-small
KNOWLEDGE_VECTOR_SIZE=1536
KNOWLEDGE_COLLECTION_NAME=dieaudit_knowledge_embeddings_v1
KNOWLEDGE_EMBEDDING_PROBE_ON_READINESS=true

Use a fresh Qdrant collection or reindex documents when changing embedding dimension or provider.

Configuration

Copy .env.example to .env for local development. Use .env.production.example as a deployment checklist.

Important production settings:

• DIEAUDIT_API_KEY or persisted API keys for authentication.
• PUBLIC_METRICS=false unless metrics are separately protected.
• ENABLE_DEMO_TEMPLATES=false.
• Keep workflow-worker enabled; it is the only durable audit pipeline runner.
• DEFAULT_SANDBOX_RUNTIME=runc.
• ALLOW_RUNC_SANDBOX=true.
• ALLOW_SANDBOX_EXTERNAL_NETWORK=false.
• ARTIFACT_STORAGE_BACKEND=local.

Check readiness:

Invoke-RestMethod http://localhost:8080/api/bff/runtime/readiness | ConvertTo-Json -Depth 10

curl -s http://localhost:8080/api/bff/runtime/readiness | jq .

More details are in docs/production-readiness.md.

Whiteboard Swarm

Each AuditRun has a shared Whiteboard graph. Agents use whiteboard-mcp to create cards, attach files, connect evidence, declare predecessor/successor gaps, search all cards, and submit complete chain evidence. The whiteboard-swarm stage starts a controller Agent that inspects the graph and selectively schedules Trace Worker, Validator, Judger, PoC Writer, or PoC Verifier runs through platform MCP tools. Source-to-sink chains are evidence produced inside this swarm workflow, not a separate top-level pipeline stage.

The Whiteboard database records are the source of truth. JSON snapshots are written under data/artifacts/whiteboards/{audit_run_id}/whiteboard.json for audit trail and report download.

Demo Profile

Demo and mock runtime surfaces are intentionally opt-in. Demo fixtures are intentionally excluded from the default startup path. The default bootstrap and startup path does not build or expose mock demo images unless explicitly requested.

Windows:

echo ENABLE_DEMO_TEMPLATES=true >> .env
.\scripts\bootstrap.ps1 -IncludeDemo
docker compose --profile core up -d

Linux/macOS:

echo ENABLE_DEMO_TEMPLATES=true >> .env
./scripts/bootstrap.sh --include-demo
docker compose --profile core up -d

Production template APIs should not expose mock templates when ENABLE_DEMO_TEMPLATES=false.

Development

Python:

python -m pip install -r services\platform\requirements.txt
python -m pip install -r services\mcp-tools\requirements.txt
python -m pip install -r services\web-api\requirements.txt
python -m pip install pytest pytest-asyncio requests-mock time-machine
python -m pytest
python -m compileall services\platform\app services\mcp-tools services\agents\kimi-code-agent services\web-api\app services\platform-common\dieaudit_common services\database\alembic\versions

Frontend:

cd services\web-ui
bun install --frozen-lockfile
bun run build

Compose validation:

docker compose --profile core config --services
docker compose --profile tools config --services

E2E smoke scripts:

.\scripts\e2e-smoke.ps1

./scripts/e2e-smoke.sh

The E2E scripts can skip real model execution when no model API key is configured.

Repository Layout

configs/                    Agent, MCP, model, nginx templates
docs/                       operational documentation
scripts/                    bootstrap, key creation, E2E, image pull helpers
services/platform/          FastAPI backend, ORM, runtime orchestration
services/platform-common/   shared split-service domain, schema, and persistence code
services/web-api/           split-service API/BFF surface
services/workflow-worker/   split-service audit pipeline worker
services/agent-gateway/     split-service agent and MCP runtime controller
services/workspace-engine/  split-service project import and snapshots
services/sandbox-runner/    split-service PoC and target execution
services/kb-indexer/        split-service knowledge ingestion and search
services/web-ui/            React + Ant Design frontend
services/mcp-tools/         MCP tool server implementation and tool images
services/agents/            ACP agent images
services/mock-*             opt-in demo fixtures
tests/                      Python and repo-structure tests

Roadmap

Near-term engineering work:

• More real-world end-to-end fixture audits.
• Better codebase-memory graph workflows per language/framework.
• Better sandbox target stack management.
• More precise dependency vulnerability normalization.
• Production-grade RAG embedding provider documentation.
• Runtime resource quotas and metrics dashboards.
• Hardening around multi-user authorization scopes.

Contributing

Contributions are welcome. See CONTRIBUTING.md.

For security reports, see SECURITY.md.

License

DieAudit is licensed under the GNU General Public License v3.0. See LICENSE.