Strix (STRIX) — Architecture Explainer

Generated 2026-08-14 from usestrix/strix (commit 8ca0c4a9) · github.com/usestrix/strix

1 · What Strix is

Strix spins up a disposable Docker sandbox loaded with real pentest tools, then hands control to a tree of AI agents — one orchestrator ("root"), many specialists ("children") — that actually probe a target, validate findings with a working proof-of-concept, and write a CI-ready report.

Explain-it-simply: Think of hiring a small team of penetration testers for an afternoon. One lead reads the brief and assigns specialists; each specialist runs their own tools and writes up anything they can prove is real; the lead collects it all into one final report. Strix is that team, except every "tester" is an AI agent and the office is a disposable container.
Precisely: strix.core.runner.run_strix_scan() is the single entry point every mode (headless CLI, interactive TUI) calls. It builds one AgentCoordinator, one shared Docker sandbox, a root SandboxAgent, and awaits core.execution.run_agent_loop() for it — child agents are spawned as independent asyncio.Tasks sharing the same sandbox.

2 · Who should read what

ReaderStart withThen
Non-technical§1 above§3 Module Map (Simple mode)
Security analyst§3 Module Mapdocs/design/data-flow.md
Junior developer§3 Module Map (Technical)docs/modules/*.md
Reviewer / architectdocs/design/HLD.mddocs/design/LLD.md

3 · Module map — click any box

Every box answers four questions: what happens, inputs/outputs, how the model is chosen (or "no model calls"), and what's deterministic vs. AI-driven.

1 · Entry
Interface
strix/interface/

CLI, interactive Go TUI, and the local read-only web viewer (strix view).

In: argv (strix --target ...) · Out: scan_config handed to core.runner
What happensmain.py:main() special-cases 'strix view' and 'strix auth' before dispatch. cli_args.py:parse_arguments() builds the full argparse surface. _bootstrap_scan() runs Docker preflight, warm_up_llm() (non-interactive), and scan_setup.py:prepare_run() (run name, local_sources, diff-scope). Dispatches to cli.py:run_cli() (headless) or interactive.py:run_tui() (default), both of which call core.runner.run_strix_scan().
How the model is chosenNo model calls of its own — warm_up_llm() only performs a connectivity check against whatever STRIX_LLM already resolves to (see config module).
Deterministic vs. AI-drivenArgument parsing, Docker/version preflight, run-directory naming, diff-scope computation for CI PR scans, and (in interface/viewer/) reading finished-run artifacts straight off disk to render the dashboard.
Depends on: core
2 · Orchestration
Core Orchestration
strix/core/

The multi-agent orchestration engine: AgentCoordinator, the turn loop, resume.

In: scan_config, target local_sources · Out: final RunResult + live agent-graph state
What happensrunner.py:run_strix_scan() is the single entry every mode funnels into: resolves the model, creates/reuses one Docker sandbox for the whole scan, builds the root agent, and awaits execution.py:run_agent_loop() for it. AgentCoordinator (agents.py) is the sole owner of cross-agent state — a mailbox model, not a call graph: coordinator.send() drops a message in a target's inbox and wakes it. spawn_child_agent() launches each child as an independent asyncio.Task sharing the same sandbox.
How the model is chosenNo model call directly — core resolves STRIX_LLM once (config.load_settings()) and shares one RunConfig(model=resolved_model) across the root and every child agent for the whole scan.
Deterministic vs. AI-drivenCoordinator state snapshotting/resume (agents.json, atomic write), mailbox routing, budget/turn-limit enforcement (hooks.py), lifecycle-tool stop-condition checking.
Depends on: agents, tools, runtime, report, config
Agent Construction
strix/agents/

Assembles one agent's tools and renders its system prompt.

In: role (root/child), scan_mode, skills list, scope context · Out: one SandboxAgent, ready for run_agent_loop()
What happensfactory.py:build_strix_agent() assembles _BASE_TOOLS + capabilities (Filesystem, Shell) + the lifecycle tool (finish_scan for root, agent_finish otherwise). prompt.py:render_system_prompt() resolves a skill list (_resolve_skills: caller-requested + always scan_modes/<mode> + always tooling/agent_browser + tooling/python + coordination/root_agent if root) and renders prompts/system_prompt.jinja against it. Root vs. child role is prompt-driven, not tool-driven — only the root's prompt includes the orchestration-only directive.
How the model is chosenNo model call here — this module only decides which model-schema style (chat-completions vs. native tool schema) a build should target, via config.models.uses_chat_completions_tool_schema().
Deterministic vs. AI-drivenTool-list assembly, skill-markdown loading and Jinja rendering are pure file/template operations with no model call.
Depends on: tools, skills, config
3 · Capabilities
Agent Tools
strix/tools/

Everything an agent can call: shell/browser/proxy, agent-graph, reporting, notes.

In: tool call from an agent (name + JSON args) · Out: bounded JSON/text result back to the agent
What happensagents_graph/tools.py implements the Graph-of-Agents primitives (create_agent, wait_for_agents, agent_finish). reporting/tool.py validates and files vulnerability reports. proxy/tools.py wraps the Caido GraphQL client for traffic inspection/replay. shell/apply_patch/view_image are SDK-native capabilities (exec_command, apply_patch, ViewImageTool) configured in agents/factory.py, not Python tool files.
How the model is chosenweb_search (Perplexity-backed) is the one tool that itself calls an external model API, gated by PERPLEXITY_API_KEY. Every other tool is either deterministic or a passthrough to the sandbox/report layer.
Deterministic vs. AI-drivenCVSS metric validation and scoring, output truncation/spilling (output_store.py), todo/notes CRUD persistence, mailbox message formatting.
Depends on: core, report
Runtime (Sandbox)
strix/runtime/

Creates the one shared Docker sandbox per scan and its Caido intercepting proxy.

In: scan_id, sandbox image, local_sources to mount · Out: live sandbox session + host-side Caido client
What happenssession_manager.py:create_or_reuse() picks the docker backend (backends.py), builds a Manifest (host bind-mounts or uploaded LocalDir entries), sets http_proxy/https_proxy/ALL_PROXY container-wide so all tool traffic routes through Caido, then calls docker_client.py's StrixDockerSandboxClient to start the container (NET_ADMIN/NET_RAW caps for nmap -sS, host.docker.internal routing) and caido_bootstrap.py to log into the in-container Caido sidecar and open a temporary project.
How the model is chosenNo model calls — pure infrastructure plumbing.
Deterministic vs. AI-drivenContainer lifecycle, manifest/mount construction, resource-limit application, Caido guest-login retry loop (readiness probe).
Depends on: config
4 · Post-scan
Findings
strix/report/

The in-memory + on-disk record of every finding, deduplicated and written out.

In: create_vulnerability_report() calls from agents · Out: strix_runs/<run>/ report.md, vulns/*.md, .csv, .json, .sarif
What happensstate.py's ReportState is the module-global singleton tracking vulnerability_reports for the run. dedupe.py:check_duplicate() judges whether a new candidate is the same root cause on the same asset as an existing finding before it's accepted. writer.py turns ReportState into on-disk Markdown/CSV/JSON; sarif.py builds a SARIF 2.1.0 document for CI/CD.
How the model is chosenreport.dedupe.check_duplicate() is an explicit LLM judge call — optionally a distinct, smaller model via DedupeSettings (STRIX_DEDUPE_MODEL) rather than the main scan model.
Deterministic vs. AI-drivenCVSS score/severity arithmetic once metric values are supplied, vuln-NNNN ID assignment, Markdown/CSV/JSON/SARIF rendering, dependency/CVE-finding dedup (identity-based, no LLM call for that path).
Depends on: config
5 · Foundation
Config & Model Routing
strix/config/

Resolves the LLM model/provider and every other tunable, once per scan.

In: env vars, ~/.strix/cli-config.json · Out: resolved Settings + StrixProvider for the whole scan
What happensloader.py:load_settings() (memoized) resolves with precedence env vars > ~/.strix/cli-config.json > defaults; persist_current() writes resolved env values back to that JSON file so they don't need re-exporting. models.py's StrixProvider subclasses the OpenAI Agents SDK's LiteLLM-backed MultiProvider.
How the model is chosenSTRIX_LLM (any LiteLLM-style id: openai/..., anthropic/..., bedrock/..., vertex_ai/..., openrouter/..., or a self-hosted endpoint via LLM_API_BASE) is the single model every agent in a scan uses, resolved once here.
Deterministic vs. AI-drivenSettings precedence resolution, provider-quirk predicate functions (is_claude_model, uses_chat_completions_tool_schema, etc.).
Internal Skills (Knowledge Packs)
strix/skills/

Markdown methodology library (vulnerabilities, tooling, coordination, scan modes).

In: role (root/child), scan_mode, is_whitebox flag · Out: skill markdown injected into the rendered system prompt, or fetched on demand
What happensPure content, no Python logic besides file lookup: 10 subdirectories (vulnerabilities/ is the largest at 25 files), loaded by agents/prompt.py at render time and by tools/load_skill/tool.py mid-run on demand. Distinct from the top-level repo skills/ folder, which targets external coding agents driving Strix, not Strix's own agents.
How the model is chosenNo model calls — static content.
Deterministic vs. AI-drivenEntirely — file lookup and Jinja templating only.

4 · The Graph of Agents

One "lead" agent never tests anything itself — it only reads the brief and assigns specialists. Each specialist can itself assign sub-specialists for a sub-task. When a specialist is done, it mails a summary back to whoever assigned it.

AgentCoordinator (strix/core/agents.py) is the sole owner of this tree: parent_of tracks structure, send()/mailboxes carry messages, and the whole state is periodically snapshotted to disk so strix --resume can reconstruct it after a crash. See diagrams/05_agent_graph_orchestration.svg.

5 · Explore the full documentation

Every deliverable this kit produced, one click away. Markdown is always the source of truth for anything with an .html mirror below — regenerate the HTML, never hand-edit it.

Diagrams

DiagramStatic (svg/png)Interactive
Architecture (layered view)01_architecture.svg01_architecture.html
Data flow (one scan, start to finish)02_dataflow_pipeline.svg02_dataflow_pipeline.html
Context diagram (DFD Level 0)03_context_dfd.svg03_context_dfd.html
Module dependencies (real CodeGraph data)04_module_dependencies.svg—
Agent-graph orchestration05_agent_graph_orchestration.svg—
Docker sandbox contents06_sandbox_container.svg06_sandbox_container.html
Standalone module map—diagrams/module-graph.html

Design docs

DocMarkdownHTML
High-Level DesignHLD.mdHLD.html
Low-Level DesignLLD.mdLLD.html
Data flow (DFD 0/1/2)data-flow.md—
Agentic framework & deterministic vs. LLM toolingagentic-framework.mdagentic-framework.html

Module docs (all 12 packages)

PackageMarkdownHTML
agentsagents.mdagents.html
corecore.md—
toolstools.md—
runtimeruntime.mdruntime.html
reportreport.mdreport.html
interfaceinterface.md—
configconfig.md—
skillsskills.md—
llmllm.md—
telemetrytelemetry.md—
utilsutils.md—
strix (root)00_root.md—

Full index with real file/LOC counts: docs/modules/README.md

Process & runbooks

DocMarkdown
Index00_process-and-runbooks-index.md
SOPprocess-operate-strix.md
Process optimizationprocess-optimization.md
Runbook: setup & credentialssetup-and-credentials.md
Runbook: run a detection scan ⚠run-a-detection-scan.md
Runbook: review & triage findingsreview-and-triage-findings.md

Real code-intelligence tool output

ViewOpen
codeviz — module → file → function drill-downstrix-codeviz.html
Stage explorer — S0–S15 → files → functionsstrix-stage-explorer.html
Graphify — named clusters (197 communities, no LLM)labeled-clusters.html
Graphify — curated call-flow diagramsstrix-callflow.html
Graphify — collapsible tree explorerGRAPH_TREE.html
Graphify — raw force-directed graph (dense)graph.html

Full index and how these were produced: docs/tools/graph-intelligence.md, tool-outputs/README.md

Start here / overview

DocMarkdown
Start here (persona reading paths)docs/00_START_HERE.md
Overviewdocs/01_overview.md