> ## Documentation Index
> Fetch the complete documentation index at: https://ctpf.q-uestionable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Module Architecture

> Scanner pipeline, MCP connection, and multi-format reporting

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:

| Category            | Scanner           | What It Checks                             |
| ------------------- | ----------------- | ------------------------------------------ |
| `command_injection` | injection         | Tool parameters susceptible to injection   |
| `auth`              | auth              | Authentication and authorization gaps      |
| `token_exposure`    | token\_exposure   | Secret and token exposure in responses     |
| `permissions`       | permissions       | Privilege escalation via tool capabilities |
| `tool_poisoning`    | tool\_poisoning   | Malicious tool descriptions                |
| `prompt_injection`  | prompt\_injection | Indirect prompt injection vectors          |
| `audit_telemetry`   | audit\_telemetry  | Missing logging and monitoring             |
| `supply_chain`      | supply\_chain     | Supply chain integrity risks               |
| `shadow_servers`    | shadow\_servers   | Unauthorized MCP server detection          |
| `context_sharing`   | context\_sharing  | Cross-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.