xerj-security-audit

# XERJ whitebox security audit Run a security review where **XERJ is the agent's second brain**: index the code once, then interrogate it — never load whole files. The deliverable is a *defensible coverage claim*, not a vibe. Scripts referenced below live in `docs/case-studies/wordpress-security-audit/sink-census/` (copy them alongside this skill to reuse in another repo). ## When to use - "Security-review this codebase / WordPress plugin / PHP app with coverage." - "Find the dangerous calls / sinks and prove we didn't miss any." - "Run the sink census / audit ledger." ## Prerequisites (state them, then set up) - XERJ running, ES-compatible, on `http://127.0.0.1:9200` (`xerj --insecure --data-dir ./data`). - `pip install tree-sitter tree-sitter-php` (+ the grammar for the target language). - The target source tree on disk. ## The loop (do these in order; report honestly at each step) ### 1. Map the dangerous functions (knowledge) Use `php_dangerous_functions.json` — 275 PHP built-ins/constructs across 28 categories (command/code exec, `unserialize`, include loaders, file r/w/delete, SSRF, SQL drivers, XXE, callables, variable-injection, reflection, weak crypto/ random, type-juggling, …), each with vuln class + the **taint-relevant argument**. For another framework/language, extend this map — it is data, not code. ### 2. Census every call site (AST) `python3 sink_census.py <src>` parses every file with tree-sitter and records ### 2b. Census the dangerous PATTERNS (the class a sink list misses) `python3 pattern_census.py <src>` AST-detects the non-function vulns — loose `==` / magic-hash, non-strict `in_array`, `strcmp`-with-array (`?login[]=`), `@` suppression, variable-variables, unsafe `setcookie`, `switch`-on-request, Host-header trust, ORDER-BY injection — into `wppatterns`. Semantic classes a census can't decide (SQL truncation, charset SQLi, second-order, phar, TOCTOU, upload-exec, is_numeric bypass, regex-anchor, session-fixation, wrong-context XSS) are catalogued in `php_dangerous_patterns.json` with detection guidance and swept by reasoning. FULL REFERENCE: `PHP-SECURITY-GUIDE.md` — every function AND pattern mapped to attack + detection + safe recipe. **every** call site of a catalogued function (calls, methods, constructs like `echo`/`include`/backtick, `new ReflectionFunction`). tree-sitter captures real calls regardless of formatting/namespacing — grep cannot. ### 3. PROVE coverage (the guarantee — do not skip) The census reconciles **every grep occurrence against the AST**, using AST string/comment/inline-HTML node ranges as the oracle. A clean run prints: ``` UNEXPLAINED: 0 => coverage PROVEN (0 gaps) ``` If UNEXPLAINED > 0, EVERY residual must be resolved (it is either a real call the extractor missed — fix the catalog/node-handling — or a proven non-call). Never report coverage while residuals are unexplained. ### 4. Index + triage (XERJ `wpsinks`) The census bulk-indexes one doc per call site (`file,line,fn,class,arg`). Query the risk profile; the rare high-value classes are the must-review set (in WP core: RCE-command 11, deserialization 13, SQL 200, SSRF 107). You can now *guarantee* you've seen every one. ### 5. AI-enrich into a ledger (`enrich_pipeline.py`) For each high-risk site: read the arg + enclosing code, decide `reachable` (request/cache/trusted/literal), `guarded` (which defense), `severity`, and a `verdict`; write it back to `wpsinks`. This is the embedding-pipeline analogue, but the enrichment is reasoned security judgement, and it accretes across runs. Enrich 100% of the rare classes; queue the long tail. ### 5b. Trace any sink through the API (`trace_sink.py <file> <line>`) Joins `wpsinks -> wpaudit -> wpauthz -> reverse callers` with NO local file access: the sink + verdict, the enclosing function's sources/sinks/sanitizer, its authz guards, and who calls it + whether they read a request source. The verdict flags a SOURCE->SINK candidate when a source and an unsanitized sink coexist in a function. (Reverse callers scan `_source` `calls` arrays because of the array-`term` engine bug, and restrict common method names like `load`/`query` to the same file to avoid class collision.) ### 6. Reason about the real bugs (the parts a census can't see) Sink coverage ≠ total coverage. Also sweep, using the other detectors in the case study: object-scoped authorization / IDOR (`wp_authz_graph.py`, `wp_checkuse_idor.py`), validator *completeness* (`wp_ssrf_ranges.py` — an incomplete allow/deny list, e.g. SSRF missing `169.254`), and sanitizer *composition* order (`wp_compose_index.py`). Verify each candidate by reading, then by executing the flow. Trace reachability to real input. ### 6b. Interprocedural taint (`taint_analysis.py`) Once the AST is exported, run source->sink taint over the XERJ call graph: every function that reads a request source, walked to every dangerous sink it can reach with no sanitizer on the path (ranked by severity, full path per flow). This is high-recall REACHABILITY triage, not precise per-argument data-flow — the SQL flows include WP_Query (safe) and intval-guarded sinks, so read each candidate. See `TAINT-ANALYSIS.md`. ### 6c. POP-gadget hunt (`gadget_hunt.py`) Trace every magic method (__wakeup/__destruct/__toString/__call/...) through the call graph to a dangerous call — the deserialization gadget surface. Flag the AUTO-triggered ones (unserialize/free/print) as the live gadgets. WP core: 0. See `GADGET-CHAINS.md`. ## Honesty rules (these make the result trustworthy) 1. Precision from the graph/facts; full-text only to navigate. FTS over raw code is noisy for security. 2. Verify by reading, then by executing (port the flow to a runnable language if no runtime). No claim from memory of the framework — cite pulled `file:line`. 3. Trace reachability to attacker-controlled input before calling something a bug. 4. No manufactured findings — a clean negative is a valid result. 5. Report substrate/engine bugs: an impossible query result means the tool is wrong, not reality. (Known XERJ caveats today: `term` on a keyword *array* matches only the first element — traverse `_source` in code for reverse call-graphs; boolean `term` matches as a string — use `"true"`.) 6. State the coverage claim precisely: *"every call to a catalogued dangerous function is enumerated with a proven-zero-gap census"* — not "we read the code." ## The coverage statement this earns > Every call to a known-dangerous built-in in the target (N sites, M functions, > K files) is enumerated with a proven-zero-gap AST census, indexed, and triaged > by vuln class; 100% of the command-exec / deserialization / SQL sinks carry an > AI verdict. ## Reuse in another repo Copy `docs/case-studies/wordpress-security-audit/sink-census/*` and this skill. Point `sink_census.py` at your tree; extend `php_dangerous_functions.json` (or add a language grammar + a parallel catalog) for your stack. The proof step and the enrichment loop are language-agnostic.