@xenos1996/usa 2.0.0 → 2.3.1

package/rules/core/provenance-cosign.yaml

@@ -0,0 +1,110 @@
+id: core/provenance-cosign
+title: Provenance Chain Verification (cosign)
+section: S3
+section_title: Supply Chain & Build Provenance
+description: >
+  Production-half chain verification for release provenance: these controls
+  cryptographically verify release artifacts against committed Sigstore
+  bundles and keys with a local `cosign` binary. They complement the
+  beta-level existence checks (SUP-013 commit signing, SUP-014 SBOM,
+  SUP-015 attestation): beta proves the material exists, production proves
+  the chain verifies. Aligned with SLSA v1.2.
+  Verify, never mint (ADR-0011): USA checks signatures, it never signs.
+  Command checks are UNKNOWN without --allow-commands — that is the honest
+  assist posture — and every command fails closed on a missing binary, key,
+  or bundle (FAIL or UNKNOWN with a loud message, never PASS).
+version: '1.0'
+
+rules:
+  - id: SUP-018
+    title: Release blob signatures verify with cosign (chain verification)
+    section: S3
+    section_title: Supply Chain & Build Provenance
+    severity: HIGH
+    class: supply-chain
+    applies_when: { fact: 'maturity:production' }
+    check:
+      kind: command
+      run: >-
+        command -v cosign >/dev/null 2>&1 || { echo "FAIL-CLOSED SUP-018: cosign binary not found in PATH, so release blob signatures cannot be verified. Install sigstore/cosign and re-run with --allow-commands."; exit 1; };
+        key="";
+        for k in cosign.pub .cosign/cosign.pub keys/cosign.pub; do if [ -f "$k" ]; then key="$k"; break; fi; done;
+        [ -n "$key" ] || { echo "FAIL-CLOSED SUP-018: no cosign public key committed (looked for cosign.pub, .cosign/cosign.pub, keys/cosign.pub), so there is nothing trustworthy to verify against."; exit 1; };
+        bundles=$(find . \( -path "*/node_modules*" -o -path "./.git*" \) -prune -o \( -name "*.sigstore.json" -o -name "*.bundle" \) -print 2>/dev/null);
+        [ -n "$bundles" ] || { echo "FAIL-CLOSED SUP-018: no Sigstore bundles (*.sigstore.json, *.bundle) committed, so no release signature chain exists to verify."; exit 1; };
+        echo "$bundles" | while IFS= read -r bundle; do
+        [ -n "$bundle" ] || continue;
+        case "$bundle" in
+        *.sigstore.json) blob="${bundle%.sigstore.json}";;
+        *.bundle) blob="${bundle%.bundle}";;
+        *) blob="$bundle";;
+        esac;
+        [ -f "$blob" ] || { echo "FAIL SUP-018: bundle $bundle has no matching artifact blob (expected $blob). The signature chain is incomplete."; exit 1; };
+        cosign verify-blob --key "$key" --bundle "$bundle" "$blob" >/dev/null 2>&1 || { echo "FAIL SUP-018: cosign verify-blob failed for artifact $blob (bundle $bundle, key $key)."; exit 1; };
+        done || exit 1;
+        echo "SUP-018: cosign verify-blob succeeded for every committed bundle against $key.";
+      expect_exit: 0
+    evidence: 'cosign verify-blob success output for every committed bundle, or the fail-closed reason above.'
+    why: 'A signature nobody verifies is decoration. At production, every release blob must verify against a committed key and bundle — otherwise anyone with publish access ships anything.'
+    remediation: 'Commit cosign.pub and a Sigstore bundle per release blob, then run with --allow-commands so `cosign verify-blob --key <key> --bundle <bundle> <blob>` succeeds for each pair.'
+    references: ['SLSA-v1.2', 'SLSA-Build-L2', 'OpenSSF-Scorecard:Signed-Releases']
+
+  - id: SUP-019
+    title: SLSA attestation bundles verify with cosign (chain verification)
+    section: S3
+    section_title: Supply Chain & Build Provenance
+    severity: MEDIUM
+    class: supply-chain
+    applies_when: { fact: 'maturity:production' }
+    check:
+      kind: command
+      run: >-
+        command -v cosign >/dev/null 2>&1 || { echo "FAIL-CLOSED SUP-019: cosign binary not found in PATH, so SLSA attestation bundles cannot be verified. Install sigstore/cosign and re-run with --allow-commands."; exit 1; };
+        key="";
+        for k in cosign.pub .cosign/cosign.pub keys/cosign.pub; do if [ -f "$k" ]; then key="$k"; break; fi; done;
+        [ -n "$key" ] || { echo "FAIL-CLOSED SUP-019: no cosign public key committed (looked for cosign.pub, .cosign/cosign.pub, keys/cosign.pub), so there is nothing trustworthy to verify against."; exit 1; };
+        atts=$(find . \( -path "*/node_modules*" -o -path "./.git*" \) -prune -o \( -name "*.intoto.jsonl" -o -name "*.intoto.json" -o -name "*provenance*.json" \) ! -name "*.sigstore.json" ! -name "*.bundle" -print 2>/dev/null);
+        [ -n "$atts" ] || { echo "FAIL-CLOSED SUP-019: no SLSA provenance or in-toto attestation files (*.intoto.jsonl, *.intoto.json, *provenance*.json) committed, so no attestation chain exists to verify."; exit 1; };
+        echo "$atts" | while IFS= read -r att; do
+        [ -n "$att" ] || continue;
+        bundle="";
+        for cand in "$att.sigstore.json" "$att.bundle"; do if [ -f "$cand" ]; then bundle="$cand"; break; fi; done;
+        [ -n "$bundle" ] || { echo "FAIL SUP-019: attestation $att has no Sigstore bundle ($att.sigstore.json or $att.bundle missing). The attestation chain is incomplete."; exit 1; };
+        cosign verify-blob --key "$key" --bundle "$bundle" "$att" >/dev/null 2>&1 || { echo "FAIL SUP-019: cosign verify-blob failed for attestation $att (bundle $bundle, key $key)."; exit 1; };
+        done || exit 1;
+        echo "SUP-019: cosign verify-blob succeeded for every committed attestation against $key.";
+      expect_exit: 0
+    evidence: 'cosign verify-blob success output for every committed attestation, or the fail-closed reason above.'
+    why: 'Provenance that does not verify answers nothing when an artifact is compromised. At production, each committed attestation must carry a bundle that verifies — otherwise "built by us, from this source" is a claim, not evidence.'
+    remediation: 'Commit SLSA/in-toto attestations with a Sigstore bundle per file (<attestation>.sigstore.json), then run with --allow-commands so each pair verifies.'
+    references: ['SLSA-v1.2', 'SLSA-Build-L2', 'OpenSSF-Scorecard:Signed-Releases']
+
+  - id: SUP-020
+    title: Every release artifact ships a Sigstore bundle (chain completeness)
+    section: S3
+    section_title: Supply Chain & Build Provenance
+    severity: MEDIUM
+    class: supply-chain
+    applies_when: { fact: 'maturity:production' }
+    check:
+      kind: command
+      run: >-
+        command -v cosign >/dev/null 2>&1 || { echo "FAIL-CLOSED SUP-020: cosign binary not found in PATH, so the release signature chain cannot be checked. Install sigstore/cosign and re-run with --allow-commands."; exit 1; };
+        n=0;
+        for dir in dist artifacts releases; do
+        [ -d "$dir" ] || continue;
+        for art in "$dir"/*; do
+        [ -f "$art" ] || continue;
+        case "$art" in
+        *.sigstore.json|*.bundle|*.sig|*.pem|*.pub|SHA256SUMS*|*.sbom.*|*.spdx*|*.intoto.*) continue;;
+        esac;
+        if [ -f "$art.sigstore.json" ] || [ -f "$art.bundle" ]; then n=$((n + 1)); else echo "FAIL SUP-020: release artifact $art has no Sigstore bundle ($art.sigstore.json or $art.bundle missing). Every release artifact must ship a verifiable signature."; exit 1; fi;
+        done;
+        done;
+        [ "$n" -gt 0 ] || { echo "FAIL-CLOSED SUP-020: no release artifacts found under dist/, artifacts/ or releases/, so there is no signature chain to judge. Publish artifacts with Sigstore bundles."; exit 1; };
+        echo "SUP-020: every release artifact under dist/, artifacts/ or releases/ has a Sigstore bundle.";
+      expect_exit: 0
+    evidence: 'The per-artifact bundle listing above, or the fail-closed reason.'
+    why: 'One unverified artifact is the one the attacker picks. SUP-018 proves the signatures that exist; this rule proves none are missing — coverage of the chain, not just its links.'
+    remediation: 'Add a Sigstore bundle (<artifact>.sigstore.json) beside every file published from dist/, artifacts/ or releases/, then run with --allow-commands.'
+    references: ['SLSA-Build-L2', 'SLSA-v1.2', 'OpenSSF-Scorecard:Signed-Releases']

package/rules/index.yaml

@@ -13,6 +13,8 @@ packs:
   - core/repo.yaml
   - core/security.yaml
   - core/supply-chain.yaml
+  - core/provenance-cosign.yaml
+  - core/provenance-attestation.yaml
   - core/architecture.yaml
   - core/code-quality.yaml
   - core/testing.yaml

package/rules/profiles/maturity.yaml

@@ -129,7 +129,7 @@ profiles:
     focus:
       - Inventory EOL dependencies and pin a replacement date for each
       - Confirm backups restore, and that someone still knows how
-      - Keep the lights on: monitoring, alerting, and an owner per service
+      - 'Keep the lights on: monitoring, alerting, and an owner per service'
       - Document the system well enough to hand over or retire
     defer:
       - Rewrites without a strangler plan, framework migrations for their own sake

package/templates/AGENTS.audit.md

@@ -0,0 +1,135 @@
+# AGENTS.md — auditing this repository with USA
+
+> Paste this into any repository you want an agent to audit with USA.
+> Generated by `usa init`, or copy from
+> [`templates/AGENTS.audit.md`](https://github.com/Er-Sajan-PLG/universal-software-auditor/blob/master/templates/AGENTS.audit.md).
+
+---
+
+## What this repository is
+
+<!-- Fill this in. One paragraph. An agent that knows what the project is
+     audits it far better than one that has to guess. -->
+
+TODO: describe the project in two sentences.
+
+## Commands
+
+```bash
+# TODO: replace with this project's real commands
+npm install
+npm run lint
+npm test
+npm run build
+```
+
+## Layout
+
+<!-- Where things live. Delete what does not apply. -->
+
+```
+src/        application code
+tests/      test suite
+docs/       documentation
+scripts/    one-off utilities
+```
+
+## Conventions
+
+- TODO: naming, module boundaries, error-handling style, what belongs where.
+
+## Do not
+
+<!-- Explicit denylists beat implicit trust. Agents follow these literally. -->
+
+- Do not force-push or rewrite published history.
+- Do not read, print, or commit `.env*` files, credentials, or tokens.
+- Do not run destructive commands (`rm -rf`, `git clean -fdx`, `DROP TABLE`) without
+  explicit approval.
+- Do not disable tests, linters, or type checks to make something pass.
+- Do not commit secrets, even in tests or fixtures.
+
+---
+
+# Auditing with USA
+
+USA is a two-part framework. **The tool settles what is mechanically checkable; you
+settle the rest.** Do not re-do the tool's work.
+
+## Step 1 — Detect
+
+```bash
+usa detect .
+```
+
+Confirm the facts against what you see. If detection is wrong, say so; the operator
+can assert facts with `--fact has:database` or in `.usa.yaml`.
+
+## Step 2 — Deterministic pass
+
+```bash
+usa audit . --out AUDIT.md --depth standard
+```
+
+This produces findings with locations and a score. **Treat these as settled.** Do not
+re-grep for a rule the tool already resolved to ✅ or 🚫.
+
+## Step 3 — Work the Judgement Queue
+
+The report's _Judgement Queue_ lists every check that cannot be settled by reading a
+file. Each row states what to look for and what evidence to record.
+
+For each item:
+
+1. Find the relevant code.
+2. Decide: `PASS` · `WRONG` · `MISSING` · `UNKNOWN`.
+3. Record `file:line` **and** one sentence of reasoning.
+4. If you cannot determine it, answer `UNKNOWN` and say what you would need.
+
+## Step 4 — Report
+
+Follow the report output template in `USA.md`:
+
+1. CRITICAL and security-HIGH findings first — with location and fix
+2. Section-by-section findings
+3. Judgement queue with your recorded evidence
+4. Roadmap: sprint 0 / sprint 1 / sprint 2 / backlog
+
+## The ten rules
+
+| #   | Rule                                                                |
+| --- | ------------------------------------------------------------------- |
+| 1   | Skip non-applicable sections silently. Do not write "N/A" 40 times. |
+| 2   | Partially applicable ⇒ audit the applicable parts only.             |
+| 3   | CRITICAL findings always go first, above every summary.             |
+| 4   | **Never mark ✅ without evidence.** `file:line` or command output.  |
+| 5   | Every finding: location + severity + why + fix.                     |
+| 6   | Score sections 0–10 from the share of applicable checks that pass.  |
+| 7   | Never assume. A file you did not find is 🚫 MISSING.                |
+| 8   | Audit what is absent as well as what is present.                    |
+| 9   | ⚠️ WRONG is worse than 🚫 MISSING. Surface it.                      |
+| 10  | Priority: Security > Correctness > Maintainability > Style.         |
+
+## Status vocabulary
+
+|     | Status       | Meaning                                  |
+| --- | ------------ | ---------------------------------------- |
+| ✅  | GOOD         | Verified present and correct             |
+| 🧪  | EXPERIMENTAL | Present, unvalidated                     |
+| 💀  | DEPRECATED   | Present, EOL                             |
+| ⚠️  | WRONG        | Present but implemented incorrectly      |
+| 🚫  | MISSING      | Required and absent                      |
+| ❓  | NEEDS REVIEW | Cannot be determined from the code alone |
+
+Severity: 🔴 CRITICAL · 🟠 HIGH · 🟡 MEDIUM · 🟢 LOW · 🔵 FUTURE
+
+## Two things agents get wrong
+
+**Guessing instead of saying UNKNOWN.** An audit that invents a passing result is worse
+than one that admits uncertainty. `UNKNOWN` lowers the report's _confidence_, which is
+the honest signal. Guessing corrupts the _score_, which is not.
+
+**Re-escalating dampened findings.** If a finding says
+_"Downgraded HIGH → MEDIUM by the MVP profile"_, that is the framework doing its job —
+the project is an MVP and the calendar is a real constraint. Leave it alone. The one
+exception is 🔴 CRITICAL, which is **never** dampened at any stage.

package/templates/AUDIT_REPORT.md

@@ -0,0 +1,155 @@
+# Audit report template
+
+> USA's CLI emits this structure automatically (`usa audit .`).
+> Use this file when you are writing a report by hand — or when an agent is
+> producing one without the tool. Matching the structure is what makes reports
+> diffable and comparable across time and teams.
+
+---
+
+```
+══════════════════════════════════════════════════════════
+              UNIVERSAL SOFTWARE AUDIT REPORT
+══════════════════════════════════════════════════════════
+Project      : [name]
+Repository   : [url]
+Commit       : [sha] ([ref])
+Audited by   : USA [version] + [agent / human]
+Date         : [ISO-8601]
+Detected type: [auto-detected]
+Platform     : [auto-detected]
+Stack        : [auto-detected]
+Maturity     : [Prototype / MVP / Beta / Production / Legacy]
+Depth        : [quick | standard | deep]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                    EXECUTIVE SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall Health Score : [X/100]
+Expected band for [maturity]: [lo]–[hi]  → [verdict]
+
+Dimension                            Score      Confidence
+S1  Repository & Structure            X/10      N%
+S2  Security                          X/10      N%
+S3  Supply Chain & Provenance         X/10      N%
+S4  Architecture & Design             X/10      N%
+S5  Code Quality                      X/10      N%
+S6  Data & Database                   X/10      N%
+S7  Testing & Quality Assurance       X/10      N%
+S8  CI/CD, Infrastructure & Obs.      X/10      N%
+S9  Release & Change Management       X/10      N%
+S10 Dependencies & Third-Party        X/10      N%
+S11 Performance & Resilience          X/10      N%
+S12 Documentation & Knowledge         X/10      N%
+S13 Accessibility, i18n & Compliance  X/10      N%
+S14 AI / LLM-Era Risks                X/10      N%
+S15 Platform-Specific                 X/10      N%
+S16 Future Readiness                  X/10      N%
+
+Automation coverage: N%   (the rest is in the judgement queue)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                    FINDINGS SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ GOOD       : N     🔴 CRITICAL : N
+⚠️ WRONG      : N     🟠 HIGH     : N
+🚫 MISSING    : N     🟡 MEDIUM   : N
+💀 DEPRECATED : N     🟢 LOW      : N
+🧪 EXPERIMENTAL: N    🔵 FUTURE   : N
+❓ TO REVIEW  : N
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                 IMMEDIATE ACTION REQUIRED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1. 🔴 [Finding] → [file:line] → [why] → [fix]
+2. 🟠 [Finding] → [file:line] → [why] → [fix]
+   (No CRITICAL/HIGH? Say so, plainly.)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                SECTION-BY-SECTION FINDINGS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[S1] Repository & Structure   → X/10
+  🔴 [finding] → [location] → [fix]
+  🚫 [finding] → [location] → [fix]
+  ✅ [N checks passing]
+
+[S2] Security                 → X/10
+  ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                     JUDGEMENT QUEUE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Rule | Section | Severity | What to look for | Evidence to record |
+|------|---------|----------|------------------|--------------------|
+| SEC-015 | S2 | 🟠 HIGH | Authorization per resource | file:line of the ownership check |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                        ACCEPTED RISK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Rule | Severity | Reason | Until |
+|------|----------|--------|-------|
+| PERF-005 | 🟡 MEDIUM | Known N+1 in the admin panel; 40 rows max. | 2026-12-31 |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                    RECOMMENDED ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SPRINT 0 (now)       : CRITICAL + security HIGH
+SPRINT 1 (1–2 weeks) : remaining HIGH
+SPRINT 2 (1 month)   : MEDIUM
+BACKLOG              : LOW + FUTURE
+DEFERRED (this stage): what the maturity profile says to ignore
+
+WHAT MATTERS AT [STAGE]:
+  - [focus item from the maturity profile]
+  - [focus item]
+
+══════════════════════════════════════════════════════════
+```
+
+---
+
+## Rules for filling this in
+
+1. **Every finding carries location + severity + why + fix.** A finding without a
+   location is an opinion.
+2. **CRITICAL first, always.** Above the summary, above the score.
+3. **No ✅ without evidence.** `file:line`, a command output, or a doc link.
+4. **Skip non-applicable sections without comment.** Do not write "N/A: not a web app".
+5. **Surface ⚠️ WRONG above 🚫 MISSING** within a severity band. Wrong is worse than
+   absent because it looks finished.
+6. **Record UNKNOWNs in the judgement queue**, not as silent passes. They are what
+   confidence measures.
+7. **The roadmap is the deliverable.** A score nobody acts on is a number; a sprint
+   list is a plan.
+
+## Rendering notes
+
+- Use the emoji tags consistently — they are what makes a long report skimmable.
+- Keep the section order fixed (S1 → S16) so two reports can be compared line by line.
+- If you are an agent writing this by hand, end the file with the machine-readable
+  trailer so `usa diff` works on it:
+
+````markdown
+<!-- USA:TRAILER:BEGIN -->
+
+```yaml
+schema: usa-report-v1
+generated_at: 2026-09-08T00:00:00.000Z
+usa_version: 1.0.0
+overall: 71.4
+sections:
+  S1: { score: 8.4, open: 2, review: 2 }
+  S2: { score: 6.2, open: 3, review: 1 }
+severity_totals:
+  CRITICAL: 0
+  HIGH: 3
+  MEDIUM: 4
+  LOW: 6
+  FUTURE: 2
+rules:
+  SEC-001: { status: PASS, severity: CRITICAL, section: S2 }
+  SEC-015: { status: UNKNOWN, severity: HIGH, section: S2 }
+```
+
+<!-- USA:TRAILER:END -->
+````