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/audit-tmpdir.md
View on GitHub# Audit Tmpdir — Ephemeral Per-Run Storage
The audit skill maintains **no persistent on-disk cache**. Every audit
invocation creates a fresh tmpdir, writes all working artifacts there,
and removes the tmpdir on exit (via `trap EXIT`).
The only persistent files the skill writes to the project are:
- `.claude/deps-audit/last-run.json` — sidecar consumed by the Phase 3
PreToolUse gate
- `.claude/deps-audit/policy.exs` — Phase 3 gate policy config (manually
created by the user; not generated by the audit)
Everything else — tarballs, mix_audit JSON, CVE diffs, hex API metadata,
findings NDJSON, SARIF output — lives in `${AUDIT_TMPDIR}` for the
duration of one audit run only.
## Why ephemeral, not persistent
The Phase 1-4 design used `.claude/deps-audit/cache/` with a 7-day
metadata TTL and `prune_cache()` for tarballs >30 days old. The
2026-05-13 design review identified three problems:
1. **Cache invalidation is hard.** Rules change between releases, lock
resolution semantics drift, and stale cache entries silently bypass
updated logic. The Phase 4 `cache_signature.json` plan tried to
protect against rule-version skew, but adds complexity that
ephemeral storage sidesteps entirely.
2. **Audit semantics demand reproducibility.** A run that says "no
vulnerabilities" must reflect today's GHSA cache and today's Hex
API, not last week's. Persistent caches encourage exactly the kind
of "but it passed yesterday" false comfort that supply-chain
tooling must resist.
3. **The latency cost is bounded and acceptable.** A 25-package audit
takes 60-90s cold (per virgil dogfood). The 4-way parallel tarball
fetcher is the same in both architectures — caching only saves the
second and subsequent runs of the *same* diff, which is a rare
workflow in practice (people don't re-audit identical locks).
## Driver pattern
Every entry-point into the audit MUST establish `AUDIT_TMPDIR` and
register the EXIT trap before any other work:
```bash
audit_main() {
# Establish per-run tmpdir + cleanup trap. This is the FIRST thing
# the driver does — before parsing args, before resolving the diff,
# before any tool invocation that writes state.
AUDIT_TMPDIR="$(mktemp -d -t phx-deps-audit-XXXXXX)" || {
echo "ERROR: mktemp failed" >&2
return 2
}
export AUDIT_TMPDIR
# shellcheck disable=SC2064
trap "rm -rf '${AUDIT_TMPDIR}'" EXIT
# ... resolve diff, fetch tarballs, run rules, diff CVEs, render ...
# All wrappers read AUDIT_TMPDIR from env.
}
```
The trap fires on:
- Normal exit (rc=0 success path)
- Non-zero exit (any function `return N` or `exit N` that bubbles up)
- Ctrl-C / SIGTERM (bash propagates these to EXIT)
- Shell errors under `set -e` (also flow through EXIT)
## Cross-tool-call handoff (CRITICAL — runtime reality)
`audit_main()` above describes **one** long-lived shell. The actual
runtime is different: each step of `/phx-deps-audit` is a **separate
Bash tool call** with a fresh shell. Consequences:
1. **`export AUDIT_TMPDIR` does NOT survive** between tool calls. The
var set in call N is gone in call N+1.
2. **Shell functions do NOT survive** either. `export -f` is bash-only
(no-op under the user's zsh) and useless across calls regardless.
3. **The EXIT trap in call N does NOT fire for call N+1.** Cleanup
must be an explicit final command (`rm -rf "$AUDIT_TMPDIR"`), not a
trap.
**Pattern — persist the path, re-read it everywhere.** First command:
```bash
AUDIT_TMPDIR="$(mktemp -d -t phx-deps-audit-XXXXXX)"
printf '%s' "$AUDIT_TMPDIR" > "${TMPDIR:-/tmp}/phx-audit-dir.txt"
echo "AUDIT_TMPDIR=$AUDIT_TMPDIR"
```
Every subsequent command re-reads it as its first line:
```bash
AUDIT_TMPDIR="$(cat "${TMPDIR:-/tmp}/phx-audit-dir.txt")"
```
Final command tears down both:
```bash
AUDIT_TMPDIR="$(cat "${TMPDIR:-/tmp}/phx-audit-dir.txt")"
rm -rf "$AUDIT_TMPDIR" "${TMPDIR:-/tmp}/phx-audit-dir.txt"
```
**Quoted-heredoc trap.** When a command writes a helper script via a
heredoc, a *quoted* delimiter (`<<'EOF'`) does NOT expand
`${AUDIT_TMPDIR}` — the script gets a literal `${AUDIT_TMPDIR}` that
is empty in its own shell, so paths collapse to `/tarballs/...` and
you get `mkdir: /tarballs: Read-only file system`. Either bake the
resolved path in with an **unquoted** heredoc:
```bash
AUDIT_TMPDIR="$(cat "${TMPDIR:-/tmp}/phx-audit-dir.txt")"
cat > "${AUDIT_TMPDIR}/fetch.sh" <<EOF
AUDIT_TMPDIR="${AUDIT_TMPDIR}"
EOF
```
…or keep the heredoc quoted and pass the path as `$1`. Never assume
the helper inherits the env.
If a subagent or helper spawns its own `mktemp -d` (e.g.,
`_mix_audit_run_with_lock` for tmpdir lock-swap), that's a separate
short-lived dir with its own `RETURN`/`EXIT` trap — nested cleanup,
not a leak. The audit-level `AUDIT_TMPDIR` is the outer envelope.
## Standard subdirectories
Convention (not enforced by code — every wrapper can place files
wherever, but consistency aids debugging):
```
${AUDIT_TMPDIR}/
├── lock.old # diff-resolver: HEAD/base mix.lock
├── lock.new # diff-resolver: working mix.lock
├── diff.json # diff-resolver: {changed, added, removed}
├── tarballs/<pkg>/<version>/ # unpacked Hex tarballs
├── hex-api/
│ ├── packages/<pkg>.json
│ └── top-500.json
├── mix-audit.json # mix_audit single-state output
├── cves_old.json # mix_audit on OLD lock (differential)
├── cves_new.json # mix_audit on NEW lock (differential)
├── diff_cves.jsonl # diff_cves.py output
├── findings.jsonl # native rule findings (current run)
└── findings.old.jsonl # native rule findings (OLD tarballs)
```
`last-run.json` is **not** under `${AUDIT_TMPDIR}` — it's copied to
`.claude/deps-audit/last-run.json` as the very last step of rendering,
just before the tmpdir is torn down.
## Migration from Phase 1-4 paths
| Phase 1-4 path | Phase 5+ path |
|----------------|---------------|
| `.claude/deps-audit/cache/lock.old` | `${AUDIT_TMPDIR}/lock.old` |
| `.claude/deps-audit/cache/lock.new` | `${AUDIT_TMPDIR}/lock.new` |
| `.claude/deps-audit/cache/diff.json` | `${AUDIT_TMPDIR}/diff.json` |
| `.claude/deps-audit/cache/<pkg>/<version>/` | `${AUDIT_TMPDIR}/tarballs/<pkg>/<version>/` |
| `.claude/deps-audit/cache/hex-api/...` | `${AUDIT_TMPDIR}/hex-api/...` |
| `.claude/deps-audit/cache/mix-audit.json` | `${AUDIT_TMPDIR}/mix-audit.json` |
| `.claude/deps-audit/cache/cves_old.json` | `${AUDIT_TMPDIR}/cves_old.json` |
| `.claude/deps-audit/cache/cves_new.json` | `${AUDIT_TMPDIR}/cves_new.json` |
| `.claude/deps-audit/cache/diff_cves.jsonl` | `${AUDIT_TMPDIR}/diff_cves.jsonl` |
| `.claude/deps-audit/cache/findings.jsonl` | `${AUDIT_TMPDIR}/findings.jsonl` |
| `.claude/deps-audit/last-run.json` | **unchanged — persistent** |
| `.claude/deps-audit/policy.exs` | **unchanged — persistent (user-owned)** |
References still containing the old `.claude/deps-audit/cache/` paths
are pre-Phase-5 wording that will be migrated incrementally.
## Removed: `prune_cache()`
The tarball-fetcher.md `prune_cache()` function (Phase 1) walked
`.claude/deps-audit/cache/` and `rm -rf`'d entries older than 30 days.
This function no longer exists — the EXIT trap obsoletes it.
## Removed: `cache_signature.json`
Phase 4's planned `cache_signature.json` (a sha256 of rule files +
commit SHA used to invalidate the cache on plugin upgrade) is dropped.
No cache, no invalidation problem.
## Fixture isolation
Smoke fixtures (`lab/deps-audit/smoke-test/{fixtures,corpus}.d/`) operate inside the
runner's own `mktemp -d`, NOT inside `AUDIT_TMPDIR`. This is by
design: fixtures must be runnable without the full audit driver
established. The fixture conventions are documented in `testing.md`.
## One-time migration: clean stale `.claude/deps-audit/cache/`
Projects audited under Phase 1-4 may have leftover tarballs at
`.claude/deps-audit/cache/<pkg>/<version>/`. These are cruft under the
ephemeral model — never read, never refreshed, just disk noise.
The driver SHOULD remove this directory at startup, once, if present:
```bash
# Run BEFORE establishing AUDIT_TMPDIR. Idempotent.
migrate_stale_cache() {
local stale=".claude/deps-audit/cache"
if [ -d "${stale}" ]; then
echo "info: removing stale Phase 1-4 cache at ${stale}" >&2
rm -rf "${stale}"
fi
}
```
This is a one-shot cleanup, not a recurring prune (there's no cache
to prune anymore). After the first v2.12.0 run on a project, the
directory stays gone.
## Hook compatibility
The Phase 3 PreToolUse gate hook (`deps-audit-gate.sh`) reads
`.claude/deps-audit/last-run.json` only. It doesn't touch
`${AUDIT_TMPDIR}` at all, so hook semantics are unchanged.
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 |