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 IPI (Indirect Prompt Injection) module generates adversarial documents with hidden instructions, tracks execution via authenticated HTTP callbacks, and produces deployment playbooks for guided testing.

​
Module Structure

ipi/
├── generators/          # Format-specific document generators
│   ├── pdf.py           # Phase 1 + Phase 2 PDF techniques
│   ├── docx.py          # DOCX hiding techniques
│   ├── image.py         # Image/VLM techniques
│   ├── markdown.py      # Markdown hiding techniques
│   ├── html.py          # HTML hiding techniques
│   ├── ics.py           # Calendar invite techniques
│   └── eml.py           # Email techniques
├── generate_service.py  # generate_documents() — orchestrates generation
├── models.py            # Format, Technique, PayloadStyle, PayloadType, Campaign, Hit enums/dataclasses
├── listener.py          # start_server() — callback HTTP listener
├── server.py            # IPI callback server (FastAPI)
├── guidance_builder.py  # build_ipi_guidance() — deployment playbook generation
├── db.py                # IPI-specific SQLite operations (campaigns, hits)
├── cli.py               # generate, listen, techniques, formats, status, export, reset
├── adapter.py           # IPIAdapter for orchestrator integration
├── mapper.py            # persist_generate() — bridges campaigns to core DB
├── api.py               # Internal HTTP endpoints for bridge notifications
└── ui.py                # Web UI route handlers

​
Supported Formats and Techniques

7 document formats, each with format-specific hiding techniques:
FormatTechniques
PDFPhase 1: white_ink, off_canvas, metadata. Phase 2: tiny_text, white_rect, form_field, annotation, javascript, embedded_file, incremental
Imagevisible_text, subtle_text, exif_metadata
Markdownhtml_comment, link_reference, zero_width, hidden_block
HTMLscript_comment, css_offscreen, data_attribute, meta_tag
DOCXdocx_hidden_text, docx_tiny_text, docx_white_text, docx_comment, docx_metadata, docx_header_footer
ICSics_description, ics_location, ics_valarm, ics_x_property
EMLeml_x_header, eml_html_hidden, eml_attachment

​
Payload System

PayloadStyle controls the social engineering framing: obvious, citation, reviewer, helpful, academic, compliance, datasource. PayloadType controls the attack objective: callback (default, benign proof of execution), exfil_summary, exfil_context, ssrf_internal, instruction_override, tool_abuse, persistence. Non-callback types require the --dangerous flag.

​
Generation Pipeline

generate_documents() is the core function:
  1. For each technique in the request, call the format-specific generator
  2. Each generator embeds the payload instruction using the hiding technique
  3. A unique UUID and authentication token are generated per document
  4. The callback URL is embedded in the payload ({callback_url}/c/{uuid}/{token})
  5. Campaign records are created in the IPI database
  6. GenerateResult returned with list of campaigns and any errors

​
Callback Listener

qai ipi listen starts a FastAPI server that receives HTTP callbacks when AI systems execute the hidden payload. Hit model fields: uuid (campaign match), source_ip, user_agent, timestamp, token_valid (boolean), confidence (HIGH/MEDIUM/LOW). Confidence scoring:
  • HIGH — Valid campaign token present in the callback URL
  • MEDIUM — No token but User-Agent matches programmatic HTTP clients (python-requests, httpx, curl)
  • LOW — No token and browser/scanner User-Agent

​
WebSocket Bridge

The IPI listener runs as a separate process. When a hit arrives, it notifies the main qai web server via an internal HTTP POST to /api/ipi/internal/notify. Authentication uses a shared bridge token from ~/.qai/bridge.token. The --notify-url flag on qai ipi listen controls the target (defaults to http://127.0.0.1:8899). The web server broadcasts the hit via WebSocket so the IPI tab in the run results view updates in real time.

​
Guidance Builder

build_ipi_guidance() generates a RunGuidance with four blocks:
  • INVENTORY — Lists generated files with technique, callback URL, and token
  • TRIGGER_PROMPTS — Format-aware, profile-specific prompts (AnythingLLM, Open WebUI, Generic) designed to cause the target to ingest the document
  • DEPLOYMENT_STEPS — Ordered instructions for uploading and triggering
  • MONITORING — Confidence level explanations for interpreting hits
The web UI renders these as collapsible cards in the IPI run results tab.

​
Adapter

IPIAdapter wraps generation for orchestrator workflows. It creates a child run, calls generate_documents() via asyncio.to_thread(), persists results, builds guidance, and transitions to WAITING_FOR_USER status (since deployment is a manual step).

​
Database

IPI maintains its own tables (ipi_campaigns, ipi_hits) in the shared ~/.qai/qai.db SQLite database, accessed through ipi/db.py. Campaign data is also bridged to the core runs/findings tables via mapper.py.