phx-deps-audit
Audit Hex deps for supply-chain security risk — bidi chars, compile-time
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills/phx-deps-audit
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Hex Dependency Audit
Non-mutating supply-chain audit for Hex packages. Runs an 8-rule MVP catalogue
against changed packages, enriches with Hex API metadata, wraps existing tools
(mix hex.audit, mix_audit, OSV-Scanner), and emits a triage table.
When to Use
- After
mix deps.updateormix deps.getbrought in new versions - On PRs that touch
mix.lock(pre-merge gate) - Before manually updating a single package (
--preview <pkg>) - When investigating a dependency you don't recognize
Iron Laws
- NEVER claim a diff is clean without inspecting it. Run all 8 rules
on the unpacked NEW tarball. "Looks fine" without a tool run is a false
pass. Always write
.claude/deps-audit/last-run.json— its absence is evidence the audit didn't actually run. - NEVER install
mix_audit/osv-scanner— even if asked. Detect, warn with install instructions, skip cleanly if missing. If the user says "install it," respond with the install command (e.g.,mix deps.add mix_audit --only dev) and do not execute it. The audit skill is non-mutating;mix.exs/mix.lockare off-limits regardless of consent. - NEVER promote a finding to BLOCK without rule citation. Every finding
shows
rule_id,severity,file:line,snippet,message. No handwaving. - NEVER fetch from Hex API without rate-limiting. Cap at 5 req/sec. Cache metadata 7 days, top-500 list 1 day.
- NEVER run the audit on already-committed lock changes silently —
tell the user which mode (A/B/C) is active and which
(old, new)pairs resolved. - LLM triage only above threshold. Native rules + Semgrep + YARA
are deterministic. The
hex-deps-triageragent runs only when score10 (1 BLOCK or 3+ WARNs), and its verdicts are advisory — never auto-suppress a finding without human review.
Operating Modes
| Mode | Trigger | Old source | New source |
|---|---|---|---|
| B (default) | phx-deps-audit |
git show HEAD:mix.lock |
working mix.lock |
| C (PR) | phx-deps-audit --base main |
git show <ref>:mix.lock |
working mix.lock |
| A (preview) | phx-deps-audit --preview httpoison |
locked version | Hex API latest |
See references/operating-modes.md for full resolver logic.
Execution Flow
Default = full 8-rule scan with streaming progress. --quick opts out
to CVE + retirement only. See references/execution-flow.md.
Step 1: Resolve the diff
Parse the mix.lock Erlang term format for both old and new sources. Emit a
list of {pkg, old_version, new_version} tuples. Surface
new-only and removed-only packages separately (a removed package is not
audited; a brand-new package gets old_version = nil and skips diff-only
rules).
See references/diff-resolver.md for shell + mix run -e snippets per mode and the JSON output contract.
Step 2: Fetch tarballs (per-run tmpdir)
For each (pkg, old, new):
mix hex.package fetch <pkg> <old> --unpack -o ${AUDIT_TMPDIR}/tarballs/<pkg>/<old>/
mix hex.package fetch <pkg> <new> --unpack -o ${AUDIT_TMPDIR}/tarballs/<pkg>/<new>/
All ephemeral artifacts live under ${AUDIT_TMPDIR} (driver-owned, removed
on exit). See references/audit-tmpdir.md and
references/tarball-fetcher.md.
Step 3: Run the 8 MVP rules on each NEW tarball
| # | Rule | Sev | Method |
|---|---|---|---|
| 1 | Bidi Unicode control chars in .ex/.exs/.erl |
BLOCK | grep |
| 2 | Code.eval_* / :erlang.apply with non-literal MFA at module scope |
BLOCK | AST (Sourceror or regex+scope) |
| 3 | System.cmd / :os.cmd / Port.open at compile time |
BLOCK | AST |
| 4 | :erlang.binary_to_term/1 on literal without :safe |
BLOCK | AST |
| 5 | New :git/:path dep in mix.exs (vs old) |
BLOCK | AST diff |
| 6 | Maintainer change between versions | BLOCK | Hex API |
| 7 | Base64 blobs >256 chars outside priv/static/, test/fixtures/, assets/ |
WARN | regex |
| 8 | Levenshtein ≤2 from top-500 + download delta >1000× | BLOCK | Hex API + fuzzy |
Full catalogue (35 rules, MVP marked) in references/heuristics.md.
Bash + mix run -e implementations for all 8 MVP rules in
references/rules-impl.md (single-pass NEW + diff rules +
Hex API rules, with run_all_rules master loop).
Step 4: External tool wrappers (parallel)
mix hex.audit— retired-package check, always availablemix_audit— CVE check via GHSA, if installed (else warn + skip; do NOT install)osv-scanner— CVE check via OSV.dev, if installed (else warn + skip; do NOT install)
See references/external-tools.md for detection, output parsing, and severity mapping per tool.
Step 5: Hex API enrichment (per package)
GET /api/packages/:name— owners, downloads, inserted_atGET /api/packages/:name/releases/:version— per-release publisher- Compute:
days_since_publish,owner_age_days,download_velocity
Cap at 5 req/sec. Per-run cache under ${AUDIT_TMPDIR}/hex-api/.
See references/hex-api.md for endpoint contracts,
caching strategy, Rule 6/8 detection, and Levenshtein implementation.
Step 5.5: Apply hex_vet.exs ledger (if present)
If hex_vet.exs exists at project root, vetted-version findings are
downgraded to INFO. Unvetted versions retain their severity.
Lock-vs-ledger disagreement: lock wins. See the deps-vet skill's
hex-vet schema doc for the "Lock-vs-ledger disagreement" section.
Use phx-deps-vet <pkg> <version> (separate skill) to add entries.
Step 5.7: Differential subtract
When run with DIFFERENTIAL=1 (default), findings that existed in the
OLD tarball are downgraded to INFO. Net-new signals reach the renderer
at full severity. See references/differential.md.
Step 5.8: LLM triage (when score > threshold)
For packages where the aggregate score exceeds 10, the
hex-deps-triager sonnet agent reads finding + diff windows and
produces structured verdicts (confidence, verdict, rationale,
fp_reasons[]). A context-supervisor consolidates verdicts
across packages into triage/consolidated.md. Main skill reads only
the consolidated file.
See references/llm-triage.md.
Step 6: Score & render
Per-package weighted sum: BLOCK = 10, WARN = 3, INFO = 1. Risk band: 0 clean · 1–5 low · 6–15 medium · 16+ high.
Output:
- Stdout: markdown table —
pkg | old → new | risk | findings | diff.hex.pm | maintainer-changeplus a per-package detail section for any non-clean row. - Sidecar (MANDATORY): Write
.claude/deps-audit/last-run.jsonwithlock_sha,audit_passedandpolicy_modeat the top level — the gate's cache reads exactly these three; without them it never hits. Always emit, even on clean runs.
--json flag emits JSON to stdout instead of markdown. See
references/output-renderer.md for table format,
sidecar schema, exit-code rubric, and --quiet mode.
Out of scope / Phase 3 surface
- NEVER modify
mix.lock,mix.exs, or any project file (non-mutating) - NEVER auto-install missing tools (warn + skip)
- Gate
mix deps.{get,update,compile}viadeps-audit-gate.sh. Seereferences/hook.md. - Prompt for
phx-compoundafter BLOCK findings — corpus self-feeds. - Emit SARIF 2.1.0 via
--sarif <path>and gate CI via--ci.
References
references/heuristics.md— full 35-rule cataloguereferences/rules-impl.md— bash +mix run -efor the 8 MVP rulesreferences/operating-modes.md— Mode A/B/C resolverreferences/diff-resolver.md— shell snippets, lock parserreferences/tarball-fetcher.md— fetch wrapper, parallel cap, cache prunereferences/external-tools.md—mix_audit,osv-scannerwrappersreferences/hex-api.md— endpoint contracts, rate limit, Rule 6/8references/output-renderer.md— markdown, JSON v1, exit codes, SARIFreferences/testing.md— smoke runner, fixture matrixreferences/differential.md/llm-triage.md— Phase 2 NDJSON subtract + triagerreferences/semgrep.md/yara.md— Phase 2 precision layers (soft deps)references/cassettes.md/sarif.md/hook.md/ci-integration.md— Phase 3 surfacereferences/trusted-publishers.md/skill-checklist.md— upstream + evalreferences/audit-tmpdir.md— Phase 5 per-run ephemeral storage contractreferences/execution-flow.md/differential-cve.md— Phase 5 default scan + CVE diff
Files (claude-elixir-phoenix)
-
priv
-
semgrep
-
elixir-supply-chain.yaml 2.4 KB
Loading…
-
-
yara
-
hex-malware.yar 2.6 KB · in bundle
-
-
-
references
-
audit-tmpdir.md 8.6 KB
Loading… -
cassettes.md 8.3 KB
Loading… -
ci-integration.md 6.3 KB
Loading… -
diff-resolver.md 5.6 KB
Loading… -
differential-cve.md 5.6 KB
Loading… -
differential.md 6.7 KB
Loading… -
execution-flow.md 5.7 KB
Loading… -
external-tools.md 15.2 KB
Loading… -
heuristics.md 8.3 KB
Loading… -
hex-api.md 7.5 KB
Loading… -
hook.md 8 KB
Loading… -
llm-triage.md 5.8 KB
Loading… -
operating-modes.md 5.1 KB
Loading… -
output-renderer.md 10.8 KB
Loading… -
rules-impl.md 18 KB
Loading… -
sarif.md 6.1 KB
Loading… -
semgrep.md 6.6 KB
Loading… -
skill-checklist.md 3.9 KB
Loading… -
tarball-fetcher.md 7 KB
Loading… -
testing.md 6 KB
Loading… -
trusted-publishers.md 3.2 KB
Loading… -
yara.md 4.8 KB
Loading…
-
-
scripts
-
diff_cves.py 8.9 KB
Loading… -
diff_findings.py 7.8 KB
Loading… -
fetch_tarball.sh 3.1 KB
Loading… -
findings_to_sarif.py 5.5 KB
Loading…
-
-
SKILL.md 8.5 KB
--- name: phx-deps-audit description: Audit Hex deps for supply-chain security risk — bidi chars, compile-time exec, maintainer changes, typosquats, CVEs. Use after mix deps.update, when checking if a package upgrade is safe, or reviewing mix.lock PR diffs. --- # Hex Dependency Audit Non-mutating supply-chain audit for Hex packages. Runs an 8-rule MVP catalogue against changed packages, enriches with Hex API metadata, wraps existing tools (`mix hex.audit`, `mix_audit`, OSV-Scanner), and emits a triage table. ## When to Use - After `mix deps.update` or `mix deps.get` brought in new versions - On PRs that touch `mix.lock` (pre-merge gate) - Before manually updating a single package (`--preview <pkg>`) - When investigating a dependency you don't recognize ## Iron Laws 1. **NEVER claim a diff is clean without inspecting it.** Run all 8 rules on the unpacked NEW tarball. "Looks fine" without a tool run is a false pass. **Always write `.claude/deps-audit/last-run.json`** — its absence is evidence the audit didn't actually run. 2. **NEVER install `mix_audit` / `osv-scanner` — even if asked.** Detect, warn with install instructions, skip cleanly if missing. If the user says "install it," respond with the install command (e.g., `mix deps.add mix_audit --only dev`) and **do not execute it**. The audit skill is non-mutating; `mix.exs` / `mix.lock` are off-limits regardless of consent. 3. **NEVER promote a finding to BLOCK without rule citation.** Every finding shows `rule_id`, `severity`, `file:line`, `snippet`, `message`. No handwaving. 4. **NEVER fetch from Hex API without rate-limiting.** Cap at 5 req/sec. Cache metadata 7 days, top-500 list 1 day. 5. **NEVER run the audit on already-committed lock changes silently** — tell the user which mode (A/B/C) is active and which `(old, new)` pairs resolved. 6. **LLM triage only above threshold.** Native rules + Semgrep + YARA are deterministic. The `hex-deps-triager` agent runs only when score > 10 (1 BLOCK or 3+ WARNs), and its verdicts are advisory — never auto-suppress a finding without human review. ## Operating Modes | Mode | Trigger | Old source | New source | |------|---------|-----------|-----------| | **B** (default) | `phx-deps-audit` | `git show HEAD:mix.lock` | working `mix.lock` | | **C** (PR) | `phx-deps-audit --base main` | `git show <ref>:mix.lock` | working `mix.lock` | | **A** (preview) | `phx-deps-audit --preview httpoison` | locked version | Hex API latest | See `references/operating-modes.md` for full resolver logic. ## Execution Flow Default = full 8-rule scan with streaming progress. `--quick` opts out to CVE + retirement only. See `references/execution-flow.md`. ### Step 1: Resolve the diff Parse the `mix.lock` Erlang term format for both old and new sources. Emit a list of `{pkg, old_version, new_version}` tuples. Surface new-only and removed-only packages separately (a removed package is not audited; a brand-new package gets `old_version = nil` and skips diff-only rules). See `references/diff-resolver.md` for shell + `mix run -e` snippets per mode and the JSON output contract. ### Step 2: Fetch tarballs (per-run tmpdir) For each `(pkg, old, new)`: ``` mix hex.package fetch <pkg> <old> --unpack -o ${AUDIT_TMPDIR}/tarballs/<pkg>/<old>/ mix hex.package fetch <pkg> <new> --unpack -o ${AUDIT_TMPDIR}/tarballs/<pkg>/<new>/ ``` All ephemeral artifacts live under `${AUDIT_TMPDIR}` (driver-owned, removed on exit). See `references/audit-tmpdir.md` and `references/tarball-fetcher.md`. ### Step 3: Run the 8 MVP rules on each NEW tarball | # | Rule | Sev | Method | |---|------|-----|--------| | 1 | Bidi Unicode control chars in `.ex`/`.exs`/`.erl` | BLOCK | grep | | 2 | `Code.eval_*` / `:erlang.apply` with non-literal MFA at module scope | BLOCK | AST (Sourceror or regex+scope) | | 3 | `System.cmd` / `:os.cmd` / `Port.open` at compile time | BLOCK | AST | | 4 | `:erlang.binary_to_term/1` on literal without `:safe` | BLOCK | AST | | 5 | New `:git`/`:path` dep in `mix.exs` (vs old) | BLOCK | AST diff | | 6 | Maintainer change between versions | BLOCK | Hex API | | 7 | Base64 blobs >256 chars outside `priv/static/`, `test/fixtures/`, `assets/` | WARN | regex | | 8 | Levenshtein ≤2 from top-500 + download delta >1000× | BLOCK | Hex API + fuzzy | Full catalogue (35 rules, MVP marked) in `references/heuristics.md`. Bash + `mix run -e` implementations for all 8 MVP rules in `references/rules-impl.md` (single-pass NEW + diff rules + Hex API rules, with `run_all_rules` master loop). ### Step 4: External tool wrappers (parallel) - `mix hex.audit` — retired-package check, always available - `mix_audit` — CVE check via GHSA, if installed (else warn + skip; do NOT install) - `osv-scanner` — CVE check via OSV.dev, if installed (else warn + skip; do NOT install) See `references/external-tools.md` for detection, output parsing, and severity mapping per tool. ### Step 5: Hex API enrichment (per package) - `GET /api/packages/:name` — owners, downloads, inserted_at - `GET /api/packages/:name/releases/:version` — per-release publisher - Compute: `days_since_publish`, `owner_age_days`, `download_velocity` Cap at 5 req/sec. Per-run cache under `${AUDIT_TMPDIR}/hex-api/`. See `references/hex-api.md` for endpoint contracts, caching strategy, Rule 6/8 detection, and Levenshtein implementation. ### Step 5.5: Apply `hex_vet.exs` ledger (if present) If `hex_vet.exs` exists at project root, vetted-version findings are **downgraded to INFO**. Unvetted versions retain their severity. Lock-vs-ledger disagreement: lock wins. See the deps-vet skill's hex-vet schema doc for the "Lock-vs-ledger disagreement" section. Use `phx-deps-vet <pkg> <version>` (separate skill) to add entries. ### Step 5.7: Differential subtract When run with `DIFFERENTIAL=1` (default), findings that existed in the OLD tarball are downgraded to INFO. Net-new signals reach the renderer at full severity. See `references/differential.md`. ### Step 5.8: LLM triage (when score > threshold) For packages where the aggregate score exceeds 10, the `hex-deps-triager` sonnet agent reads finding + diff windows and produces structured verdicts (`confidence`, `verdict`, `rationale`, `fp_reasons[]`). A `context-supervisor` consolidates verdicts across packages into `triage/consolidated.md`. Main skill reads only the consolidated file. See `references/llm-triage.md`. ### Step 6: Score & render Per-package weighted sum: BLOCK = 10, WARN = 3, INFO = 1. Risk band: 0 clean · 1–5 low · 6–15 medium · 16+ high. Output: 1. **Stdout:** markdown table — `pkg | old → new | risk | findings | diff.hex.pm | maintainer-change` plus a per-package detail section for any non-clean row. 2. **Sidecar (MANDATORY):** Write `.claude/deps-audit/last-run.json` with `lock_sha`, `audit_passed` and `policy_mode` at the top level — the gate's cache reads exactly these three; without them it never hits. Always emit, even on clean runs. `--json` flag emits JSON to stdout instead of markdown. See `references/output-renderer.md` for table format, sidecar schema, exit-code rubric, and `--quiet` mode. ## Out of scope / Phase 3 surface - **NEVER modify** `mix.lock`, `mix.exs`, or any project file (non-mutating) - **NEVER auto-install** missing tools (warn + skip) - **Gate** `mix deps.{get,update,compile}` via `deps-audit-gate.sh`. See `references/hook.md`. - **Prompt** for `phx-compound` after BLOCK findings — corpus self-feeds. - **Emit** SARIF 2.1.0 via `--sarif <path>` and gate CI via `--ci`. ## References - `references/heuristics.md` — full 35-rule catalogue - `references/rules-impl.md` — bash + `mix run -e` for the 8 MVP rules - `references/operating-modes.md` — Mode A/B/C resolver - `references/diff-resolver.md` — shell snippets, lock parser - `references/tarball-fetcher.md` — fetch wrapper, parallel cap, cache prune - `references/external-tools.md` — `mix_audit`, `osv-scanner` wrappers - `references/hex-api.md` — endpoint contracts, rate limit, Rule 6/8 - `references/output-renderer.md` — markdown, JSON v1, exit codes, SARIF - `references/testing.md` — smoke runner, fixture matrix - `references/differential.md` / `llm-triage.md` — Phase 2 NDJSON subtract + triager - `references/semgrep.md` / `yara.md` — Phase 2 precision layers (soft deps) - `references/cassettes.md` / `sarif.md` / `hook.md` / `ci-integration.md` — Phase 3 surface - `references/trusted-publishers.md` / `skill-checklist.md` — upstream + eval - `references/audit-tmpdir.md` — Phase 5 per-run ephemeral storage contract - `references/execution-flow.md` / `differential-cve.md` — Phase 5 default scan + CVE diff
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.