oliver-kriska/claude-elixir-phoenix / targets/dsh/skills/phx-deps-audit
phx-deps-audit
FlaggedAudit 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.
references/execution-flow.md
View on GitHub# Execution Flow (Phase 5)
Authoritative pacing for `/phx-deps-audit`. The SKILL.md "Execution Flow"
section is a thin pointer; the runtime contract lives here.
## Default = full scan
The default invocation runs **all 8 MVP rules** plus all available external
tools (`mix hex.audit`, `mix_audit`, `osv-scanner`) plus Hex API enrichment
plus the differential CVE pass.
**There is no interactive choice prompt** — heuristics run by default.
A "run heuristics?" prompt is a silent-failure footgun on large diffs:
the user picks "no" to save time, the skill reports "no findings," and a
bidi-char trojan lands in the lock with no warning.
```
/phx-deps-audit ← runs the full pipeline
/phx-deps-audit --base main
/phx-deps-audit --preview httpoison
```
## `--quick`: CVE + retirement only
The opt-out is `--quick`. When set, the audit skips the 8 native rules,
Hex API enrichment, and the differential CVE pass — keeping only:
- `mix hex.audit` (retired-package check)
- `mix_audit` (GHSA CVE check, current lock only)
Use case: very large diffs (>50 packages), CI gates where wall-time
matters more than novel-attack detection, or pre-PR triage where the
maintainer just wants to confirm no known-CVE updates are merging dirty.
Target latency on a 25-package update: **<10s**.
```
/phx-deps-audit --quick
```
Flag synonyms considered: `--cve-only`, `--no-heuristics`, `--fast`.
**`--quick`** was chosen for brevity and cultural alignment with
`mix test --quick`.
## Streaming progress
The full scan emits one line per package per phase to stdout:
```
[ 1/25] cowboy 2.13.0 — fetching tarball...
[ 2/25] cowlib 2.15.0 — fetching tarball...
...
[ 1/25] cowboy 2.13.0 — running rule 1 (bidi)...
[ 1/25] cowboy 2.13.0 — running rule 2 (eval)...
...
[ 1/25] cowboy 2.13.0 — Hex API: owners, downloads
[12/25] decimal 3.1.0 — running rule 8 (typosquat)...
[25/25] phoenix 1.8.7 — done (0 findings)
```
Streaming progress is the default: facing a silent terminal for 60-90s,
users assume the skill has hung and Ctrl-C before results come back.
Format spec:
- `[N/M]` — package counter (current/total), zero-padded to align
- `pkg ver` — package name and NEW version
- ` — ` em-dash separator
- Phase verb in present continuous (`fetching`, `running`, `enriching`)
- Phase noun (optional but encouraged)
Render to stdout, not stderr, so the user sees it interactively but
machine consumers (`--json`, `--sarif`) can suppress with `--quiet`.
## Suppressing progress
| Flag | Effect |
|------|--------|
| `--quiet` | No streaming output; final result only |
| `--json` | Implies `--quiet`; JSON to stdout |
| `--sarif PATH` | Implies `--quiet`; SARIF to PATH |
| `--ci` | Implies `--quiet`; exits non-zero on BLOCK |
## Phase ordering
Default pipeline in order. Each step is independent and parallelism-safe
unless noted.
1. **Resolve diff** — `(pkg, old, new)` tuples from mix.lock pair
2. **Fetch tarballs** — 4-way parallel; both OLD and NEW versions
3. **Run 8 native rules** on NEW tarballs (per-package, parallel up to 4)
4. **External CVE pass** — `mix_audit_diff` (OLD + NEW), then `diff_cves.py`
5. **External retirement** — `mix hex.audit` (current lock)
6. **Hex API enrichment** — owner, downloads, rule 6/8 (rate-limited 5/s)
7. **`hex_vet.exs` ledger** — downgrade vetted versions to INFO
8. **Differential native subtract** — Phase 2 `diff_findings.py`
9. **LLM triage** (if score >10 per package) — `hex-deps-triager` agent
10. **Render** — markdown table + sidecar JSON, with security-changelog headline
`--quick` skips steps 1, 3, 5b, 6, 7, 8, 9 — keeping only steps 1-lite,
2-lite (NEW only), 5a (`mix hex.audit`), 4-lite (`mix_audit` on NEW only,
no diff), and 10-lite (no headline, just table).
## When to break from these defaults
| Situation | Override |
|-----------|----------|
| CI gate, time-sensitive | `--quick --ci` |
| Pre-merge PR review | (default — full scan) |
| One-off package preview | `--preview pkg [pkg...]` (skips diff resolution) |
| Already-vetted batch | Run normally; `hex_vet.exs` handles downgrades |
| Air-gapped CI (no Hex API) | `--no-hex-api` (Phase 4 flag) |
## Wall-time budgets
| Diff size | Default scan | `--quick` |
|-----------|--------------|-----------|
| 1-5 packages | 5-15s | <3s |
| 10-25 packages | 30-90s | <10s |
| 50-100 packages | 2-4 min | 15-30s |
| 200+ packages | 5-10 min | <60s |
Measured on a real 25-package update (~75s default) with the 4-way
parallel fetcher.
## `--trace` flag (Iron Law #1 auditability)
Without a trace there is a verification gap: when the audit
reports "8 rules clean", there's no on-disk evidence the
rules actually ran. The tmpdir is gone, no Bash trace is captured by
ccrider, and a fast model could in principle synthesize a plausible
verdict from the lock-diff text alone — exactly the Iron Law #1 false
pass.
`--trace` writes a verifiable audit log to
`.claude/deps-audit/last-run.trace.log` documenting every shell command
the audit ran (one per line, prefixed with timestamp + duration):
```
2026-05-13T11:01:50.123Z [3.4s] mix hex.package fetch decimal 2.3.0 --unpack -o /tmp/phx-deps-audit-XXX/tarballs/decimal/2.3.0
2026-05-13T11:01:53.501Z [3.1s] mix hex.package fetch decimal 2.4.1 --unpack -o /tmp/phx-deps-audit-XXX/tarballs/decimal/2.4.1
2026-05-13T11:01:56.612Z [0.4s] grep -rP '[\x{202a}-\x{202e}\x{2066}-\x{2069}]' /tmp/phx-deps-audit-XXX/tarballs/decimal/2.4.1
...
```
The trace file is the single piece of evidence that Iron Law #1 was
upheld for a given run. It's not under `${AUDIT_TMPDIR}` — it survives
audit completion so a reviewer can verify after the fact. The model
SHOULD enable `--trace` by default when the gate hook is configured
(`policy.exs` exists), and otherwise leave it opt-in.
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 |