# Technical Specification: detonate
## 1. Overview & Architecture
`detonate` is an execution oracle for reflected cross-site scripting (XSS) payloads. It resolves whether a reflected HTTP response contains JavaScript that auto-executes under browser semantics.
```
┌────────────────────────┐
│ HTML Response │
└───────────┬────────────┘
│
┌───────────▼────────────┐
│ HTML5 Spec Parser │
│ (html5ever / scraper) │
└───────────┬────────────┘
│
┌───────────▼────────────┐
│ extract_executable_js │
│ (filter data blocks & │
│ interaction handlers) │
└─────┬────────────┬─────┘
│ │
┌─────────────▼──┐ ┌──▼─────────────┐
│ Engine::Jsdet │ │ Engine::Chrome │
│ QuickJS-WASM │ │ Headless DOM │
└─────────────┬──┘ └──┬─────────────┘
│ │
┌─────▼────────────▼─────┐
│ ExecutionProof │
│ (sinks, executed, err) │
└────────────────────────┘
```
### Engine Modes
1. **`Engine::Jsdet` (Default)**:
- Uses QuickJS compiled to WebAssembly (`jsdet-core`, `jsdet-browser`).
- Runs in-process with a simulated DOM/browser bridge (`BrowserBridge`).
- Fast (<1ms per fragment), lightweight, strictly bounded by WebAssembly fuel and memory caps.
2. **`Engine::Chrome` (Opt-in / Fallback)**:
- Drives real headless Chrome/Chromium via `--headless=new --dump-dom`.
- Serves an instrumented harness from an ephemeral HTTP server (`127.0.0.1:0`).
- Validates **mutation XSS (mXSS)** vectors where DOM re-serialization (e.g. `innerHTML` reassignment) mutates inert markup into executing script.
- Falls back to `Engine::Jsdet` when no Chrome binary is detected on `$PATH`.
---
## 2. Invariants & Guarantees
### False-Positive Resistance
- **Spec-Compliant Extraction**: Uses `scraper` (HTML5 tree building) to ignore `<script>` tags inside HTML comments (`<!-- -->`), `<textarea>`, `<title>`, `<style>`, or element attribute values.
- **Data Block Filtering (`is_js_type`)**: Filters out non-executable script blocks with `type` attributes such as `text/plain`, `application/json`, `importmap`, `speculationrules`, `text/html`, and `text/template`.
- **Auto-Firing Handler Restriction**: Only auto-firing event handlers (`onerror`, `onload`, `ontoggle`, `onpageshow`, `onfocusin`, `onanimation*`, `onbegin`, `onend`, `onrepeat`) are extracted. Interaction handlers (`onclick`, `onmouseover`) are excluded because they require user actions.
- **Iframe `javascript:` Navigation**: Only `javascript:` URIs inside auto-navigating frame tags (`<iframe>`, `<frame>`) are extracted. `<a>` href links are excluded.
### Resource Boundedness & Cleanup
- **Jsdet Sandbox**: Execution is bounded by fuel limit and memory ceiling (`detonation_config()`). Sandbox traps (`while(1){}` or OOM) return `ExecutionProof::failed(...)` with `fragments_run` preserved.
- **Chrome Engine**: Chrome execution is bounded by a 15-second deadline (`CHROME_TIMEOUT`). Standard output is asynchronously drained on a background thread to prevent OS pipe deadlock on large DOM dumps.
- **Process Group Isolation**: Chrome processes are spawned in a dedicated process group (`setpgid`). Upon completion or timeout, the entire process group is signaled (`SIGKILL`) to prevent lingering renderer/GPU helper processes.
### Loud Failure Reporting (Law 10 Compliance)
- Operational failures (missing browser binary, HTTP harness bind failure, sandbox traps, browser launch timeouts) return an `ExecutionProof` with `executed: false` AND `error: Some(reason)`.
- Callers check `proof.failed_to_run()` to distinguish an infra failure from a safe, non-executing payload.
---
## 3. Core Types & API Contract
### `ExecutionProof`
```rust
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
pub struct ExecutionProof {
pub executed: bool,
pub sink: Option<String>,
pub message: Option<String>,
pub sinks: Vec<SinkHit>,
pub fragments_run: usize,
pub error: Option<String>,
}
```
- `proves(expected: &str) -> bool`: Returns `true` if `executed` is `true` AND `message` matches `expected`.
- `failed_to_run() -> bool`: Returns `true` if `error` is `Some(...)`.
### `SinkHit`
```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SinkHit {
pub kind: String,
pub detail: String,
}
```
Recognized sink categories:
- Dialog: `alert`, `confirm`, `prompt`
- Network: `network` (`fetch`, `sendBeacon`, `XMLHttpRequest`)
- Code execution: `eval` (`eval`, `Function`)
- DOM write: `dom-write` (`document.write`, `document.writeln`, `element.innerHTML`)
- Window / Navigation: `popup` (`window.open`), `redirect` (`location`), `cookie`, `storage`
### Vector Catalogs
- `EXEC_PRESERVING_VECTORS`: Self-validating execution-preserving XSS evasion vectors.
- `MUTATION_XSS_VECTORS`: Self-validating browser-only mXSS vectors (`mutation::MUTATION_XSS_VECTORS`).
- `BREAKOUT_VECTORS`: Self-validating context-breakout vectors (`breakout::BREAKOUT_VECTORS`).
---
## 4. CLI Interface
### Usage
```bash
detonate --url <URL> [--body-file <FILE>] [--expect <ARG>] [--engine jsdet|chrome]
detonate vectors [--marker <MARKER>]
```
### Exit Codes
- `0`: Execution proven (`executed: true` and `--expect` matched if provided).
- `3`: Execution completed successfully, but no matching execution was proven (`executed: false` or `--expect` mismatch).
- `2`: Usage error, invalid CLI flags, or file IO error.