@vyuhlabs/dxkit 2.9.0 → 2.9.2

package/templates/.claude/skills/dxkit-allowlist/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: dxkit-allowlist
+description: Manage the dxkit allowlist over its whole lifecycle — list, inspect, audit (including orphaned entries after a re-baseline), remove stale entries, prune expired ones, and export Snyk-originated suppressions to a .snyk policy. Use when the user says "review our allowlist", "what suppressions do we have", "this allowlist entry is stale", "remove this fingerprint", "the allowlist drifted after re-baselining", "audit our accepted-risk entries", or "push our Snyk ignores back to Snyk". For the fix-vs-suppress DECISION and adding a new entry, defer to dxkit-action.
+---
+
+# dxkit-allowlist
+
+The allowlist is dxkit's per-finding suppression surface: a reviewed finding that the team has categorized (`false-positive`, `test-fixture`, `mitigated-externally`, `accepted-risk`, `deferred`) with a reason, so the guardrail lets it pass on future runs. It's the single source of truth across every scanner — native semgrep/gitleaks and ingested Snyk Code / CodeQL findings alike, all keyed on one fingerprint.
+
+This skill manages the allowlist's **lifecycle**: reviewing what's there, keeping it honest, and propagating decisions outward. For the upstream question — *should this be fixed instead of suppressed, and how do I add an entry* — that decision and the `add` path live in **dxkit-action**. Fix first; suppress second.
+
+## The lifecycle at a glance
+
+```
+add ──▶ list / show ──▶ audit ──▶ { renew | remove | prune } ──▶ export --snyk
+(dxkit-action)  inspect    keep honest   clean up                 propagate to Snyk
+```
+
+## Review what's suppressed
+
+```bash
+npx vyuh-dxkit allowlist list                # every entry (text); --json for structured
+npx vyuh-dxkit allowlist show <fingerprint>  # one entry's full detail
+```
+
+Reading is always safe — no mutation. Use these to brief the team on the overall suppression posture before a release or audit.
+
+## Audit — keep the allowlist honest
+
+```bash
+npx vyuh-dxkit allowlist audit                      # expired / soon-to-expire / missing-rationale
+npx vyuh-dxkit allowlist audit --soon-days=30       # widen the soon-to-expire window
+npx vyuh-dxkit allowlist audit --against-baseline   # ALSO flag orphaned entries
+```
+
+`audit` partitions entries into actionable buckets:
+
+- **expired** — past their `expiresAt`. The suppression no longer applies; the finding will re-flag on the next scan. Prune or renew.
+- **soon-to-expire** — within the window (default 14 days). `accepted-risk` / `deferred` entries approaching expiry should be re-justified or removed.
+- **missing-rationale** — no reason on the entry (only happens in sanitized mode when the gitignored reasons sidecar is absent).
+- **orphaned** — *only with `--against-baseline`*. The entry's fingerprint matches no finding in the committed baseline.
+
+### Orphaned entries — flag, never bulk-remove
+
+`--against-baseline` reads the committed baseline and reports entries whose fingerprint isn't present in the current finding set (it counts both each finding's own fingerprint and any cross-tool fingerprints absorbed into it, so an entry keyed on a collapsed contributor is *not* falsely flagged).
+
+**An orphan is not automatically stale.** Two things produce orphans:
+
+1. **The finding is genuinely gone** (fixed, file deleted) → the entry is dead weight; remove it.
+2. **Re-baselining churned the fingerprint** — semgrep is nondeterministic run-to-run, and cross-tool dedup can shift which tool's fingerprint represents a merged finding. The suppressed finding may still exist intermittently. Removing the entry would let it block a future PR.
+
+So treat the orphaned bucket as a **review queue**: confirm each finding is truly gone (re-run the analyzer and check the fingerprint is absent), *then* remove. Never script a bulk-remove of the orphaned set.
+
+## Remove a single entry
+
+```bash
+npx vyuh-dxkit allowlist remove <fingerprint>
+```
+
+Deletes one file-level entry. Use this for a confirmed-orphaned entry, or any stale-but-unexpired entry (which `prune` won't touch — `prune` removes only *expired* entries). No more hand-editing `.dxkit/allowlist.json`.
+
+## Prune expired entries
+
+```bash
+npx vyuh-dxkit allowlist prune --dry-run   # preview what would go
+npx vyuh-dxkit allowlist prune             # remove all expired entries
+```
+
+`prune` is the bulk counterpart to `remove`, scoped to expired entries only (those are unambiguously inactive). Run it periodically; renew anything still relevant before pruning.
+
+## The re-baseline → re-point flow (self-serve)
+
+After a baseline refresh, some fingerprints churn and a few valid suppressions orphan. The self-serve recovery:
+
+```bash
+npx vyuh-dxkit allowlist audit --against-baseline   # 1. discover orphans
+# 2. for each orphan: re-run the analyzer, confirm the finding is truly gone
+npx vyuh-dxkit vulnerabilities                      #    (grep output for the fingerprint)
+npx vyuh-dxkit allowlist remove <fingerprint>       # 3a. gone → remove
+npx vyuh-dxkit allowlist add --fingerprint=<new> …  # 3b. churned → re-point to the new fp (see dxkit-action)
+```
+
+> **Refresh the baseline in CI, not on your laptop.** A local `baseline create --force` bakes your machine's scanner versions into the committed baseline, which produces spurious tooling-drift warnings and phantom "resolved" findings on the next PR — and *causes* exactly this fingerprint churn. Use the bundled `dxkit-baseline-refresh` workflow (workflow_dispatch) so the canonical baseline is captured with CI's scanner versions. See **dxkit-ingest** for the refresh-job pattern.
+
+## Export to Snyk — propagate suppressions outward
+
+```bash
+npx vyuh-dxkit allowlist export --snyk            # writes ./.snyk
+npx vyuh-dxkit allowlist export --snyk --out=path/to/.snyk
+```
+
+When the team allowlists a **Snyk-originated** finding (one ingested via `dxkit-ingest`, `tool: snyk-code`), the decision lives only in dxkit by default — Snyk's own gate (`snyk code test`, the Snyk UI) still reports it as open. `export --snyk` closes that loop: it writes a `.snyk` policy ignoring every Snyk Code finding that maps to an *active* allowlist entry, keyed on the Snyk rule id + path, carrying the entry's reason + expiry. Expired entries are skipped; native semgrep/gitleaks findings don't export (no Snyk equivalent).
+
+This is the outbound mirror of the inbound sync dxkit already does (it honors Snyk's SARIF `result.suppressions` at ingest). The two are round-trip stable — an exported ignore re-read from Snyk's SARIF is suppressed, not double-counted.
+
+**Prerequisite:** Snyk Code (SAST) honors `.snyk` ignores only when the org has Snyk's "consistent ignores" feature enabled; SCA/dependency ignores are standard. Commit the `.snyk` so it applies in CI. It's opt-in — if dxkit is the only gate, you don't need it.
+
+## Stale inline annotations
+
+Inline `dxkit-allow:` annotations are a different surface (source-anchored, managed by `dxkit-action`'s `add` path). If the underlying finding is fixed but the annotation lingers, the next scan emits a `stale-allow` finding pointing at the orphaned comment. The fix is always to delete the comment — dxkit refuses to allowlist a stale-allow.
+
+## Hand-offs
+
+- For the **fix-vs-suppress decision** and **adding** a new entry (inline or file-level, the typed-category table, the canonical `add` path) → **dxkit-action**.
+- For **ingesting** Snyk/CodeQL findings in the first place, and the **CI baseline/deep-SAST refresh** jobs → **dxkit-ingest**.
+- For **ignore-file** (`.dxkit-ignore`) edits and policy tuning → **dxkit-config**.
+- For a **broken install** (guardrail not firing, command not found) → **dxkit-fix**.

package/templates/.claude/skills/dxkit-config/SKILL.md

@@ -155,7 +155,7 @@ A `npx vyuh-dxkit doctor` or `tools list` showing tools as missing **when they a
 1. Create / edit `.dxkit/tools.json` and add that directory to `probePaths`.
 2. Re-run `npx vyuh-dxkit tools list` — the tool should now show as available.
 3. If the user wants dxkit to *install* tools into a specific dir, set `installDir`, then `npx vyuh-dxkit tools install`.
-4. Regenerate the baseline so it reflects the now-available scanners: `npx vyuh-dxkit baseline create --force`.
+4. Regenerate the baseline so it reflects the now-available scanners — through the `dxkit-baseline-refresh` CI workflow, not a local `baseline create --force` (see "What NOT to do" for why).
 
 ## Workflow
 
@@ -163,11 +163,11 @@ When the user asks for a config change:
 
 1. Identify which file owns the concern (path exclusion → `.dxkit-ignore`; severity routing → `.dxkit/policy.json`; detection override → `.npx vyuh-dxkit.json`).
 2. Open the file, propose the edit, confirm.
-3. After writing, run `npx vyuh-dxkit baseline create --force` if exclusions changed (so the baseline doesn't carry stale findings from the now-excluded paths).
-4. Commit both: the config file + the regenerated baseline.
+3. If exclusions changed, refresh the baseline so it doesn't carry stale findings from the now-excluded paths — via the `dxkit-baseline-refresh` CI workflow, not a local `baseline create --force` (see "What NOT to do").
+4. Commit the config file; let CI refresh + commit the baseline.
 
 ## What NOT to do
 
 - Don't edit `.dxkit/cache/` or `.dxkit/reports/` — they're regenerated on every run (gitignored).
-- Don't manually mutate `.dxkit/baselines/main.json` — use `baseline create --force` to regenerate.
+- Don't manually mutate `.dxkit/baselines/main.json` — regenerate it. And regenerate it in CI (the `dxkit-baseline-refresh` workflow), NOT with a local `baseline create --force`: a local refresh bakes your machine's scanner versions into the committed baseline, so the next PR's guardrail emits spurious `TOOLING-DRIFT` warnings and phantom "resolved" findings when CI's versions differ. A local `--force` is fine only for the first capture or a throwaway experiment.
 - Don't add `.dxkit/` to `.dxkit-ignore` — dxkit itself doesn't scan its own outputs.

package/templates/.claude/skills/dxkit-fix/SKILL.md

@@ -91,7 +91,7 @@ If doctor flags a tool (git, dotnet, node, npm, a scanner) as missing but the cu
 2. Add that directory to `.dxkit/tools.json` `probePaths` (hand off to **dxkit-config**, which documents the file).
 3. Re-run `npx vyuh-dxkit doctor` to confirm it now resolves.
 
-This matters: an undetected scanner means `baseline create` silently captured ZERO findings for that tool's category — re-baseline (`baseline create --force`) once detection is fixed.
+This matters: an undetected scanner means `baseline create` silently captured ZERO findings for that tool's category — refresh the baseline once detection is fixed. Do that through the `dxkit-baseline-refresh` CI workflow, not a local `baseline create --force`: a local refresh records your machine's scanner versions in the committed baseline, so the next PR's guardrail emits spurious `TOOLING-DRIFT` warnings and phantom "resolved" findings when CI's versions differ.
 
 ## Capturing the FIRST baseline — be deliberate
 

package/templates/.claude/skills/dxkit-ingest/SKILL.md

@@ -88,6 +88,8 @@ Compiled languages (Java, C#, Kotlin, Go) need a working build for CodeQL extrac
 
 Ingested findings flow through the same aggregate as native findings, so they appear in the vulnerability report (with the engine as the `tool`), get a stable fingerprint, dedupe against any overlapping semgrep finding, and — with `--graph-context` — carry the enclosing symbol + blast radius the agent needs to fix safely. That graph enrichment is the part the source engine's own autofix doesn't have.
 
+> **Step [4] belongs in CI, not on your laptop.** Adding ingested findings changes the finding set, so the baseline must be refreshed to pick them up. Do that through the bundled `dxkit-baseline-refresh` workflow (workflow_dispatch / post-merge), NOT a local `baseline create --force`. A local refresh bakes your machine's scanner versions into the committed baseline; when they differ from CI's, the next PR gets spurious `TOOLING-DRIFT` warnings and phantom "resolved" findings. Refresh the snapshot AND the baseline from CI so both are captured with CI's tool versions.
+
 ## Keeping it fresh (CI)
 
 Add a scheduled refresh (mirrors `dxkit-baseline-refresh`): a CI job with the `SNYK_TOKEN` secret runs `ingest --from-snyk` and commits the updated snapshot. The bundled `--with-deep-sast-refresh` workflow (`workflow_dispatch`) does exactly this; its `method` input picks `api` (Enterprise, quota-free) or `cli` (free/team, one test per run). The ingested findings are a point-in-time snapshot of the engine's last scan — re-ingest after the engine re-scans.