penthera 1.2.0 → 1.5.0

package/docs/METHODOLOGY.md

@@ -0,0 +1,321 @@
+# Methodology
+
+This document describes what Penthera tests, how it decides that something is a
+finding, how sure it is, and where its limits are. Each design choice points to
+the research or standard it rests on. Citation keys such as `[bau2010state]`
+refer to [references.md](references.md) and [references.bib](references.bib).
+
+Measured accuracy on the bundled benchmark is in
+[bench/RESULTS.md](../bench/RESULTS.md); the method behind those numbers is in
+[bench/README.md](../bench/README.md).
+
+## Contents
+
+- [Threat model](#threat-model)
+- [Black-box and white-box: what each can find](#black-box-and-white-box-what-each-can-find)
+- [Confidence model](#confidence-model)
+- [False-positive controls](#false-positive-controls)
+- [Non-destructive by default](#non-destructive-by-default)
+- [Offline and no telemetry](#offline-and-no-telemetry)
+- [How new attack techniques are adopted](#how-new-attack-techniques-are-adopted)
+- [Citations in reports](#citations-in-reports)
+- [Known limitations](#known-limitations)
+
+## Threat model
+
+Penthera is built for small teams shipping web apps and APIs, often with AI
+coding tools, who need a first line of evidence before a human review or a
+paid penetration test. The threat model follows the structure in Shostack
+[shostack2014threat]: what are we building, what can go wrong, what do we do
+about it, and did we do a good job.
+
+**Assets.** User data behind the API, credentials and API keys (including AI
+provider keys), the session and identity layer, and the integrity of the code
+and dependencies that get deployed.
+
+**Adversaries in scope.**
+
+1. A remote, unauthenticated attacker on the internet who can send arbitrary
+   HTTP requests to the deployed app. This is what the black-box scan models.
+2. An authenticated user trying to reach another user's data (broken object
+   level authorization, the top item in the OWASP API Security Top 10
+   [owasp2023api]). Penthera tests this when given credentials.
+3. Anyone who obtains a copy of the source: a leaked repository, a public fork,
+   a compromised CI log. Meli et al. found secrets leaked in over 100,000
+   public GitHub repositories, with thousands of new, unique secrets leaked
+   every day [meli2019bad]. This is what the
+   white-box secret scan models.
+4. A supply-chain attacker who publishes or compromises a dependency
+   [ladisa2023sok, ohm2020backstabber, zimmermann2019small], including
+   packages that code-generating models invent and attackers then register
+   [spracklen2025package].
+
+**Out of scope.** Physical access, insider threats with production access,
+denial of service, social engineering, and anything that needs exploitation
+beyond a single benign probe. Penthera does not try to replace a human tester;
+it tries to find the issues a scanner can find reliably and say clearly which
+ones it cannot judge.
+
+**Penthera itself is in the threat model.** A security tool runs with the
+user's credentials and network position, so a compromised scanner is a
+compromised machine. Thompson's point that you cannot trust code you did not
+build yourself [thompson1984reflections] applies to scanners and their rule
+feeds. This is why Penthera fetches no rules at run time
+([below](#how-new-attack-techniques-are-adopted)).
+
+STRIDE, the threat categories that Shostack's book builds on, originates at
+Microsoft [kohnfelder1999threats]. Penthera's probes map onto it roughly as:
+spoofing (auth, JWT, OAuth, email SPF/DMARC), tampering (injection, CORS),
+repudiation (not tested), information disclosure (exposed files, secrets,
+verbose errors), denial of service (not tested, only rate limiting is
+checked), and elevation of privilege (IDOR/BOLA, client-side-only auth).
+
+## Black-box and white-box: what each can find
+
+Penthera runs two kinds of analysis and reports them together.
+
+### Black-box (URL scan)
+
+The scanner sees only HTTP responses. Its tests are those of the OWASP Web
+Security Testing Guide [owaspwstg42]; each probe's WSTG IDs are listed in
+[owasp-wstg-coverage.md](owasp-wstg-coverage.md).
+
+What black-box testing finds well: properties that are visible in every
+response (missing security headers, TLS configuration, cookie flags, CORS
+policy), files and interfaces that should not be public, and injection flaws
+whose effect shows up in the response or its timing. Protocol checks follow
+the relevant specifications: HSTS [hodges2012rfc6797], JWT
+[jones2015rfc7519, sheffer2020rfc8725], and OAuth redirect and PKCE handling
+[lodderstedt2025rfc9700, sakimura2015rfc7636, fett2016comprehensive].
+
+What it misses, and why. Two classic evaluations of black-box scanners point
+the same way. Bau et al. tested eight commercial scanners against a custom
+vulnerable application and older versions of real ones. As a group the tools
+did reasonably well, but second-order flaws, stored XSS and stored SQL
+injection, were missed by many of them [bau2010state]. Doupé et al. tested
+eleven commercial and open-source scanners against WackoPicko, a realistic
+purpose-built app with sixteen planted flaws. Eight of the sixteen were missed
+by every scanner, including stored SQL injection, multi-step stored XSS,
+forceful browsing and a business logic flaw. They concluded that crawling
+matters as much as detection: a scanner cannot test a page it never reaches,
+and losing track of state (logins, multi-step forms) is a main reason it
+doesn't [doupe2010johnny].
+
+Penthera's design responds to each point:
+
+- **Crawl coverage.** Endpoint discovery uses a wordlist plus the app's own
+  OpenAPI document when one is exposed, and records exactly which probes ran.
+  The WSTG coverage table in every report lists tests as run or not run, so a
+  missing check is never presented as a pass.
+- **State and logic.** Penthera does not claim to find business logic flaws,
+  which no scanner in the Doupé et al. study found either.
+  IDOR/BOLA results are labelled `needs-human-review` because a scanner cannot
+  know whether user A is allowed to read object B.
+- **Stored and second-order flaws.** Not tested. They need a write followed by
+  a read elsewhere, which conflicts with the non-destructive default.
+
+### White-box (repository scan)
+
+The scanner reads source files. It finds hardcoded secrets, route handlers and
+their authentication boundaries, and risky code patterns.
+
+Secret detection uses provider-specific prefixes (for example `AKIA` for AWS,
+`sk-ant-` for Anthropic) plus a small number of assignment patterns such as
+`api_key = "..."` with a placeholder filter. Meli et al. took the same
+conservative route, restricting detection to private keys and API keys with
+distinctive formats [meli2019bad]. The cost is recall: a secret with no
+recognisable format is invisible to this approach. SecretBench, a labelled
+dataset of real secrets across many formats, is the natural yardstick for that
+gap [basak2023secretbench]. The benchmark here includes an unprefixed signing
+key that Penthera misses for this reason.
+
+What white-box scanning cannot see: runtime configuration (headers added by a
+CDN, a WAF in front of the app), secrets injected at deploy time, and anything
+in dependencies that is only known from a vulnerability database.
+
+### Combining them
+
+Running both against the same app catches cases neither sees alone: a route
+the repository marks as public that the black-box scan confirms is reachable,
+or a header the code sets that the edge strips. The report keeps the source of
+each finding (`source`, `method`) so a reader can tell which side produced it.
+
+## Confidence model
+
+Severity says how bad a finding would be if real. Confidence says how likely it
+is to be real. Penthera reports both, and never lets a heuristic look like a
+fact. The labels are defined in
+[lib/provenance.js](../lib/provenance.js):
+
+| Label | Meaning | Typical sources |
+|---|---|---|
+| `confirmed` | Deterministic evidence. The header is absent, the certificate expired, the key matches a provider format. | Header audit, TLS check, cookie audit, secret scan, OpenAPI exposure |
+| `likely` | A strong signal with a small false-positive chance. | Injection probes with a verified canary, auth and JWT probes, framework checks |
+| `potential` | A heuristic or one-shot signal that needs corroboration. | Fuzzer, adaptive probes |
+| `needs-human-review` | Exploitability cannot be judged from outside. | IDOR/BOLA, client-side-only auth |
+
+Every finding also carries `source`, `method` and `collected_at`, and these
+travel into SARIF so the label survives into GitHub code scanning.
+
+The benchmark reports precision per confidence label, which is the check that
+the labels mean what they say. On the current run all `likely` and
+`needs-human-review` findings were true positives, the one `potential` finding
+was a false positive, and the two `confirmed` false positives are cases where
+the evidence is real but the judgement is wrong (a health endpoint that is
+public by design, AWS's published example key). See
+[bench/RESULTS.md](../bench/RESULTS.md).
+
+## False-positive controls
+
+Black-box scanners lose trust through false positives faster than through
+misses. Specific controls in the probes:
+
+- **Randomized canaries.** The SSTI probe multiplies two random four-digit
+  numbers and looks for the seven- or eight-digit product, and only when the
+  raw payload and the literal expression are absent from the response
+  ([lib/injections.js](../lib/injections.js), `buildSstiProbes`). The common
+  fixed `7*7 = 49` canary fires on any page that happens to contain "49". XSS
+  probes use a per-probe random reflection marker (`makeCanary`).
+- **Context before payload.** The XSS probe first checks where its marker is
+  reflected (HTML body, attribute, script) and only sends payloads that would
+  execute in that context, then checks they came back unencoded. This is the
+  approach of context-aware tools such as Dalfox.
+- **Baseline comparison.** Error-based SQL injection is only reported when the
+  database error appears in the injected response and not in the baseline.
+- **Timing re-sampling.** A single slow response proves nothing: garbage
+  collection, cold starts and network jitter all look like an injected sleep.
+  Time-based SQL and command injection candidates are re-sent and only
+  reported when the median delay holds (`confirmTimingDelay`). Crosby et al.
+  showed that network jitter dominates single remote timing measurements and
+  that filtering over many samples is what makes them usable
+  [crosby2009opportunities], building on Kocher's original timing attacks
+  [kocher1996timing]. Penthera's delays are seconds, not microseconds, so a
+  median of three samples is enough.
+- **Host-checked redirects.** An open redirect is reported only if the
+  `Location` header actually resolves to the attacker host, not when the
+  payload merely appears in a same-site redirect's query string.
+- **Context-aware suppression.** On localhost and private hosts, findings that
+  do not apply (no HTTPS, missing `Secure` on cookies) are suppressed.
+
+The benchmark's decoy target exercises each of these with an endpoint built to
+fool a naive scanner. Writing it found one real problem in the decoy itself: a
+"safe" redirect that accepted `/\evil.com`, which browsers treat as
+`//evil.com`. Penthera reported it correctly.
+
+## Non-destructive by default
+
+The `quick` and `standard` profiles send only requests a normal browser or API
+client would send: GETs, `OPTIONS`, and invalid login attempts. They do not
+send attack payloads, create or modify data, or exploit anything they find.
+
+Payload-based testing (`--deep`, `--fuzz`, `--adaptive`, or `--profile deep`)
+is opt-in and gated behind a confirmation prompt. Even then each probe sends a
+benign marker (a random string, arithmetic, a short sleep, `id`) rather than a
+working exploit, and stops at the first confirmation per endpoint. The
+adaptive engine may send unexpected HTTP methods, including `DELETE`, to
+routes with placeholder IDs; it is therefore never part of a default run.
+
+This follows Saltzer and Schroeder's fail-safe defaults and least privilege
+[saltzer1975protection]: the default does the least that is still useful, and
+anything riskier needs an explicit decision. NIST SP 800-115 makes the same
+distinction between non-intrusive assessment and penetration testing, and
+recommends written rules of engagement before the latter
+[scarfone2008sp800115].
+
+## Offline and no telemetry
+
+Penthera does not phone home. It sends no usage data, analytics or crash
+reports, and it has no accounts. Reports are written to local files.
+
+Network traffic goes to the target you name, with two documented exceptions:
+
+1. `--recon` (and the `deep` profile) queries public OSINT sources (crt.sh,
+   the Wayback Machine, AlienVault OTX) with the target domain. It is skipped
+   for localhost.
+2. The Retire.js check downloads the public Retire.js vulnerability database
+   from GitHub to compare JavaScript library versions locally. This is data,
+   not code: it is parsed as JSON and never executed. It is the one place a
+   detection input arrives at run time, and the roadmap's `--offline` egress
+   guard replaces it with a vendored copy shipped in releases.
+
+The benchmark enforces offline operation mechanically: it wraps `fetch` so any
+request to a non-loopback host is refused and counted, and fails if the count
+is not zero.
+
+These choices follow economy of mechanism and complete mediation
+[saltzer1975protection]: fewer network paths means fewer things to audit, and
+a tool that talks only to the target is easy to reason about in a regulated
+environment.
+
+## How new attack techniques are adopted
+
+Attack techniques change quickly. In the last few years: indirect prompt
+injection against LLM-integrated apps [greshake2023signed, perez2022ignore,
+liu2023prompt], package hallucination and slopsquatting
+[spracklen2025package], and attacks on agent tooling and MCP servers
+catalogued by OWASP [owasp2024llmtop10, owasp2025agentic, owasp2025mcptop10]
+and MITRE ATLAS [mitreatlas]. A scanner that does not keep up becomes a
+false sense of security.
+
+Penthera keeps up through reviewed releases, not through live updates:
+
+- **Rules ship as code in a release.** New probes, patterns and templates are
+  added by pull request, reviewed, tested against the benchmark, and published
+  in a versioned release with a CHANGELOG entry. There is no rule server, no
+  background update, and no command that fetches rules from the internet.
+- **Every new rule carries a source and a date.** A rule added after v1.2.0
+  records where the technique comes from (a paper, an advisory, an OWASP or
+  ATLAS entry, an incident write-up) and the date it was added. Categories are
+  already linked to their sources in [lib/references.json](../lib/references.json);
+  the built-in rules that predate this policy are being backfilled.
+- **Every new rule comes with a benchmark case.** A detection rule is added
+  together with a labelled true positive and, where a false positive is
+  plausible, a decoy in [bench/](../bench/). The CI floor in the benchmark
+  stops a rule that adds false positives.
+- **Your own templates stay local.** `--nuclei <path>` and `--templates <dirs>`
+  load YAML templates from directories you choose. Penthera does not download
+  them.
+
+Why not auto-update? A rule feed is a code path from someone else's server
+into a tool that runs with your network access and often your credentials.
+Supply-chain research shows that update channels and package registries are
+exactly where attackers insert themselves [ladisa2023sok, ohm2020backstabber,
+zimmermann2019small], and that securing an update channel needs signed
+metadata, key rotation and explicit trust delegation [samuel2010survivable,
+torresarias2019intoto]. Shipping rules inside the signed, versioned package
+reuses the trust you already place in the release, and gives a clear audit
+trail: the rules you ran are the rules in the version you installed.
+
+## Citations in reports
+
+Each finding category maps to one to three references in
+[lib/references.json](../lib/references.json). They appear:
+
+- in the Markdown report, as a "Why this matters / Sources" line under each
+  finding and a "Sources" line under each action-plan item;
+- in SARIF [oasis2023sarif], as the rule's `helpUri` (first source) and
+  `help` text (all sources), and as `properties.references` (the BibTeX keys).
+
+[references.md](references.md) and the `sources` block of `references.json`
+are generated from [references.bib](references.bib) by
+`node scripts/build-references.mjs`, and a test fails if they drift.
+
+## Known limitations
+
+- No authenticated crawling beyond the bearer token or cookie you pass, so
+  pages behind multi-step flows are not reached [doupe2010johnny].
+- No stored or second-order injection testing [bau2010state].
+- No DOM-based XSS analysis; Penthera does not run JavaScript
+  [lekies2013flows, stock2014precise].
+- No business logic testing. IDOR/BOLA findings need a human to confirm.
+- Secret detection is pattern-based and skips Markdown and other
+  documentation files, so unprefixed secrets and secrets in notes are missed.
+- The bundled benchmark was written by the same people as the scanner. Its
+  numbers measure regressions and the false-positive controls, not accuracy on
+  arbitrary applications. Independent benchmarks such as the OWASP Benchmark
+  [owaspbenchmark] and the approach of Antunes and Vieira
+  [antunes2010benchmarking, antunes2015assessing] are the model for a fairer
+  comparison, and scoring against labelled third-party targets (Juice Shop,
+  crAPI) is the next step.
+- Compliance output (NIS2 [eu2022nis2]) is evidence toward a duty of care, not
+  a certification.

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/evidence.md

@@ -0,0 +1,158 @@
+# Evidence bundles and audience reports
+
+Penthera can write the results of one scan as an **evidence bundle**: every
+report, a manifest with the SHA-256 of each file, and an optional SSH
+signature over the manifest. An auditor checks the bundle with one command.
+No hosted service is involved, and nothing needs to be installed beyond Node
+(or `shasum` and `jq`) and OpenSSH 8.0 or later.
+
+## For auditors: verify a bundle
+
+You need the bundle directory and an **allowed signers file** that names the
+key you expect the bundle to be signed with. Get that public key from the
+organisation through a channel other than the bundle itself (their security
+page, an email you can authenticate, or in person).
+
+```bash
+npx penthera evidence verify ./evidence --allowed-signers allowed_signers
+```
+
+Exit code `0` means every file matches the manifest and the manifest was signed
+by a key in `allowed_signers`. Exit code `1` means something changed, is
+missing, was added, or the signature does not check out; the output says which.
+
+An `allowed_signers` file is one line per key:
+
+```text
+security@example.com namespaces="penthera-evidence" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
+```
+
+### Without Penthera
+
+The bundle does not depend on Penthera to be checked. With standard tools:
+
+```bash
+cd evidence
+# 1. The manifest was signed by the expected key (namespace penthera-evidence)
+ssh-keygen -Y verify -f ../allowed_signers -I security@example.com \
+  -n penthera-evidence -s manifest.json.sig < manifest.json
+# 2. Every artifact matches its hash in the manifest
+jq -r '.artifacts[] | "\(.sha256)  \(.path)"' manifest.json | shasum -a 256 -c -
+# 3. Nothing else is in the directory
+ls
+```
+
+`penthera evidence verify` does the same three checks, and also rejects
+manifest paths that would leave the directory (`../`, absolute paths) and
+symlinked files.
+
+### What the checks prove, and what they do not
+
+- **Hashes** prove that the files have not changed since the manifest was
+  written. Without a signature they prove nothing about who wrote it: anyone
+  can rewrite a file and its hash together.
+- **The signature** proves that the holder of the signing key produced this
+  manifest. It does not prove that the scan was run against the system you
+  care about, or with the options you expect. Read the manifest's `command`,
+  `target`, `scan` and `git` fields, and the auditor report's scope section.
+- Without `--allowed-signers`, `verify` still checks that the signature is
+  valid but cannot tell you whose key made it. It reports
+  `valid-unknown-signer` as a warning.
+- A scan is a snapshot. The bundle is evidence of what Penthera saw at
+  `generated_at`, not a statement that the system is secure.
+
+## For the team producing evidence
+
+```bash
+penthera https://staging.example.com --repo . --framework nis2 \
+  --evidence evidence/2026-10-19 --sign-key ~/.ssh/id_ed25519
+```
+
+- `--evidence <dir>` writes the bundle. The directory must be new or empty, so
+  a bundle never mixes two runs.
+- `--sign-key <key>` signs `manifest.json` with
+  `ssh-keygen -Y sign -n penthera-evidence`. Use the private key path, or the
+  `.pub` path when the key lives in `ssh-agent` or on a hardware token. A
+  passphrase prompt appears in the terminal.
+- `--sbom <file>` and `--readiness` add their outputs to the bundle.
+- Give auditors the public key out of band, as an `allowed_signers` line.
+
+### What is in a bundle
+
+| File | Contents |
+|------|----------|
+| `report.json` | The full scan result |
+| `report.md` | The default Markdown report |
+| `report.sarif` | SARIF 2.1.0 |
+| `report-developer.md` | Findings with file:line, fix recipe ids or diffs, and sources |
+| `report-owner.md` | Plain-language summary, what to do first, owner actions, trend |
+| `report-auditor.md` | Scope and method, confidence and provenance, egress, inconclusive probes, suppressions, fix timeline, NIS2 and OWASP mapping |
+| `report-custom.md` | Your `--report-template` output, when given |
+| `nis2-readiness.md` | With `--readiness` |
+| `sbom.cdx.json` | CycloneDX SBOM, with `--sbom` |
+| `manifest.json` | Tool version, command line (secrets redacted), timestamp, target, git commit, SHA-256 and size of every file above |
+| `manifest.json.sig` | SSH signature over `manifest.json`, with `--sign-key` |
+
+The command line in the manifest has the values of `--auth-cookie`,
+`--auth-bearer` and any token, secret or password flag replaced with
+`[REDACTED]`, and credentials in URLs masked.
+
+## Audience reports
+
+`--audience developer|owner|auditor` picks who the Markdown report is for. It
+applies to `--markdown <file>`; without `--markdown` the report goes to stdout.
+The default report (no `--audience`) is unchanged.
+
+```bash
+penthera https://example.com --repo . --audience owner > for-the-owner.md
+penthera https://example.com --repo . --audience auditor --markdown audit.md
+```
+
+When a scan used `--memory`, the owner report shows the trend across recent
+scans. When the result has an agent loop run (`loopRun`) or memory has fix
+events, the developer, owner and auditor reports show a fix timeline:
+found → fixed → verified, with time to fix.
+
+## Your own template
+
+`--report-template file.md` renders your own Markdown from the same data the
+audience reports use. The language is deliberately tiny:
+
+```markdown
+# Security status for {{summary.target}}
+
+{{summary.critical}} critical, {{summary.high}} high ({{summary.total}} total).
+
+{{#each findings}}
+- [{{severity}}] {{title}}{{#if location}} at {{location}}{{/if}} ({{confidence}})
+{{/each}}
+
+{{#if suppressed}}
+Set aside: {{#each suppressed}}{{title}} by {{actor}}: {{reason}}; {{/each}}
+{{else}}
+Nothing suppressed.
+{{/if}}
+```
+
+- `{{path.to.value}}` prints a value. Values are HTML- and Markdown-escaped,
+  and newlines become spaces, so a finding title cannot add HTML, a heading, a
+  list item or a table cell.
+- `{{#each list}}…{{/each}}` loops; inside, `{{this}}` is the item and
+  `{{@index}}` its 0-based index. Names not found on the item are looked up in
+  the enclosing scope.
+- `{{#if value}}…{{else}}…{{/if}}`; an empty list counts as false.
+
+There are no helpers, no expressions, no raw output, no partials and no file
+includes. Paths containing `__proto__`, `constructor` or `prototype` are
+rejected, and only own properties are read. A template that uses anything else
+fails with a line number before the scan starts.
+
+Top-level fields: `tool`, `target`, `timestamp`, `duration`, `modes`,
+`profile`, `offline`, `probes`, `summary` (`critical`, `high`, `medium`,
+`low`, `info`, `serious`, `total`, `suppressed`, `inconclusive`), `findings`
+(`fid`, `title`, `severity`, `confidence`, `source`, `method`, `collectedAt`,
+`category`, `location`, `file`, `line`, `url`, `description`, `recipe`,
+`fixText`, `sources`, `owasp`, `wstg`), `suppressed` (`title`, `severity`,
+`reason`, `actor`, `by`, `expires`), `inconclusive`, `egress`, `actions`,
+`topActions`, `ownerActions`, `nis2`, `owasp`, `trend` and `timeline`. The
+model is built in [`src/report/model.js`](../src/report/model.js).