Claude Skill

deps-audit

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.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-plugins_elixir-phoenix_skills_deps-audit-4621ae4.zip · 89 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/deps-audit
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git 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.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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/references/audit-tmpdir.md and ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/references/heuristics.md. Bash + mix run -e implementations for all 8 MVP rules in ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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

  • ${CLAUDE_SKILL_DIR}/references/heuristics.md — full 35-rule catalogue
  • ${CLAUDE_SKILL_DIR}/references/rules-impl.md — bash + mix run -e for the 8 MVP rules
  • ${CLAUDE_SKILL_DIR}/references/operating-modes.md — Mode A/B/C resolver
  • ${CLAUDE_SKILL_DIR}/references/diff-resolver.md — shell snippets, lock parser
  • ${CLAUDE_SKILL_DIR}/references/tarball-fetcher.md — fetch wrapper, parallel cap, cache prune
  • ${CLAUDE_SKILL_DIR}/references/external-tools.md — mix_audit, osv-scanner wrappers
  • ${CLAUDE_SKILL_DIR}/references/hex-api.md — endpoint contracts, rate limit, Rule 6/8
  • ${CLAUDE_SKILL_DIR}/references/output-renderer.md — markdown, JSON v1, exit codes, SARIF
  • ${CLAUDE_SKILL_DIR}/references/testing.md — smoke runner, fixture matrix
  • ${CLAUDE_SKILL_DIR}/references/differential.md / llm-triage.md — Phase 2 NDJSON subtract + triager
  • ${CLAUDE_SKILL_DIR}/references/semgrep.md / yara.md — Phase 2 precision layers (soft deps)
  • ${CLAUDE_SKILL_DIR}/references/cassettes.md / sarif.md / hook.md / ci-integration.md — Phase 3 surface
  • ${CLAUDE_SKILL_DIR}/references/trusted-publishers.md / skill-checklist.md — upstream + eval
  • ${CLAUDE_SKILL_DIR}/references/audit-tmpdir.md — Phase 5 per-run ephemeral storage contract
  • ${CLAUDE_SKILL_DIR}/references/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 9.3 KB
    ---
    name: 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.
    effort: medium
    argument-hint: "[--base <ref> | --preview [pkg...]] [--quick] [--json] [--sarif <path>] [--ci] [--strict] [--no-differential] [--no-llm | --llm] [--trace]"
    ---
    
    # 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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/references/audit-tmpdir.md` and
    `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/references/heuristics.md`.
    Bash + `mix run -e` implementations for all 8 MVP rules in
    `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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
    `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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
    
    - `${CLAUDE_SKILL_DIR}/references/heuristics.md` — full 35-rule catalogue
    - `${CLAUDE_SKILL_DIR}/references/rules-impl.md` — bash + `mix run -e` for the 8 MVP rules
    - `${CLAUDE_SKILL_DIR}/references/operating-modes.md` — Mode A/B/C resolver
    - `${CLAUDE_SKILL_DIR}/references/diff-resolver.md` — shell snippets, lock parser
    - `${CLAUDE_SKILL_DIR}/references/tarball-fetcher.md` — fetch wrapper, parallel cap, cache prune
    - `${CLAUDE_SKILL_DIR}/references/external-tools.md` — `mix_audit`, `osv-scanner` wrappers
    - `${CLAUDE_SKILL_DIR}/references/hex-api.md` — endpoint contracts, rate limit, Rule 6/8
    - `${CLAUDE_SKILL_DIR}/references/output-renderer.md` — markdown, JSON v1, exit codes, SARIF
    - `${CLAUDE_SKILL_DIR}/references/testing.md` — smoke runner, fixture matrix
    - `${CLAUDE_SKILL_DIR}/references/differential.md` / `llm-triage.md` — Phase 2 NDJSON subtract + triager
    - `${CLAUDE_SKILL_DIR}/references/semgrep.md` / `yara.md` — Phase 2 precision layers (soft deps)
    - `${CLAUDE_SKILL_DIR}/references/cassettes.md` / `sarif.md` / `hook.md` / `ci-integration.md` — Phase 3 surface
    - `${CLAUDE_SKILL_DIR}/references/trusted-publishers.md` / `skill-checklist.md` — upstream + eval
    - `${CLAUDE_SKILL_DIR}/references/audit-tmpdir.md` — Phase 5 per-run ephemeral storage contract
    - `${CLAUDE_SKILL_DIR}/references/execution-flow.md` / `differential-cve.md` — Phase 5 default scan + CVE diff
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.