Claude Skill

phx-deps-vet

Record a vetted Hex package version in hex_vet.exs after a security review

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-targets_amp_skills_phx-deps-vet-4621ae4.zip · 12 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills/phx-deps-vet
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

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 phx-deps-audit runs.

Run this AFTER phx-deps-audit to clear findings. Run this BEFORE merging a mix.lock PR to certify new versions.

Usage

phx-deps-vet phoenix 1.7.21      # vet a single package version
phx-deps-vet my_dep github:org/repo@tag:v1.0   # vet a git/github/path dep pin
phx-deps-vet --seed              # import curated baseline seed (~30 pkgs)
phx-deps-vet --list              # show existing ledger entries
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.
  2. 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.
  3. Ledger lives at project root. hex_vet.exs is a first-class security artifact, visible in PR review. Don't move it into .claude/.
  4. 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.
  5. Always show findings before prompting. The user must see what's being vetted. No silent :safe_to_deploy defaults.
  6. 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. Its policy is
    block_on_unvetted: :new_only, so the deps gate now BLOCKS `mix deps.get`
    when a new unvetted dep appears (it was warn-only without a ledger).
    Set it to false to keep warn-only."

The stub always writes policy.block_on_unvetted explicitly. Never create a ledger without it: the gate infers :new_only from a bare ledger, and that silent switch from warn-only to blocking surprises users.

Step 2: Branch by mode

  • <pkg> <version> → single-vet path (Step 3-7).
  • <dep> <pin> where the pin starts with git:, github: or path: → non-Hex path. Use the exact pin the gate printed (phx-deps-vet my_dep github:org/repo@tag:v1.0); the gate matches it character for character. Skip Steps 3-4 (no Hex tarball). Show the mix.exs tuple and what the pin points at, and say that a branch:, a missing ref, or a path: is mutable: the vet records a decision, not reviewed content. Then Steps 6-7 with version: "<pin>". See hex-vet.md §"Non-Hex dep pins".
  • --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). Non-Hex pin entries are checked against mix.exs tuples, not lock versions.

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/scripts/fetch_tarball.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 phx-deps-audit to clear vetted findings.
  • Run before merging a mix.lock PR to certify new versions.
  • Run phx-deps-vet --check to detect ledger drift vs mix.lock.
  • phx-deps-audit auto-downgrades vetted findings to INFO.
  • policy.block_on_unvetted is enforced by the plugin's deps-audit-gate.sh PreToolUse hook on mix deps.get / mix deps.update.

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 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.
  • Distributed imports — defer cargo-vet imports: until trust-chain semantics are designed.
Files (claude-elixir-phoenix)
  • priv
    • hex_vet_seed.exs 7.4 KB · in bundle
  • references
    • hex-vet.md 12.9 KB
      Loading…
    • seed.md 4.4 KB
      Loading…
  • SKILL.md 6.9 KB
    ---
    name: phx-deps-vet
    description: Record a vetted Hex package version in hex_vet.exs after a security review
      — manages the audit ledger, not the scanner. Use to approve a dep after phx-deps-audit
      findings or to initialize hex_vet.exs.
    ---
    
    # 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 `phx-deps-audit` runs.
    
    Run this AFTER `phx-deps-audit` to clear findings.
    Run this BEFORE merging a `mix.lock` PR to certify new versions.
    
    ## Usage
    
    ```text
    phx-deps-vet phoenix 1.7.21      # vet a single package version
    phx-deps-vet my_dep github:org/repo@tag:v1.0   # vet a git/github/path dep pin
    phx-deps-vet --seed              # import curated baseline seed (~30 pkgs)
    phx-deps-vet --list              # show existing ledger entries
    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.
    2. **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.
    3. **Ledger lives at project root.** `hex_vet.exs` is a first-class
       security artifact, visible in PR review. Don't move it into `.claude/`.
    4. **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.
    5. **Always show findings before prompting.** The user must see what's
       being vetted. No silent `:safe_to_deploy` defaults.
    6. **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`
    
    ```text
    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. Its policy is
        block_on_unvetted: :new_only, so the deps gate now BLOCKS `mix deps.get`
        when a new unvetted dep appears (it was warn-only without a ledger).
        Set it to false to keep warn-only."
    ```
    
    The stub always writes `policy.block_on_unvetted` explicitly. Never create a
    ledger without it: the gate infers `:new_only` from a bare ledger, and that
    silent switch from warn-only to blocking surprises users.
    
    ### Step 2: Branch by mode
    
    - **`<pkg> <version>`** → single-vet path (Step 3-7).
    - **`<dep> <pin>`** where the pin starts with `git:`, `github:` or `path:` →
      non-Hex path. Use the exact pin the gate printed (`phx-deps-vet my_dep
      github:org/repo@tag:v1.0`); the gate matches it character for character.
      Skip Steps 3-4 (no Hex tarball). Show the `mix.exs` tuple and what the pin
      points at, and say that a `branch:`, a missing ref, or a `path:` is
      mutable: the vet records a decision, not reviewed content. Then Steps 6-7
      with `version: "<pin>"`. See hex-vet.md §"Non-Hex dep pins".
    - **`--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). Non-Hex pin
      entries are checked against `mix.exs` tuples, not lock versions.
    
    ### 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:
    
    ```text
    bash ../phx-deps-audit/scripts/fetch_tarball.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(...))`.
    
    ```elixir
    %{
      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** `phx-deps-audit` to clear vetted findings.
    - **Run before** merging a `mix.lock` PR to certify new versions.
    - **Run `phx-deps-vet --check`** to detect ledger drift vs `mix.lock`.
    - **`phx-deps-audit`** auto-downgrades vetted findings to INFO.
    - **`policy.block_on_unvetted`** is enforced by the plugin's `deps-audit-gate.sh`
      PreToolUse hook on `mix deps.get` / `mix deps.update`.
    
    ## 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 `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.
    - **Distributed imports** — defer cargo-vet `imports:` until
      trust-chain semantics are designed.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.