Strix — Data Flow

docs / design / data-flow

← all docs

Strix — Data Flow

DFD Level 0 — Context

See ../../diagrams/03_context_dfd.html.

Strix, as one system, sits between the person/CI job invoking it, the target being tested, the LLM provider powering its agents, the run artifacts it writes to disk, and (optionally) the managed app.strix.ai cloud platform. Everything below decomposes the "Strix" box in that diagram.

DFD Level 1 — One scan, start to finish

See ../../diagrams/02_dataflow_pipeline.html for the sequence-diagram form. As a numbered flow, with the real function/class names:

  1. CLI entry: interface/main.py:main() parses strix --target ./app-directory via cli_args.py:parse_arguments(); validates Docker is installed and the sandbox image is present.
  2. Run preparation: _bootstrap_scan(args) -> scan_setup.py:prepare_run(args) generates a run_name, resolves the local directory into local_sources, computes diff-scope (for CI PR-diff runs), persists an initial run record.
  3. State init: interface/cli.py:run_cli(args) builds scan_config (targets, instructions, local_sources, scope_mode, scan_mode), instantiates report.state.ReportState(run_name) and registers it as the process-global.
  4. Orchestration entry: run_cli calls core.runner.run_strix_scan(scan_config=, scan_id=, image=, local_sources=, interactive=False, max_budget_usd=, max_turns=, status_sink=).
  5. Sandbox creation: runtime.session_manager.create_or_reuse() picks the docker backend, builds/starts one Kali-based container per scan with the local directory bind-mounted, NET_ADMIN/NET_RAW capabilities, and Caido proxy env vars injected container-wide; caido_bootstrap.bootstrap_caido() logs into the in-container Caido sidecar and opens a temporary project.
  6. Root agent construction: agents.factory.build_strix_agent(is_root=True, ...) renders the system prompt (always-loaded skills + the root-only orchestration directive) and assembles the root's tool list, ending in the finish_scan lifecycle tool.
  7. Root registration + child factory: runner.py builds ReportUsageHooks (budget/turn tracking), an AgentCoordinator, registers the root agent, and builds a child_agent_builder closure wired into the shared context dict as context["spawn_child_agent"].
  8. Root loop starts: core.execution.run_agent_loop(agent=root_agent, initial_input=build_root_task(scan_config), ...).
  9. Root agent turn: the model (via the OpenAI Agents SDK's Runner.run_streamed()) calls view_agent_graph, reads scope, and repeatedly calls create_agent(name=, task=, skills=[...]) to fan out specialists.
  10. Child spawn: create_agent -> context["spawn_child_agent"] -> execution.spawn_child_agent() -> builds a child SandboxAgent, registers it (parent_id=root_id), launches its own run_agent_loop() as a background task. The root's turn returns immediately — children run in parallel.
  11. Parallel tool execution inside the shared sandbox: each child calls exec_command (nmap/ffuf/sqlmap/nuclei/agent-browser/python3, via the SDK's Shell capability), apply_patch/view_image (Filesystem capability), and Strix-native tools like list_requests/repeat_request (Caido). All outbound HTTP from any shell subprocess is transparently intercepted by the container-wide Caido proxy.
  12. Finding a vulnerability: a child builds and validates a proof-of-concept, then calls create_vulnerability_report(title=, description=, cvss_breakdown=, poc_script_code=, evidence=, ...).
  13. Validation, dedup, persistence: tools/reporting/tool.py:_do_create() validates required fields, computes CVSS score/severity, calls report.dedupe.check_duplicate() (LLM-judged) against existing findings for this run — if not a duplicate, report_state.add_vulnerability_report() assigns vuln-NNNN and fires the vulnerability_found_callback (live display).
  14. Reporting back: the child calls agent_finish(result_summary=, findings=[...], success=True), which posts a completion report to the root's mailbox and marks the child completed.
  15. Root aggregation: the root, parked on wait_for_agents, wakes on the mailbox message, may spawn further specialists, and eventually calls finish_scan(executive_summary=, methodology=, technical_analysis=, recommendations=).
  16. Scan completion: finish_scan -> report_state.update_scan_final_fields(); the SDK's tool_use_behavior hook ends the root's Runner cycle; run_agent_loop() returns to runner.py.
  17. Artifact writing: report/writer.py — write_run_record() -> run.json; write_executive_report() -> penetration_test_report.md; write_vulnerabilities() -> vulnerabilities/vuln-NNNN.md per finding + vulnerabilities.csv + vulnerabilities.json; separately report/sarif.py:write_sarif_report() -> findings.sarif.
  18. Sandbox teardown: session_manager.cleanup(scan_id) closes the Caido client and deletes the Docker container (best-effort).
  19. CLI exit: the final report prints; process exits 2 if any vulnerabilities were recorded (for CI gating), else 0.

DFD Level 2 — Inside a validated finding (steps 12–14, expanded)

flowchart TD A["Child agent observes a candidate issue\n(e.g. reflected payload via repeat_request)"] --> B["Build + run a PoC\n(exec_command, proxy tools)"] B --> C{"PoC actually\ndemonstrates impact?"} C -- "no" --> B C -- "yes" --> D["create_vulnerability_report(...)\ntitle, description, cvss_breakdown,\npoc_script_code, evidence, code_locations"] D --> E["tools/reporting/tool.py: _do_create()\nvalidate required narrative fields +\nCVSS metric-by-metric enums"] E --> F["_calculate_cvss()\nscore + severity + vector"] F --> G["report/dedupe.py: check_duplicate()\nLLM judges: same root cause, same asset?"] G -- "duplicate" --> H["reject — return existing id to caller"] G -- "new" --> I["report_state.add_vulnerability_report()\nassign vuln-NNNN, append to run's list"] I --> J["vulnerability_found_callback\n(live CLI/TUI panel)"] I --> K["agent_finish(findings=[...])\n-> parent mailbox"]

Related: STRIX — Pipeline Stages, STRIX — Architecture (HLD), HLD.md, LLD.md.