@xenos1996/usat 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 USAT contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+<div align="center">
+
+# 🧠 USAT
+
+### Universal Software Audit Template
+
+**An open-source, self-adapting audit framework for any project, any stack, any stage.**
+
+[![CI](https://github.com/Er-Sajan-PLG/software-auditing-template/actions/workflows/ci.yml/badge.svg)](https://github.com/Er-Sajan-PLG/software-auditing-template/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@xenos1996/usat)](https://www.npmjs.com/package/@xenos1996/usat)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Rules](https://img.shields.io/badge/rules-200%2B-blue)](rules/)
+
+</div>
+
+---
+
+**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.
+
+**USAT 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/` + `usat` CLI**       | Deterministic checks: everything answerable by reading a file | Reproducible, fast, CI-gateable, diffable                  |
+| **`USAT.md` + judgement queue** | The parts only reasoning can settle                           | Coupling, authorisation, threat modelling, product context |
+
+---
+
+## ⚡ Quick start
+
+```bash
+# Audit any project — no install, no config, no network
+npx @xenos1996/usat audit .
+
+# See what it detected before you trust the report
+npx @xenos1996/usat detect .
+
+# Deep audit, graded against the production bar
+npx @xenos1996/usat audit ~/code/api --depth deep --profile production
+
+# Fail the build on HIGH or worse
+npx @xenos1996/usat 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.
+
+<details>
+<summary><b>What the report looks like</b> (abridged)</summary>
+
+```markdown
+## 📊 Executive Summary
+
+### Overall Health Score: 71.4/100
+
+`█████████████████░░░░░░░`
+
+Expected band for Beta / Growing: 60–85 — within the expected band 👍
+
+| Dimension                            | Score  | Confidence |
+| ------------------------------------ | ------ | ---------- |
+| S1 · Repository & Project Structure  | 8.4/10 | 72.7%      |
+| S2 · Security                        | 6.2/10 | 100%       |
+| S3 · Supply Chain & Build Provenance | 5.1/10 | 100%       |
+| S7 · Testing & Quality Assurance     | 7.5/10 | 80%        |
+
+## 🚨 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…
+
+## 🧠 Judgement Queue (agent / human review)
+
+| Rule                                            | Section | Severity | What to look for | Evidence to record               |
+| ----------------------------------------------- | ------- | -------- | ---------------- | -------------------------------- |
+| `SEC-015` Authorization is enforced per request | S2      | 🟠 HIGH  | …                | file:line of the ownership check |
+```
+
+That excerpt is real output, generated by running USAT against
+[`examples/demo-app`](examples/demo-app) — a small, deliberately vulnerable
+Express service kept in this repo so you can reproduce the findings yourself:
+
+```bash
+usat audit examples/demo-app --out /tmp/demo.md
+```
+
+See the full report: [`examples/sample-report.md`](examples/sample-report.md).
+
+</details>
+
+---
+
+## 🔍 How it adapts
+
+**1 · Detect.** ~200 declarative signals in [`rules/detectors.yaml`](rules/detectors.yaml)
+produce facts about your project — language, framework, package manager, platform,
+database, auth, CI, AI stack, and more.
+
+```bash
+$ usat 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:
+
+```bash
+usat 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: `usat audit . --profile production` — the "what would it take to ship this?" view.
+
+---
+
+## 📦 What it checks
+
+**16 sections**, S1–S16, in [`USAT.md`](USAT.md) — the human/agent-facing document.
+
+**200+ rules** in [`rules/`](rules) — the machine-facing ones:
+
+```
+rules/
+├── index.yaml              pack registry
+├── detectors.yaml          ~200 detection signals → facts
+├── sections.yaml           section weights (override the defaults)
+├── profiles/maturity.yaml  the five lifecycle profiles
+├── core/                   11 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/                 16 conditional packs
+    ├── node-typescript     ├── python      ├── go        ├── rust
+    ├── jvm                 ├── web-frontend├── mobile    ├── containers
+    ├── iac                 ├── solidity    ├── ml-ai      ├── cli
+    ├── data                ├── api-backend ├── compliance └── ai-era
+```
+
+### What USAT 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.                                                                                |
+| **`usat diff`**                                     | An audit you cannot compare to the last one is just a number.                                                                                             |
+
+See [`docs/standards-mapping.md`](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
+
+USAT 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.
+
+```bash
+usat audit .                     # deterministic pass
+# → then: "Read USAT.md and AUDIT.md, and work the Judgement Queue.
+#          For each item, find the evidence and record file:line."
+```
+
+Ready-made packs:
+
+- [`skills/usat-audit/SKILL.md`](skills/usat-audit/SKILL.md) — Agent Skills format
+  (Claude Code, Cursor, Codex, Copilot, Gemini CLI; drop into your skills dir)
+- [`templates/AGENTS.audit.md`](templates/AGENTS.audit.md) — paste into any repo as `AGENTS.md`
+
+---
+
+## 🔧 Configuration
+
+`usat init` scaffolds `.usat.yaml`:
+
+```yaml
+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 (decision: ADR-014)'
+suppressions:
+  - rule: PERF-005
+    reason: 'Known N+1 in the admin panel; 40 rows max.'
+    until: '2026-12-31'
+ignore: [] # extra globs to exclude from indexing
+facts: [] # assert facts detection missed, e.g. "has:database"
+```
+
+Full reference: [`docs/configuration.md`](docs/configuration.md).
+
+---
+
+## 🚦 CI
+
+Add to any workflow ([`action.yml`](action.yml) is a composite action if you prefer):
+
+```yaml
+- name: USAT audit
+  run: npx @xenos1996/usat audit . --fail-on high
+
+- name: Publish report
+  if: always()
+  run: cat AUDIT.md >> "$GITHUB_STEP_SUMMARY"
+```
+
+`usat init` writes a complete workflow for you, and this repo audits itself on every PR
+([`.github/workflows/self-audit.yml`](.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                                                                    |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [`USAT.md`](USAT.md)                                     | **The template itself** — every section, every check, the agent behaviour rules |
+| [`docs/getting-started.md`](docs/getting-started.md)     | Install, first audit, reading the report                                        |
+| [`docs/concepts.md`](docs/concepts.md)                   | Severity × status, scoring maths, confidence                                    |
+| [`docs/rule-packs.md`](docs/rule-packs.md)               | Author your own packs — every check kind, with examples                         |
+| [`docs/detectors.md`](docs/detectors.md)                 | The fact catalogue and how to add signals                                       |
+| [`docs/maturity-profiles.md`](docs/maturity-profiles.md) | Lifecycle stages and dampening rules                                            |
+| [`docs/agent-integration.md`](docs/agent-integration.md) | Driving USAT from Claude/Cursor/Codex/Copilot                                   |
+| [`docs/ci-integration.md`](docs/ci-integration.md)       | GitHub Actions, GitLab CI, quality gates                                        |
+| [`docs/standards-mapping.md`](docs/standards-mapping.md) | USAT ↔ ASVS 5.0, SSDF, SLSA, Scorecard, ISO 5055, WCAG, CRA                     |
+| [`docs/configuration.md`](docs/configuration.md)         | `.usat.yaml` reference                                                          |
+
+---
+
+## 🛠️ Contributing
+
+Rule packs are the easiest high-value contribution — one YAML file, no TypeScript.
+
+```bash
+git clone https://github.com/Er-Sajan-PLG/software-auditing-template
+cd software-auditing-template
+npm install && npm test
+npm run usat -- audit .       # run the CLI from source
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Good first contributions:
+
+- **A stack pack** for a language or framework we do not cover yet
+- **A detector** for a technology USAT fails to notice
+- **A false positive** you hit — rules should be precise, not noisy
+
+---
+
+## ⚠️ What USAT 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`](LICENSE). Use it commercially, fork it, ship it, send rule packs back.