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 audit module (q_ai.audit) scans MCP servers for security vulnerabilities. It connects to a server, enumerates its tools/resources/prompts, runs scanner checks against them, and produces findings mapped to security frameworks.

​
Module Structure

audit/
├── orchestrator.py      # run_scan() — coordinates connection, enumeration, scanning
├── scanner/
│   ├── registry.py      # Scanner registration and lookup
│   └── *.py             # Individual scanner implementations (one per OWASP MCP category)
├── reporting/
│   ├── json_report.py
│   ├── sarif_report.py
│   ├── html_report.py
│   ├── ndjson_report.py
│   └── csv_report.py
├── cli.py               # scan, enumerate, list-checks, report commands
├── adapter.py           # AuditAdapter for orchestrator integration
└── mapper.py            # persist_scan() — bridges ScanFinding → core Finding for DB

​
Scan Pipeline

  1. Connect — MCPConnection (from q_ai.mcp) opens a stdio, SSE, or Streamable HTTP connection to the target server
  2. Enumerate — enumerate_server() discovers tools, resources, and prompts
  3. Scan — run_scan() runs all registered scanners (or a filtered subset via --checks) against the enumerated capabilities
  4. Map — Each scanner produces ScanFinding objects with a category field (e.g., command_injection, auth). The FrameworkResolver populates framework_ids with OWASP MCP Top 10, MITRE ATLAS, CWE, and OWASP Agentic Top 10 mappings.
  5. Report — Results serialize to JSON, SARIF, HTML, NDJSON, or CSV
  6. Persist — persist_scan() maps ScanFinding → core Finding model for database storage

​
Scanner Registry

Scanners are registered in scanner/registry.py. Each scanner targets one OWASP MCP Top 10 category:
CategoryScannerWhat It Checks
command_injectioninjectionTool parameters susceptible to injection
authauthAuthentication and authorization gaps
token_exposuretoken_exposureSecret and token exposure in responses
permissionspermissionsPrivilege escalation via tool capabilities
tool_poisoningtool_poisoningMalicious tool descriptions
prompt_injectionprompt_injectionIndirect prompt injection vectors
audit_telemetryaudit_telemetryMissing logging and monitoring
supply_chainsupply_chainSupply chain integrity risks
shadow_serversshadow_serversUnauthorized MCP server detection
context_sharingcontext_sharingCross-context information leakage
Use qai audit list-checks to see available scanners and their framework mappings.

​
Adapter

AuditAdapter integrates the audit module with the orchestrator for workflow execution. It creates a child run, calls run_scan(), persists results, and emits findings via the workflow runner.

​
Reporting

All report generators take a ScanResult object (containing findings, server info, scanner metadata) and produce formatted output. The --format flag on qai audit scan and qai audit report selects the format. SARIF output follows the OASIS SARIF 2.1.0 schema and is compatible with GitHub Code Scanning.