> ## 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.

# CXP Module Architecture

> Context file poisoning for coding assistants

The CXP (Context File Poisoning) module builds poisoned instruction files for coding assistants and validates whether the assistant's output follows the injected rules. It tests whether AI coding tools blindly trust workspace configuration files.

## Module Structure

```
cxp/
├── builder.py           # build() — generates poisoned test repositories
├── catalog.py           # Rule catalog (get_rule, list_rules)
├── validator.py         # validate() — checks generated code against detection rules
├── guidance_builder.py  # build_cxp_guidance() — deployment playbook generation
├── models.py            # BuildResult, Rule, CampaignRecord, ValidationResult
├── formats/             # Format definitions for each assistant type
├── bases/               # Base repository templates
├── objectives/          # Attack objectives
├── rules/               # Rule definitions (YAML)
├── techniques/          # Technique implementations
├── prompt_reference.py  # Reference prompt generation
├── reporter.py          # generate_matrix(), export_poc()
├── db.py                # CXP-specific DB operations (campaigns, results)
├── cli.py               # formats, generate, record, campaigns, validate, report commands
├── adapter.py           # CXPAdapter for orchestrator integration
├── mapper.py            # persist to core DB
└── base_loader.py       # Base template loading
```

## Supported Formats

Each format targets a specific coding assistant's instruction file convention:

| Format ID              | Filename                          | Target Assistant |
| ---------------------- | --------------------------------- | ---------------- |
| `cursorrules`          | `.cursorrules`                    | Cursor IDE       |
| `claude-md`            | `.claude/instructions.md`         | Claude           |
| `copilot-instructions` | `.github/copilot-instructions.md` | GitHub Copilot   |
| `agents-md`            | `agents.md`                       | Gemini (agents)  |
| `gemini-md`            | `.gemini/instructions.md`         | Gemini           |
| `windsurfrules`        | `.windsurfrules`                  | Windsurf IDE     |

## Build Pipeline

`build()` generates a test repository:

1. Creates the repository directory structure from a base template
2. Writes the format-specific instruction file with injected rules
3. Generates a prompt reference file (suggested trigger prompts)
4. Returns `BuildResult` with repo\_dir, context\_file path, rules\_inserted list, prompt\_reference\_path

## Rule System

Rules are the injected instructions. Each rule has an `id`, `description`, and `category`. Examples: `hardcoded-secrets` (embed API keys), `shell-true` (use shell=True in subprocess), `extra-index-url` (add malicious package index).

Rules are defined in YAML files under `rules/`. The catalog (`catalog.py`) provides lookup and listing.

## Validation

`validate()` checks whether generated code follows the injected rules. Takes raw output text and a technique ID, returns a `ValidationResult` with verdict, matched rules, and detail text.

## Guidance Builder

`build_cxp_guidance()` generates a `RunGuidance` with four blocks:

* **INVENTORY** — Active rules with descriptions and categories
* **TRIGGER\_PROMPTS** — Format-specific curated prompts with override slot
* **DEPLOYMENT\_STEPS** — Instructions for opening the repo, verifying context file detection, triggering generation, and recording results
* **INTERPRETATION** — How to evaluate vulnerable vs. clean responses, with per-rule indicators

The trigger prompt can be overridden via `POST /api/cxp/{run_id}/trigger-override`.

## Adapter

`CXPAdapter` wraps `build()` for orchestrator workflows. It runs via `asyncio.to_thread()`, builds guidance, and transitions to `WAITING_FOR_USER` status (since testing the assistant is manual). The conclude campaign action marks the workflow as complete.

## Reporting

`report matrix` generates an assistant × technique comparison matrix (markdown or JSON). `report poc` exports a bounty-ready ZIP package for a specific test result.