Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.q-uestionable.ai/llms.txt

Use this file to discover all available pages before exploring further.

The chain module (q_ai.chain) executes YAML-defined multi-step attack chains. It supports dry-run tracing, live execution against real targets, blast radius analysis, and detection rule generation.

​
Module Structure

chain/
├── loader.py            # load_chain(), load_all_chains() — YAML parsing
├── validator.py         # validate_chain() — graph/reference validation
├── tracer.py            # trace_chain() — dry-run execution path tracing
├── executor.py          # execute_chain() — live execution engine (5-module dispatch)
├── executor_models.py   # TargetConfig, StepOutput, ChainResult
├── blast_radius.py      # analyze_blast_radius(), write_blast_radius_report()
├── detection.py         # generate_detection_rules(), write_detection_rules()
├── variables.py         # Variable substitution in templates
├── artifacts.py         # Per-module artifact extraction (audit, inject, ipi, cxp, rxp)
├── models.py            # ChainDefinition, ChainStep, ChainCategory
├── templates/           # Built-in YAML chain definitions (6 templates)
├── cli.py               # validate, list-templates, run, blast-radius, detect commands
├── adapter.py           # ChainAdapter for orchestrator integration
└── mapper.py            # persist to core DB

​
Chain Definitions

Chains are YAML files with sequential steps. Each step specifies a module, technique, trust boundary, and dependencies. Key fields on ChainStep: id, name, module (audit/inject), technique, trust_boundary, on_success (next step), terminal (boolean), inputs (variable references). ChainCategory values: rag_pipeline, agent_delegation, mcp_ecosystem, hybrid.

​
Execution Modes

Dry run (--dry-run, default): trace_chain() walks the step graph without executing anything. Outputs the success-path execution order, trust boundaries crossed, and per-step technique details. Live execution (--no-dry-run): execute_chain() runs each step against real targets. The executor dispatches to five module executors:
ModuleExecutorWhat It Does
auditexecute_audit_step()Connects to MCP server, runs scanner
injectexecute_inject_step()Loads template, runs single-round campaign
ipiexecute_ipi_step()Generates poisoned documents, builds deployment guidance
cxpexecute_cxp_step()Builds poisoned context file repo, builds deployment guidance
rxpexecute_rxp_step()Runs retrieval validation against embedding model
IPI and CXP executors build deployment guidance (using the same build_ipi_guidance() / build_cxp_guidance() functions as standalone runs) and store it in the step’s artifacts. This guidance renders in the web UI when viewing chain execution detail.

​
Manual Gates

Steps with manual_gate: true in their inputs pause after execution and wait for the researcher to perform a manual action. The executor calls a gate_callback function that blocks until the operator resumes (via the web UI “Resume” button or equivalent). If no gate callback is configured (e.g., running from CLI without web UI), manual gate steps fail with a clear error message.

​
Key Data Models

ChainResult — returned by both trace_chain() and execute_chain():
  • chain_name, success (boolean), step_outputs (list of StepOutput)
  • trust_boundaries_crossed (ordered list)
  • started_at, finished_at
StepOutput — per-step result:
  • step_id, module, technique, order
  • success, error, artifacts (dict with step-specific data like finding_count, best_outcome, and guidance for IPI/CXP manual gate steps)
  • trust_boundary, started_at, finished_at
TargetConfig — loaded from chain-targets.yaml:
  • Audit connection details (transport, command/URL)
  • Inject model (provider/model format, falls back to QAI_MODEL env var)
  • Override via --inject-model CLI flag

​
Blast Radius

qai chain blast-radius --results <file> reads a chain execution report and produces an attack path analysis: what data was reached, which systems were touched, which trust boundaries were crossed, and the ordered attack path. Output formats: JSON or HTML.

​
Detection Rules

qai chain detect --results <file> generates detection rules from successful execution steps. Supported formats: Sigma (YAML) and Wazuh (XML). Rules include technique identification and are generated only for steps that succeeded.

​
Adapter

ChainAdapter wraps chain execution for orchestrator workflows. Uses fail_fast error handling — if any step fails, the chain stops. Findings are emitted for each failed step. The adapter provides a gate_callback that integrates with the orchestrator’s wait_for_user() mechanism for manual gate steps.

​
Proxy Correlation

Proxy sessions can be correlated with chain execution via chain_run_id and chain_step_id fields on SessionStore. When a chain runs audit steps that go through the proxy, the captured traffic is tagged with the chain execution context. This enables post-execution analysis of which network traffic was generated by which chain step.