Skip to content

oliver-kriska/claude-elixir-phoenix / targets/amp/skills/phx-deps-vet

phx-deps-vet

Verified

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.

FileKindSize
SKILL.mdskill md6.9 KB
priv/hex_vet_seed.exsother7.4 KB
references/hex-vet.mdmarkdown12.9 KB
references/seed.mdmarkdown4.4 KB

references/seed.md

View on GitHub
# Seed ledger — curated baseline of vetted Hex packages

`priv/hex_vet_seed.exs` ships with the plugin and provides a
**curated baseline of audits** for a hand-picked set of high-trust,
high-download Hex packages (currently ~30 — the monthly CI job in
"Regeneration" grows this toward the top-100).

It is a **provenance baseline, not certification of your project's
current `mix.lock`.** Seed versions are pinned; per `hex_vet.exs`
Iron Law #2 (lock wins), any locked version *newer* than the seed
entry stays unvetted. On an up-to-date stack the seed may certify
few or none of your actual locked deps — surface this to the user
*before* import, not after. The seed's lasting value is the trusted
provenance record + `:new_only` enforcement of *future* additions.

## Iron Laws (seed-specific)

1. **Seed entries are NOT a substitute for project-specific review.**
   They're a baseline; project-aware audits still take precedence.
2. **Stale seeds warn.** If `reviewed_at` is more than 90 days old at
   import time, emit a warning. Stale trust is more dangerous than
   no trust.
3. **Seed import is opt-in.** `phx-deps-vet --seed` requires an
   explicit `AskUserQuestion` confirmation; never silent.

## Schema

Same map shape as `hex_vet.exs`, but lives at
`../priv/hex_vet_seed.exs`:

```elixir
# Auto-generated by .github/workflows/seed-regen.yml on YYYY-MM-DD.
# Reviewer: <CI identity>.
%{
  generated_at: ~D[2026-05-12],
  source: "https://hex.pm/api/packages?sort=downloads",
  audits: [
    %{package: "jason",   version: "1.4.4",  criteria: :safe_to_deploy, ...},
    %{package: "phoenix", version: "1.7.21", criteria: :safe_to_deploy, ...},
    # ... ~28 more
  ]
}
```

## Import flow

```text
phx-deps-vet --seed

  Step 1: Code.eval_file priv/hex_vet_seed.exs.
  Step 2: Check generated_at; warn if > 90 days.
  Step 3: COMPUTE before prompting (Iron Law #6):
            - total = length(seed.audits)
            - split = Enum.frequencies_by(seed.audits, & &1.criteria)
            - vs existing ledger: new / overwrite / no-op counts
  Step 4: AskUserQuestion (numbers are the computed values, never
          estimates):
            "Import <total> curated audits into hex_vet.exs?
             - <split[:safe_to_deploy]> :safe_to_deploy,
               <split[:safe_to_run]> :safe_to_run (+ any others)
             - <new> new · <overwrite> overwrite · <no-op> no-op
             Note: provenance baseline — seed versions are pinned;
             newer locked versions stay unvetted (lock wins)."
  Step 5: On Yes: dedupe + merge + write back via Code.format_string!.
          On No: exit without modification.
  Step 6: Confirm: "Imported <N> entries; ledger now has <total>."
```

Existing audits never get silently overwritten — overwrites surface
in the confirmation prompt.

## Regeneration

Monthly CI job (`.github/workflows/seed-regen.yml`):

1. Query `https://hex.pm/api/packages?sort=downloads` for top-100.
2. For each, run Phase 1 rules + check Hex retirement.
3. Compose audit entries (criteria: `:safe_to_deploy` if zero BLOCKs).
4. Open a PR to update `priv/hex_vet_seed.exs`.

The job runs under the plugin's CI identity; the PR is human-reviewed
before merge. No auto-merge for security artifacts.

### Org-policy 403 fallback

Some org GitHub policies deny `GITHUB_TOKEN` PR creation. The seed-
regen and cassette-regen workflows both apply the same fallback
pattern when `peter-evans/create-pull-request@v6` exits with 403:

1. Upload the regenerated artifact (`priv/hex_vet_seed.exs` for seed,
   the cassettes tree for cassettes) as a workflow artifact.
2. Write a job summary explaining the policy and pointing to
   `Settings → Actions → Allow GitHub Actions to create and approve
   pull requests`.
3. Exit 0 — the regen succeeded even if the PR didn't.

Maintainers download the artifact, commit manually. The fallback is
the same in `cassette-regen.yml`; see `../../phx-deps-audit/references/cassettes.md`
"403 fallback".

## When to NOT use the seed

- Air-gapped or fork-restricted environments. The seed assumes
  upstream Hex; if your registry is internal-only, audit your local
  catalog instead.
- Hard-trust corporate-controlled packages — for those, project-level
  audits with internal reviewer emails are more legible in PR review.

## Future: distributed imports

cargo-vet's `imports:` field lets organizations trust **each other's**
audits via signed bundles. Phase 2 stubs the `imports:` key in the
schema but ignores its contents. Phase 3+ wiring TBD.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall