xerj-security-audit

name	xerj-security-audit
description	Coverage-guaranteed whitebox security audit of a codebase using XERJ + tree-sitter AST. Use when the user wants to security-review PHP (or other-language) code with a provable "we enumerated every dangerous call" guarantee, or asks to run the WordPress-style sink census / audit. Drives an index-once, query-read-reason loop; proves zero gaps against grep; enriches findings into a queryable ledger.

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.