phx-deps-vet

Deps Vet — Hex package audit ledger

Review a Hex package version, run Phase 1 supply-chain rules against it,

prompt the user for a verdict, append the result to hex_vet.exs

(project-root audit ledger). Vetted versions get downgraded to INFO

on subsequent $elixir-phoenix:phx-deps-audit runs.

Run this AFTER $elixir-phoenix:phx-deps-audit to clear findings.

Run this BEFORE merging a mix.lock PR to certify new versions.

Usage

$elixir-phoenix:phx-deps-vet phoenix 1.7.21      # vet a single package version
$elixir-phoenix:phx-deps-vet --seed              # import curated baseline seed (~30 pkgs)
$elixir-phoenix:phx-deps-vet --list              # show existing ledger entries
$elixir-phoenix:phx-deps-vet --check             # cross-check mix.lock vs ledger

Iron Laws

1. NEVER auto-approve. Every entry MUST come from an AskUserQuestion

confirmation. Drive-by trust ruins the ledger's value.

1. Lock wins on disagreement. If mix.lock has version X and the

ledger vets X-1, emit INFO and treat X as unvetted. Don't silently

trust the older entry.

1. Ledger lives at project root. hex_vet.exs is a first-class

security artifact, visible in PR review. Don't move it into .claude/.

1. Round-trip via inspect/2. When appending, read the file with

Code.eval_file/1, mutate the map, and write back via

inspect(term, pretty: true, limit: :infinity). Hand-rolled string

appends drift over time.

1. Always show findings before prompting. The user must see what's

being vetted. No silent :safe_to_deploy defaults.

1. Confirmation counts are COMPUTED, never estimated. Any number in

an AskUserQuestion (criteria split, new/overwrite/no-op) MUST be

derived from the loaded data before prompting — e.g.

Enum.frequencies_by(seed.audits, & &1.criteria). Eyeballing the

file and approving on wrong numbers corrupts the consent.

Execution flow

Step 1: Locate or seed hex_vet.exs

If hex_vet.exs exists at project root:
    Read it via Code.eval_file/1
Else:
    Write the empty-ledger stub (see references/hex-vet.md §"Empty ledger")
    Inform user: "Created hex_vet.exs at project root."

Step 2: Branch by mode

• <pkg> <version> → single-vet path (Step 3-7).
• --seed → import priv/hex_vet_seed.exs. Before prompting,

Code.eval_file/1 the seed and compute (Iron Law #6): the

criteria split (Enum.frequencies_by(seed.audits, & &1.criteria))

and, against any existing ledger, exact new / overwrite / no-op

counts. Put those computed numbers in the AskUserQuestion. Also

state up front that the seed is a **provenance baseline, not

certification of your current mix.lock** (per Iron Law #2, seed

versions older than the locked ones stay unvetted). Ask before

overwriting existing entries.

• --list → render the audits table; exit.
• --check → compare ledger entries with mix.lock; warn on

drift. Read the lock via Code.eval_file("mix.lock") with

2>/dev/null — modern locks have quoted keys and emit a

found quoted keyword warning per package (tens of KB of noise that

gets persisted as an oversized tool result otherwise).

Step 3: Fetch the tarball (single-vet)

Run the deps-audit corpus loader. Cache lives at

~/.cache/phx-deps-audit/corpus/<pkg>/<version>/contents/. Use:

bash ../phx-deps-audit/smoke-test/corpus.d/fetch.sh \
    <pkg> <version>

Step 4: Run Phase 1 rules

Source the rules from ../phx-deps-audit/references/rules-impl.md.

Run run_all_rules over the cached dir. Write findings to a temp

vet-findings.jsonl. Set FINDINGS_FILE to override default path.

Step 5: Present findings

Print the findings table per ../phx-deps-audit/references/output-renderer.md.

On zero findings: say "No findings — vet from a clean baseline."

On any finding: show severity, file, line, snippet inline.

Step 6: Prompt for verdict

Call AskUserQuestion with these 4 options:

• :safe_to_deploy — full trust; findings investigated and cleared.
• :safe_to_run — trust in non-production envs only (test deps).
• :does_not_implement_crypto — Mozilla-style sub-criterion.
• Skip — defer decision; don't write an entry.

If any finding is BLOCK severity: default-highlight Skip. Require

explicit override before writing :safe_to_deploy over a BLOCK.

Step 7: Append to ledger

Read existing hex_vet.exs via Code.eval_file/1. Append the audit

map below to :audits. Write back via

Code.format_string!(inspect(...)).

%{
  package: "<pkg>",
  version: "<version>",
  criteria: <verdict_atom>,
  reviewer: "<git config user.email>",
  notes: "<user-provided one-liner OR findings summary>",
  reviewed_at: ~D[<today>]
}

Write back via Code.format_string!(inspect(term, pretty: true)).

Confirm to user: "Added <pkg> <version> to hex_vet.exs."

Integration

• Run after $elixir-phoenix:phx-deps-audit to clear vetted findings.
• Run before merging a mix.lock PR to certify new versions.
• Run $elixir-phoenix:phx-deps-vet --check to detect ledger drift vs mix.lock.
• $elixir-phoenix:phx-deps-audit auto-downgrades vetted findings to INFO.

References

• references/hex-vet.md — schema, parser, lookup
• references/seed.md — --seed flag, curated baseline
• ../phx-deps-audit/references/rules-impl.md — the

same rules $elixir-phoenix:phx-deps-audit runs

Out of scope (Phase 3+)

• Mix task surface — defer mix phx.deps_vet to a separate Hex

package phx_deps_vet for non-CC users.

• Block-on-unvetted enforcement — defer to a PreToolUse hook

that gates mix deps.get.

• Distributed imports — defer cargo-vet imports: until

trust-chain semantics are designed.