🧠 USA

Universal Software Auditor

An open-source, self-adapting audit framework for any project, any stack, any stage.

Most audit checklists are static. They ask a React prototype to prove multi-region failover, and they ask a bank to prove it has a README. The result is noise that gets skimmed and ignored.

USA adapts. It detects what your project actually is, activates only the sections that apply, grades you against a bar appropriate to your stage, and tells you what to fix first — with a reproducible score you can diff against last quarter's.

It is two things, and you should use both:

| | What it does | Why you need it | | ------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------- | | rules/ + usa CLI | Deterministic checks: everything answerable by reading a file | Reproducible, fast, CI-gateable, diffable | | USA.md + judgement queue | The parts only reasoning can settle | Coupling, authorisation, threat modelling, product context |

⚡ Quick start

# Audit any project — no install, no config, no network
npx @xenos1996/usa audit .

# See what it detected before you trust the report
npx @xenos1996/usa detect .

# Deep audit, graded against the production bar
npx @xenos1996/usa audit ~/code/api --depth deep --profile production

# Fail the build on HIGH or worse
npx @xenos1996/usa audit . --fail-on high

That writes AUDIT.md — a single self-contained Markdown file you can commit, paste into a PR, or email to a client.

## 📊 Executive Summary

### Overall Health Score: **45.2/100**

`███████████░░░░░░░░░░░░░`

Verified automatically: **65.8%** of applicable checks. 27 checks need a human — see the judgement queue.

Expected band for **Prototype / Spike**: 30–65 — **within the expected band** 👍

| Dimension                            | Score  | Confidence |
| ------------------------------------ | ------ | ---------- |
| S1 · Repository & Project Structure  | 7.2/10 | 83.3%      |
| S2 · Security                        | 4.9/10 | 92.9%      |
| S3 · Supply Chain & Build Provenance | 0/10   | 100%       |
| S5 · Code Quality                    | 3.5/10 | 87.5%      |
| S7 · Testing & Quality Assurance     | 0/10 † | 33.3%      |

## 🚨 Immediate Action Required

1. 🔴 **No hardcoded credentials in source** · `SEC-001`
   - **Where:** `src/config.js:3`, `src/config.js:4`
   - **Why:** 2 occurrence(s): `api_key: 'example_key_not_real_12345',` at src/config.js:3 (+1 more).
   - **Fix:** Move to environment variables backed by a secret manager; rotate anything that was ever committed.
2. 🔴 **SQL is not built by string concatenation** · `SEC-005`
   - **Where:** `src/db.js:15`
   - **Why:** 1 instance(s): `'SELECT * FROM orders WHERE id = ' + orderId,` at src/db.js:15.
   - **Fix:** Use parameterised queries ($1, ?, :name) or the ORM query API.

That excerpt is real output, generated by running USA against examples/demo-app — a small, deliberately vulnerable Express service kept in this repo so you can reproduce the findings yourself:

usa audit examples/demo-app --out /tmp/demo.md

See the full report: examples/sample-report.md (raw checklist, machine-verified). For the customer-facing story over the same evidence, see examples/sample-report-narrative.md.

🔍 How it adapts

1 · Detect. ~230 declarative signals in rules/detectors.yaml produce facts about your project — language, framework, package manager, platform, database, auth, CI, AI stack, and more.

$ usa detect .
maturity: beta
lang: typescript          fw: next, react, tailwind
pm: pnpm                  db: postgres, redis
orm: prisma               auth: jwt, oauth
ci: github-actions        has: tests, containers, monitoring

2 · Select. Every rule declares applies_when. A Solidity pack skips a Next.js blog; a mobile pack skips a CLI. Packs can also assert facts, so enabling a monorepo pack pulls in boundary checks automatically.

3 · Dampen. The detected maturity stage adjusts severity. A prototype is not graded like a bank — but 🔴 CRITICAL is never dampened, at any stage.

4 · Score. Weighted, deterministic, reproducible. Sections that could not be verified report "not verified" rather than quietly scoring 10.

5 · Diff. Every report embeds a machine-readable trailer:

usa diff reports/2026-06.md reports/2026-09.md
# ✅ Fixed (7) · 🔺 Regressed (1) · 🆕 Newly applicable (3) · Net +11.2 points

📊 The severity model

Two axes kept separate — this is what makes the score reproducible instead of vibes.

Severity (how bad, if violated): 🔴 CRITICAL · 🟠 HIGH · 🟡 MEDIUM · 🟢 LOW · 🔵 FUTURE

Status (what was observed):

| | Status | Means | Score credit | | --- | -------------- | --------------------------------------- | ------------ | | ✅ | GOOD | Verified present and correct | 1.00 | | 🧪 | EXPERIMENTAL | Present, unvalidated | 0.50 | | 💀 | DEPRECATED | Present, EOL | 0.40 | | ⚠️ | WRONG | Present but incorrectly implemented | 0.15 | | 🚫 | MISSING | Required and absent | 0.00 | | ❓ | NEEDS REVIEW | Judgement required | excluded | | ➖ | SKIPPED | Not applicable | excluded |

⚠️ WRONG scores above MISSING on purpose. Something exists, so there is partial credit — but a wrong implementation is more dangerous than nothing, because it looks finished. Most checklists only have a box for "is it there".

🌱 Maturity profiles — the "any stage" part

| Stage | Detected when | Security | Docs / Style | Expected | | ------------- | ------------------------------------ | -------- | ------------ | -------- | | 🌱 Prototype | no tests, no CI, no history | −1 step | −2 steps | 30–65 | | 🚀 MVP | some process, real users | −0 | −2 steps | 45–75 | | 🧪 Beta | CI + tests + changelog | −0 | −1 step | 60–85 | | 🏭 Production | score ≥7 and release tags | −0 | −0 | 75–95 | | 🏚️ Legacy | ~18 months idle, or stale without CI | −0 | −1 step | 40–70 |

Hard rule: 🔴 CRITICAL is never dampened. A leaked credential in a weekend prototype is still a leaked credential. Everything else is negotiable with the calendar.

Override it: usa audit . --profile production — the "what would it take to ship this?" view.

📦 What it checks

16 sections, S1–S16, in USA.md — the human/agent-facing document.

310+ rules in rules/ — the machine-facing ones:

rules/
├── index.yaml              pack registry
├── detectors.yaml          ~230 detection signals → facts
├── profiles/maturity.yaml  the five lifecycle profiles
├── core/                   15 universal packs
│   ├── repo.yaml           ├── security.yaml      ├── supply-chain.yaml
│   ├── architecture.yaml   ├── code-quality.yaml  ├── testing.yaml
│   ├── cicd.yaml           ├── release.yaml       ├── dependencies.yaml
│   ├── documentation.yaml  └── future-readiness.yaml
└── stacks/                 17 conditional packs
    ├── node-typescript     ├── python      ├── go        ├── rust
    ├── jvm                 ├── web-frontend├── mobile    ├── containers
    ├── iac                 ├── solidity    ├── ml-ai      ├── cli
    ├── data                ├── api-backend ├── compliance ├── ai-era
    └── swift

What USA adds beyond a conventional audit checklist

| Addition | Why | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | S3 Supply Chain & Provenance as its own section | You can write flawless code and still ship someone else's backdoor. SLSA v1.2, NIST SSDF, OpenSSF Scorecard. | | S9 Release & Change Management | The gap between "we deploy" and "we ship": versioning, migration ordering, flags, runbooks. | | S14 AI / LLM-Era Risks | Mapped to OWASP LLM Top 10 (2026) and OWASP Agentic AI Top 10 (ASI, 2026). Prompt injection, excessive agency, unbounded consumption, RAG tenant leakage. | | ⚠️ WRONG as a distinct status | Present-but-incorrect is worse than absent. Rule 9 of the agent behaviour rules. | | Maturity-aware severity dampening | Stage-appropriate grading, with a hard floor on CRITICAL. | | Approved-risk suppressions | Decisions you made deliberately stay visible but stop costing points. Each needs a reason and an optional expiry. | | Confidence, not just score | A 90/100 at 40% confidence means a fifth of the surface was never checked. | | usa diff | An audit you cannot compare to the last one is just a number. |

See docs/standards-mapping.md for the full comparison against OWASP ASVS 5.0, NIST SSDF, SLSA, OpenSSF Scorecard, CII Best Practices, ISO/IEC 5055, WCAG 2.2, and the EU CRA.

🤖 Use it with an AI agent

USA is designed to be driven by an agent: the tool settles everything mechanical, and the agent works the judgement queue — the checks that cannot be settled by grep, each with the evidence it needs recorded.

usa audit .                     # deterministic pass
# → then: "Read USA.md and AUDIT.md, and work the Judgement Queue.
#          For each item, find the evidence and record file:line."

Ready-made packs:

• skills/usa-audit/SKILL.md — Agent Skills format (Claude Code, Cursor, Codex, Copilot, Gemini CLI; drop into your skills dir)
• templates/AGENTS.audit.md — paste into any repo as AGENTS.md

🔧 Configuration

usa init scaffolds .usa.yaml (all entries commented — uncomment what you need):

version: 1
# maturity: production        # override auto-detection
# include: [stacks/solidity]  # force a pack on
# exclude: [stacks/mobile]    # force a pack off
rules:
  # DOC-003:
  #   severity: LOW
  #   reason: "Docs live in Notion, not the repo (decision: ADR-014)"
suppressions:
  # - rule: PERF-005
  #   reason: "Known N+1 in the admin panel; 40 rows max. Revisit Q4."
  #   until: "2026-12-31"
ignore: []
facts: [] # assert facts detection missed, e.g. "has:database"

Full reference: docs/configuration.md.

🚦 CI

Add to any workflow (action.yml is a composite action if you prefer):

- name: USA audit
  run: npx @xenos1996/usa audit . --fail-on high

- name: Publish report
  if: always()
  run: cat AUDIT.md >> "$GITHUB_STEP_SUMMARY"

usa init writes a complete workflow for you, and this repo audits itself on every PR (.github/workflows/self-audit.yml).

| Exit code | Meaning | | --------- | --------------------------------------------------- | | 0 | No findings at or above --fail-on (default: none) | | 1 | Gate tripped | | 2 | Usage or configuration error |

📚 Documentation

| Doc | What's in it | | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | USA.md | The template itself — every section, every check, the agent behaviour rules | | docs/getting-started.md | Install, first audit, reading the report | | docs/concepts.md | Severity × status, scoring maths, confidence | | docs/rule-packs.md | Author your own packs — every check kind, with examples | | docs/detectors.md | The fact catalogue and how to add signals | | docs/maturity-profiles.md | Lifecycle stages and dampening rules | | docs/agent-integration.md | Driving USA from Claude/Cursor/Codex/Copilot | | docs/ci-integration.md | GitHub Actions, GitLab CI, quality gates, SARIF/JSON output | | docs/standards-mapping.md | USA ↔ ASVS 5.0, SSDF, SLSA, Scorecard, ISO 5055, WCAG, CRA | | docs/configuration.md | .usa.yaml reference | | docs/EVOLUTION.md | The deterministic self-extension loop | | docs/reference/api.md | Programmatic API: runAudit, renderers, scoring, diffing, evolution |

The full index — including architecture, ADRs, and the CLI reference — is docs/README.md.

🛠️ Contributing

Rule packs are the easiest high-value contribution — one YAML file, no TypeScript.

git clone https://github.com/Er-Sajan-PLG/universal-software-auditor
cd universal-software-auditor
pnpm install && pnpm test
pnpm run usa -- audit .       # run the CLI from source

Agents and humans doing repo work: read AGENTS.md first — it holds the operating manual (the loop, the gates, the conventions).

See CONTRIBUTING.md. Good first contributions:

• A stack pack for a language or framework we do not cover yet
• A detector for a technology USA fails to notice
• A false positive you hit — rules should be precise, not noisy

⚠️ What USA is not

• Not a penetration test. No dynamic analysis, no fuzzing. It finds open doors; it does not walk through them.
• Not a replacement for CodeQL / Semgrep / Snyk / Trivy. It checks whether those are configured and tells you to run them.
• Not a compliance certification. It maps to the standards and tells you what evidence you would need. An auditor still certifies.
• Not a code review. It does not understand your product.

📄 Licence

MIT — see LICENSE. Use it commercially, fork it, ship it, send rule packs back.