Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

docs(case-study): ship the audit skill as a tracked, copyable file

Xerj Squad Afd6a846b758e
diff --git a/docs/case-studies/wordpress-security-audit/COVERAGE-AUDIT.md b/docs/case-studies/wordpress-security-audit/COVERAGE-AUDIT.md
index 5099a14e7..d2180c4e6 100644
--- a/docs/case-studies/wordpress-security-audit/COVERAGE-AUDIT.md
+++ b/docs/case-studies/wordpress-security-audit/COVERAGE-AUDIT.md
@@ -31,7 +31,7 @@ Everything here is reproducible; scripts are in
> **The full map is the reference.** [`PHP-DANGEROUS-FUNCTIONS.md`](sink-census/PHP-DANGEROUS-FUNCTIONS.md)
> is the readable table of all 275 functions; `sink-census/php_dangerous_functions.json`
> is the machine-readable source. This whole recipe is packaged as a copyable
-> Claude Code skill — see [`.claude/skills/xerj-security-audit/`](../../../.claude/skills/xerj-security-audit/SKILL.md).
+> Claude Code skill — see [`skill/SKILL.md`](skill/SKILL.md).
## Step 1 — Map the dangerous built-ins (the full reference)
diff --git a/docs/case-studies/wordpress-security-audit/README.md b/docs/case-studies/wordpress-security-audit/README.md
index cda40250b..5c6c14356 100644
--- a/docs/case-studies/wordpress-security-audit/README.md
+++ b/docs/case-studies/wordpress-security-audit/README.md
@@ -100,7 +100,7 @@ read; scale and durability come from XERJ.
zero gaps against grep, then AI-enrich into a queryable ledger (`sink-census/`).
- [`sink-census/PHP-DANGEROUS-FUNCTIONS.md`](sink-census/PHP-DANGEROUS-FUNCTIONS.md) —
the **full map of 275 dangerous PHP functions** (28 categories, taint-arg noted).
-- **Copyable Claude Code skill**: [`.claude/skills/xerj-security-audit/`](../../../.claude/skills/xerj-security-audit/SKILL.md)
+- **Copyable Claude Code skill**: [`skill/SKILL.md`](skill/SKILL.md)
— install it and run this whole workflow on your own codebase.
- [`FINDINGS.md`](FINDINGS.md) — the SSRF vulnerability, with verification and
reachability.
diff --git a/docs/case-studies/wordpress-security-audit/skill/README.md b/docs/case-studies/wordpress-security-audit/skill/README.md
new file mode 100644
index 000000000..6a53da159
--- /dev/null
+++ b/docs/case-studies/wordpress-security-audit/skill/README.md
@@ -0,0 +1,15 @@
+# xerj-security-audit — copyable Claude Code skill
+
+`SKILL.md` is a self-contained Claude Code skill that encodes the whole
+coverage-guaranteed whitebox audit workflow (setup → map → AST census → prove
+0 gaps → index → AI-enrich → reason).
+
+## Install
+```bash
+mkdir -p ~/.claude/skills/xerj-security-audit # or <repo>/.claude/skills/...
+cp SKILL.md ~/.claude/skills/xerj-security-audit/SKILL.md
+cp -r ../sink-census ~/.claude/skills/xerj-security-audit/ # the scripts + catalog
+```
+Then invoke it in Claude Code (`/xerj-security-audit`) or just ask to
+"run the XERJ security audit" on a target codebase. Retarget another stack by
+extending `php_dangerous_functions.json` (the taint model is data, not code).
diff --git a/docs/case-studies/wordpress-security-audit/skill/SKILL.md b/docs/case-studies/wordpress-security-audit/skill/SKILL.md
new file mode 100644
index 000000000..9b5631f45
--- /dev/null
+++ b/docs/case-studies/wordpress-security-audit/skill/SKILL.md
@@ -0,0 +1,94 @@
+---
+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
+**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.
+
+### 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.
+
+## 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.