oliver-kriska/claude-elixir-phoenix / targets/amp/skills/phx-deps-vet
phx-deps-vet
VerifiedRecord 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
| priv/hex_vet_seed.exs | other | 7.4 KB |
| references/hex-vet.md | markdown | 12.9 KB |
| references/seed.md | markdown | 4.4 KB |
references/hex-vet.md
View on GitHub# `hex_vet.exs` — schema, parser, and lookup
The audit ledger. Lives at **project root**, alongside `mix.exs` and
`mix.lock`. Modeled on cargo-vet's `audits.toml` — same trust-chain
intent, idiomatic Elixir surface.
## Why project root, not `.claude/`
`hex_vet.exs` is a **deliverable security artifact**, not an ephemeral
sidecar. Three properties of root placement that `.claude/` doesn't
give us:
1. **Visible in PR review.** Adding a vetted dep shows up as a diff
line on the same file as `mix.lock`, prompting the reviewer to
look at both.
2. **CI-discoverable without configuration.** The triple
`mix.lock` / `mix.exs` / `hex_vet.exs` is recognizable —
security tooling can find the ledger without project-specific
config.
3. **Survives `.claude/` deletion.** Some teams treat `.claude/` as
per-developer state and gitignore it. The audit ledger has to be
shared.
Phase 1's `last-run.json` stays under `.claude/deps-audit/`
intentionally — that file is ephemeral run state, not durable trust.
## Schema
```elixir
# hex_vet.exs
%{
imports: %{
# Phase 3+ feature — distributed audit imports. Ignored in Phase 2.
# mozilla: "https://hg.mozilla.org/.../audits.toml"
},
audits: [
%{
package: "phoenix",
version: "1.7.21",
criteria: :safe_to_deploy,
reviewer: "oliver@ideax.sk",
notes: "Reviewed against rules 1-8; diff.hex.pm checked clean.",
reviewed_at: ~D[2026-05-12]
},
%{
package: "jason",
version: "1.4.4",
criteria: :safe_to_deploy,
reviewer: "team@example.com",
notes: "No findings; widely-used (>50M downloads).",
reviewed_at: ~D[2026-05-10]
}
],
policy: %{
criteria_required: :safe_to_deploy,
block_on_unvetted: :new_only # Phase 3 default; see Tri-mode section
}
}
```
### Tri-mode `block_on_unvetted` (Phase 3)
`block_on_unvetted` takes one of four modes (a legacy boolean is
normalized — see "Migration from Phase 2 boolean" below):
| Mode | Hook behavior | When to pick |
|------|---------------|--------------|
| `false` | Warn-only; `mix deps.get` exits 0 | Phase 2 compat; opt-out |
| `:new_only` | Block if PR ADDS an unvetted version; allow re-locks of already-locked unvetted pkgs | **Recommended default** for new projects |
| `:strict` | Block ANY `mix deps.get` while any locked version is unvetted | Mature ledger; enforce on whole graph |
| `:full` | Run Tier 2 audit pipeline (Semgrep + YARA + LLM) then apply `:strict` rules | High-stakes (financial, healthcare); accept 30-90s per `mix deps.get` |
**Why `:new_only` is the default:** strict mode fails CI on
existing repos before seed import; warn is too loose for teams
serious about supply-chain. `:new_only` blocks the specific risk
(introducing an unvetted dep) without holding the team hostage on
historical un-audited locks.
### Migration from Phase 2 boolean
The hook reads `policy.block_on_unvetted` and normalizes:
```elixir
defp normalize_block_mode(false), do: false
defp normalize_block_mode(true) do
IO.warn("""
block_on_unvetted: true is deprecated and will be removed in v4.0.
Replaced with :strict (same semantics). For new projects, consider
:new_only — blocks only NEW unvetted versions, allows re-locks.
""")
:strict
end
defp normalize_block_mode(mode) when mode in [:new_only, :strict, :full], do: mode
defp normalize_block_mode(other) do
raise "Invalid block_on_unvetted: #{inspect(other)} — must be one of: false, :new_only, :strict, :full"
end
```
The one-time `IO.warn` surfaces in `mix deps.get` output. Migrate
to `:strict` (drop-in) or `:new_only` (recommended) to silence.
### `:new_only` semantics
"New" means: the package+version pair in the **current** `mix.lock`
was NOT in `mix.lock` at the hook's reference commit (default:
`origin/main`, override via `PHX_DEPS_AUDIT_BASE`). The reference
diff isolates additions:
```bash
git show "${PHX_DEPS_AUDIT_BASE:-origin/main}":mix.lock 2>/dev/null \
> /tmp/mix.lock.base
diff <(awk '/^ "[^"]+":/' /tmp/mix.lock.base) \
<(awk '/^ "[^"]+":/' mix.lock) \
| grep '^>' | sed 's/^> *//'
```
Each added line is one `<pkg>: <version>` pair; block if any added
pair is missing from `audits`. Re-locks of already-locked unvetted
pkgs are ignored — those are pre-existing tech debt, not new risk.
### Non-Hex dep pins
`git:`, `github:` and `path:` deps have no Hex version, so their audit entry
stores a **pin** in `version`. The `deps-audit-gate.sh` hook (rule 5) builds
the same pin from the `mix.exs` tuple and clears a new non-Hex dep only when
an uncommented entry has the matching `package` and the exact `version`:
```text
<kind>:<source>[@<refkind>:<ref>]
{:my_dep, github: "org/repo", tag: "v1.0"} → github:org/repo@tag:v1.0
{:my_dep, git: "https://h/r.git", ref: "abc123"} → git:https://h/r.git@ref:abc123
{:my_dep, git: "https://h/r.git", branch: "main"} → git:https://h/r.git@branch:main
{:my_dep, path: "../my_dep"} → path:../my_dep
```
```elixir
%{
package: "my_dep",
version: "github:org/repo@tag:v1.0",
criteria: :safe_to_deploy,
reviewer: "oliver@ideax.sk",
notes: "Our own repository; reviewed at v1.0.",
reviewed_at: ~D[2026-11-02]
}
```
The block message prints the exact `phx-deps-vet <dep> <pin>` command, so
the pin never has to be typed by hand. Changing the tag or ref makes a new
pin, which needs a new vet (lock-wins, as for Hex versions). A `branch:`, a
tuple with no ref, and a `path:` all point at mutable content: the entry
records that someone accepted the dep, not that its current code was
reviewed. Prefer `tag:` or `ref:` for deps you vet. When `mix deps.update`
moves a branch-pinned dep, the hook allows it but tells Claude which commit
`mix.lock` held, so the new commits can be reviewed.
`mix igniter.install my_dep@github:org/repo` is judged before igniter writes
the tuple, so its pin is the argument after `my_dep@`: `github:org/repo`.
Pins containing `#` can't be matched, because the hook strips `#` comments
before matching (fail closed).
### Criteria atoms
Following cargo-vet's vocabulary, three Phase 2 criteria are
recognized:
| Atom | Meaning |
|------|---------|
| `:safe_to_deploy` | Reviewed; safe in production. Highest trust. |
| `:safe_to_run` | Safe in non-production envs (test/dev deps). |
| `:does_not_implement_crypto` | Sub-criterion; package contains no cryptographic implementation, so transitive crypto-review obligations don't apply. |
Other atoms are valid but unrecognized — Phase 2 treats them as a
softer match (logged, never trusted).
### Empty ledger stub
Used when `hex_vet.exs` doesn't exist. New ledgers default to
`:new_only` (Phase 3) — opt-in to enforcement on the additions
without blocking historical un-audited locks:
```elixir
%{
imports: %{},
audits: [],
policy: %{criteria_required: :safe_to_deploy, block_on_unvetted: :new_only}
}
```
## Parser
Use `Code.eval_file/1` — Elixir's own parser, no Sourceror needed:
```bash
# One-line read:
mix run --no-mix-exs -e '
{ledger, _} = Code.eval_file("hex_vet.exs")
IO.inspect(ledger.audits, limit: :infinity)
'
```
Inside a skill script the same call works via `mix run -e`. For lookup
performance, the ledger is small (target: <2,000 entries; 50K LOC
file). No streaming parser needed.
### Lookup function
```elixir
def vetted?(ledger, pkg, version, required \\ :safe_to_deploy) do
Enum.any?(ledger.audits, fn audit ->
audit.package == pkg and
audit.version == version and
meets_criteria?(audit.criteria, required)
end)
end
defp meets_criteria?(:safe_to_deploy, _required), do: true
defp meets_criteria?(:safe_to_run, :safe_to_run), do: true
defp meets_criteria?(other, other), do: true
defp meets_criteria?(_, _), do: false
```
`:safe_to_deploy` satisfies every requirement (deploy implies run).
`:safe_to_run` only satisfies `:safe_to_run`.
## Lock-vs-ledger disagreement (Day-1 decision: lock wins)
When `mix.lock` says `phoenix 1.7.21` and the ledger has an entry for
`phoenix 1.7.20`:
- The unmatched lock version (1.7.21) is **unvetted**.
- The orphaned ledger entry (1.7.20) is **informational** — emit an
INFO finding "ledger entry exists for older version 1.7.20; treating
1.7.21 as unvetted."
- The audit runs the full Phase 1 rule pass on 1.7.21 with normal
severities.
This is the conservative call. The alternative ("lock-version-or-higher
trust") would let attackers exploit version-bump attacks where the
ledger entry was approved on a safe version.
## Append flow
Round-trip through `inspect/2` to preserve Elixir term semantics:
```bash
mix run --no-mix-exs -e '
{ledger, _} = Code.eval_file("hex_vet.exs")
new_audit = %{
package: "<pkg>",
version: "<ver>",
criteria: :safe_to_deploy,
reviewer: System.cmd("git", ["config", "user.email"]) |> elem(0) |> String.trim(),
notes: "<notes>",
reviewed_at: Date.utc_today()
}
updated = Map.update!(ledger, :audits, &[new_audit | &1])
formatted = updated
|> inspect(pretty: true, limit: :infinity, width: 80)
|> Code.format_string!()
|> IO.iodata_to_binary()
File.write!("hex_vet.exs", formatted <> "\n")
'
```
`Code.format_string!/1` ensures the output matches the project's
formatter config (incl. `.formatter.exs` overrides). Test the
round-trip on a fixture before relying on it — version pinning matters.
## Migration from existing trust artifacts
For projects using ad-hoc trust mechanisms (a comment in `mix.exs`,
README sections, internal wiki pages), the seed-import flow
(`phx-deps-vet --seed`) lets a team bootstrap a real ledger from
the top-100 list and then layer in project-specific audits.
The seed is regenerated monthly; entries older than 90 days emit a
stale-warning. See `seed.md` for the regeneration job.
## Distributed imports (Phase 3 — single-source v1)
cargo-vet supports trusting other organizations' audit ledgers via
the `imports:` table. Phase 3 ships **explicit allow-list v1**: any
import URL listed in `imports` must be opted into per-project — no
implicit trust, no transitive imports.
### Schema
```elixir
imports: %{
# key = canonical handle, value = ledger URL
"elixir-phoenix-plugin" =>
"https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/main/plugins/elixir-phoenix/skills/deps-vet/priv/hex_vet_seed.exs"
}
```
The handle (left side) is the attribution the renderer uses when a
finding is downgraded via an imported audit: "vetted via
`elixir-phoenix-plugin` (imported)". The URL (right side) must
resolve to a file with the same `hex_vet.exs` map shape (`audits:` is
the only key consumed; `imports:` of the imported ledger is ignored
to prevent transitive trust chains).
### v1 allow-list
Phase 3 v1 hardcodes the recognized import set:
```elixir
@allowed_imports %{
"elixir-phoenix-plugin" =>
"https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/main/plugins/elixir-phoenix/skills/deps-vet/priv/hex_vet_seed.exs"
}
```
Imports listed in `hex_vet.exs` that aren't in `@allowed_imports` are
**ignored with stderr warning**, never silently trusted. Multi-org
imports (Phoenix team, EEF, etc.) stay drafted until the trust-chain
semantics are battle-tested through one full cycle of single-import
production use.
### Fetch + cache
Imports fetch on first use and cache 24h under
`.claude/deps-audit/cache/imports/<handle>.exs`. On cache miss or
TTL expiry, re-fetch via `curl -fsSL`. Fetch failures fall back to
the cached copy with a "stale import" stderr warning.
### Lookup precedence
```text
project audits (hex_vet.exs `audits:`)
↓ not found
imported audits (each allowed import, parallel)
↓ not found
unvetted (Phase 1 rules apply at full severity)
```
A local audit always wins over an import — explicit project trust
is more durable than implicit shared trust. Conflicts (local
`:safe_to_run` vs import `:safe_to_deploy`) resolve to local.
### Attribution in output
The renderer surfaces import provenance:
```text
phoenix 1.7.21 — vetted via elixir-phoenix-plugin (imported), :safe_to_deploy
plug 1.16.1 — vetted locally (oliver@ideax.sk, 2026-05-12), :safe_to_deploy
unknown 0.1.0 — unvetted (no local or imported audit)
```
Reviewers see exactly where the trust came from. Out-of-policy
imports (anything not in the allow-list) get a one-time stderr
warning `ignored import: <handle> — not in v1 allow-list` but
never silently downgrade severity.
### Publishing your org's audit ledger
The plugin's seed file is the reference shape. Mirror the pattern:
1. Maintain an `hex_vet.exs` (or any `.exs` returning the same map)
in a repository your team controls.
2. Open a PR to add your URL to the plugin's `@allowed_imports`.
3. Add a `README` covering: review process, criteria meaning for
your org, signing/checksums.
4. Cross-reference: your `hex_vet.exs` lists `imports:` of
`elixir-phoenix-plugin` for symmetry.
Allow-list reviews enforce trust-chain hygiene: a malicious import
URL would compromise every plugin user. The plugin maintainers are
the final gate.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |