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.

qai is a modular, layered system with seven security testing modules unified through a shared core infrastructure. Each module operates independently while leveraging common data storage, configuration, and runtime services.

​
Architecture Layers

Web UI Layer — FastAPI application server with HTMX for dynamic interactions, Jinja2 server-side rendering, and WebSocket channels for real-time run status and IPI hit notifications. Launched by running qai ui. Orchestrator Layer — Workflow registry, WorkflowRunner for background task execution, module adapters for lifecycle management. Manages parent/child run relationships and cross-module coordination. Service Layer — Typed query functions in q_ai.services (finding_service, run_service, evidence_service). Sits between the orchestrator/web layers and the core DB. Used by adapters for cross-module data queries (e.g., inject adapter querying audit findings) and by route handlers for template context loading. Module Layer — Seven security modules (audit, proxy, inject, chain, ipi, cxp, rxp), each with a CLI subcommand (Typer), adapter class for orchestrator integration, and mapper for DB persistence. Shared Core Layer — SQLite database (WAL mode, auto-migrating schema), configuration management (YAML + keyring + DB settings), FrameworkResolver for OWASP MCP Top 10 / MITRE ATLAS / CWE / OWASP Agentic Top 10 mapping, MitigationResolver for structured finding guidance, RunGuidance for deployment playbooks, LLM provider abstraction via litellm. MCP Layer — Shared MCP connection utilities (q_ai.mcp) for stdio, SSE, and Streamable HTTP transports. Used by audit, proxy, and inject modules.

​
Modules

ModulePurposeKey Features
auditMCP server vulnerability scanning10 scanners mapped to OWASP MCP Top 10, multi-format reports (JSON, SARIF, HTML, NDJSON, CSV)
proxyMCP traffic interceptionInteractive TUI, session recording, replay against live servers
injectTool poisoning and prompt injectionMulti-provider campaigns via litellm, NormalizedResponse scoring, evidence preservation
chainMulti-step attack pathsYAML chain definitions, blast radius analysis, detection rule generation (Sigma, Wazuh)
ipiIndirect prompt injection7 document formats, callback tracking with confidence scoring, deployment playbooks
cxpContext file poisoningCoding assistant instruction files, rule catalog, output validation
rxpRAG retrieval poisoningEmbedding model validation, domain profiles, retrieval rate measurement

​
CLI Structure

All modules share a consistent CLI structure via Typer subcommands: 
qai ui                           # Launch web UI
qai audit scan                   # Scan an MCP server
qai audit enumerate              # List server capabilities
qai inject campaign              # Run injection campaign
qai ipi generate                 # Generate adversarial documents
qai ipi listen                   # Start callback listener
qai chain run                    # Execute attack chain
qai cxp generate                 # Build poisoned instruction files
qai rxp validate                 # Measure retrieval rank
qai import                       # Import external tool findings
qai runs list                    # View run history
qai findings list                # View all findings
qai config set-credential        # Store provider API key
qai update-frameworks            # Check for upstream framework changes

​
Data Flow

  1. Run creation — User launches a workflow via web UI or CLI. The orchestrator creates a parent run and child runs per module.
  2. Module execution — Each module adapter runs its domain logic (scan, campaign, generate, validate). Results persist to SQLite via mapper functions.
  3. Cross-module queries — The service layer enables modules to query each other’s results. The inject adapter queries audit findings via finding_service to prioritize templates. The IPI adapter receives retrieval gates from RXP via the workflow orchestrator.
  4. Finding emission — Modules emit findings with severity, category, and framework IDs. The MitigationResolver generates structured remediation guidance per finding.
  5. Real-time updates — WebSocket broadcasts run status changes, progress messages, and IPI hit notifications to the web UI.
  6. Export — Results export as JSON bundles, SARIF, NDJSON, CSV, or HTML reports.

​
Configuration Precedence

CLI flags (highest priority)
  → Environment variables
    → Database settings (via Settings UI or qai config set)
      → YAML config file (~/.qai/config.yaml)
        → Built-in defaults (lowest priority)
Credentials follow a separate chain: environment variable → OS keyring → error.

​
Key Infrastructure Components

FrameworkResolver — Loads frameworks.yaml, maps assessment categories to OWASP MCP Top 10, MITRE ATLAS, CWE, and OWASP Agentic Top 10 technique IDs. Used by audit findings and displayed as pill badges in the web UI. MitigationResolver — Generates structured, tiered remediation guidance for findings. Loads mitigations.yaml covering all 10 OWASP MCP categories. Per-section provenance tracking. RunGuidance — Per-run deployment playbooks generated by IPI and CXP module adapters. Contains ordered GuidanceBlocks (inventory, trigger prompts, deployment steps, monitoring/interpretation). Provider Registry — Manages LLM providers for inject campaigns and chain execution. Supports cloud providers (Anthropic, OpenAI, Groq, OpenRouter) and local providers (Ollama, LM Studio) via litellm. Credentials stored in OS keyring. Bridge Token — Shared secret at ~/.qai/bridge.token for IPI callback listener ↔ web UI communication. Auto-generated on first use, no expiry. WorkflowRunner — Manages background task execution, parent/child run lifecycle, and WebSocket event broadcasting.

​
Next Steps