penthera 1.4.0 → 1.6.0

package/docs/compare/semgrep.md

@@ -0,0 +1,54 @@
+# Penthera and Semgrep
+
+*Last checked: 2026-10-19 against Semgrep's docs, GitHub and pricing page.*
+
+## Use them together
+
+[Semgrep](https://semgrep.dev) is a static analyser for your own code. The
+Community Edition engine is open source (LGPL-2.1) and runs locally; the
+commercial AppSec Platform adds cross-file analysis, supply-chain reachability,
+secrets and AI triage ([CE vs platform](https://docs.semgrep.dev/semgrep-pro-vs-oss)).
+Penthera's repo scan is narrower than Semgrep's. What Penthera adds is the rest
+of the picture: the running app, what your dependencies can do, and your AI
+tooling.
+
+A reasonable setup: Semgrep on every pull request for code patterns, with your
+own rules if you write them. Penthera for the lockfile, the preview URL and the
+agent config.
+
+## Side by side
+
+| | Penthera | Semgrep |
+|---|---|---|
+| Your code | Route discovery, trust-boundary mapping and secrets for Next.js, Express, Hono, Fastify | Pattern-based analysis in many languages; CE works within a single file, the platform adds cross-file taint analysis ([CE vs platform](https://docs.semgrep.dev/semgrep-pro-vs-oss)) |
+| Rules | Built in and readable; no rule language for users | A rule language plus 2,000+ community rules in the Registry ([repo](https://github.com/semgrep/semgrep)) |
+| Dependencies | Capabilities, upgrade diff, typosquats, licenses (npm and Python) | Semgrep Supply Chain with reachability, on the platform |
+| Running app | URL scan | No |
+| AI tooling | `penthera agents` | No dedicated check |
+| Network | None needed | CE with local rules sends no metrics by default; `--metrics=off` turns them off ([metrics](https://docs.semgrep.dev/metrics)) |
+| Cost | Free, MIT | CE is free. Platform free for up to 10 contributors; Teams from $30 per contributor a month per product ([pricing](https://semgrep.dev/pricing)) |
+
+## Where Semgrep goes further
+
+- **Code analysis depth and breadth**: many languages, and dataflow across files
+  on the platform.
+- **Your own rules.** If your team has patterns to ban, Semgrep's rule language
+  is the right tool. Penthera has no user rule language for code.
+- **Reachability** for dependency vulnerabilities.
+
+## Where Penthera adds something
+
+- **Outside the source**: the running app, what packages do when installed, and
+  the agent config on your machine.
+- **Fixes that are verified** by a re-scan on a local branch.
+- **EU evidence** from the same runs.
+
+## Run both
+
+```bash
+semgrep scan --config p/default --sarif -o semgrep.sarif
+npx penthera http://localhost:3000 --repo . --sarif penthera.sarif
+npx penthera deps --base origin/main
+```
+
+[All comparisons](README.md) · [Back to the README](../../README.md)

package/docs/compare/snyk.md

@@ -0,0 +1,62 @@
+# Penthera and Snyk
+
+*Last checked: 2026-10-19 against Snyk's public docs, pricing page and GitHub.*
+
+## Use them together
+
+[Snyk](https://snyk.io) is a developer security platform built around a curated
+vulnerability database: it tells you which of your dependencies, containers and
+infrastructure files have known issues, across many languages, and opens fix
+pull requests. Penthera asks different questions: what can a package do (not
+only which CVEs it has), how does the running app behave, and what is in your
+AI tooling config. It does this offline and without an account.
+
+A reasonable setup: Snyk for known-vulnerability coverage across your stack.
+Penthera for the behaviour diff on lockfile changes, the scan of your preview
+URL before a deploy, and the agent-config audit.
+
+## Side by side
+
+| | Penthera | Snyk |
+|---|---|---|
+| Dependencies | What each npm and Python package can do (install scripts, shell, network, env, obfuscation), what an upgrade added, typosquats, licenses | Known vulnerabilities and licenses across 13+ package ecosystems ([supported languages](https://docs.snyk.io/supported-languages/supported-languages-package-managers-and-frameworks)) |
+| Your code | Route discovery, trust boundaries and secrets for JS/TS frameworks | Snyk Code static analysis in 16 languages ([supported languages](https://docs.snyk.io/supported-languages/supported-languages-package-managers-and-frameworks)) |
+| Running app | URL scan (headers, TLS, CORS, auth, JWT, IDOR, OAuth, OpenAPI; opt-in injection and fuzzing) | Snyk API & Web, a DAST product on Enterprise plans ([plans](https://snyk.io/plans/)) |
+| Containers, IaC | No | Yes ([CLI](https://docs.snyk.io/developer-tools/snyk-cli)) |
+| AI tooling | `penthera agents`: skills, MCP servers, hooks, permissions, plugins, rule files, checked locally | Snyk Agent Scan: MCP servers and skills, sends component metadata to Snyk's API and needs a token ([agent-scan](https://github.com/snyk/agent-scan)) |
+| Account | None | Required for the CLI ([authenticate](https://docs.snyk.io/developer-tools/snyk-cli/authenticate-to-use-the-cli)) |
+| Fixes | Deterministic recipes as local diffs, re-scanned to verify; never pushes | Fix pull requests through SCM integrations ([fix PRs](https://docs.snyk.io/scan-with-snyk/pull-requests/snyk-fix-pull-or-merge-requests)) |
+| Editor | Through your coding agent (Agent Skill) | Plugins for VS Code, JetBrains, Visual Studio, Eclipse ([IDE](https://docs.snyk.io/developer-tools/snyk-ide-plugins-and-extensions)) |
+| Licence | MIT | CLI is Apache-2.0 ([repo](https://github.com/snyk/cli)); the platform is commercial |
+| Cost | Free | Free plan with 5 projects and 100 Snyk Code tests a month; Team from $25 a month ([plans](https://snyk.io/plans/)) |
+
+## Where Snyk goes further
+
+- **Curated vulnerability data** across many languages, with advisories written
+  and maintained by a research team. Penthera does not track CVEs for your
+  dependencies beyond the vendored Retire.js database for front-end scripts.
+- **Breadth**: containers, infrastructure as code, many more languages.
+- **Reachability analysis** to cut a CVE list down to what you call.
+- **Organisation features**: dashboards, policies across many repos, reporting.
+
+## Where Penthera adds something
+
+- **Behaviour, not only known issues.** A new install script or a package that
+  suddenly reads your whole environment shows up even when no CVE exists yet.
+- **The running app**, free, on localhost.
+- **Fully local.** No account, no API calls, nothing about your code leaves the
+  machine. The AI-tooling audit is local too.
+- **EU evidence**: NIS2 readiness, CRA report drafts, SBOM and AI-BOM, and a
+  signable evidence bundle.
+
+## Run both
+
+```bash
+snyk test                               # known vulnerabilities in dependencies
+npx penthera deps --base origin/main    # what the new packages can do
+npx penthera http://localhost:3000 --repo .
+```
+
+Both write SARIF, so both can upload to GitHub code scanning.
+
+[All comparisons](README.md) · [Back to the README](../../README.md)

package/docs/compare/socket.md

@@ -0,0 +1,78 @@
+# Penthera and Socket
+
+*Last checked: 2026-10-19 against Socket's public docs and pricing page.*
+
+## Use them together
+
+[Socket](https://socket.dev) watches the open-source registries for malicious and
+risky packages and tells you about them in pull requests, in your editor and at
+install time. Penthera runs on your machine and checks the app you built, the
+packages already in your lockfile, and the AI tooling you build it with.
+
+A reasonable setup: Socket's GitHub app or firewall on every dependency change,
+because it watches new releases across the registries and Penthera does
+not. Penthera before each deploy, for the app scan, the agent-config audit
+and the evidence, and anywhere a network call or an account is not an option.
+
+## Side by side
+
+| | Penthera | Socket |
+|---|---|---|
+| Main question | Is the thing I am about to ship safe, and can I prove it? | Is this package safe to depend on? |
+| Scope | Your running app (URL scan), your source (repo scan), your dependencies, your AI tooling (skills, MCP, hooks), fixes, NIS2 and CRA evidence | Packages across many ecosystems, plus browser extensions and AI models ([language support](https://docs.socket.dev/docs/language-support)) |
+| Ecosystems for dependencies | npm and Python | JS/TS, Python, Go, Java, Ruby, .NET, Rust and more ([language support](https://docs.socket.dev/docs/language-support)) |
+| How it decides | Deterministic rules in the repo, with `file:line` evidence and a confidence label | Static analysis followed by an LLM stage, with researchers confirming detections ([AI alert](https://socket.dev/alerts/gptMalware)) |
+| Threat intelligence | None beyond what ships in a release | Registry-wide and continuously updated |
+| Network | None needed; `--offline` limits traffic to the target you named | The CLI and firewall query Socket's API ([CLI](https://github.com/SocketDev/socket-cli), [firewall](https://docs.socket.dev/docs/socket-firewall-overview)) |
+| Account | None | API token for the CLI; the firewall's free wrapper mode needs no key ([firewall](https://docs.socket.dev/docs/socket-firewall-overview)) |
+| Install-time guard | `penthera install`: reviews capabilities and install scripts before any script runs (npm) | Socket Firewall (`sfw`): blocks known-malicious packages for npm, yarn, pnpm, pip, uv and cargo in free mode |
+| Pull requests | GitHub Action that comments the capability diff | GitHub app that comments on risky dependency changes ([docs](https://docs.socket.dev/docs/socket-for-github)) |
+| AI tooling | Audits the skills, MCP servers, hooks, permissions and plugins already on disk | An MCP server agents can use to look up package scores ([MCP guide](https://docs.socket.dev/docs/guide-to-socket-mcp)); firewall coverage for agent skills and AI models as downloads ([firewall](https://socket.dev/features/firewall)) |
+| App security | URL and repo scans, fix recipes | Not its focus; SAST and secrets are on the Enterprise plan ([pricing](https://socket.dev/pricing)) |
+| SBOM | CycloneDX SBOM and AI-BOM, free | Business plan and up ([pricing](https://socket.dev/pricing)) |
+| Licence | MIT | `socket` CLI and MCP server MIT; `sfw` under PolyForm Shield 1.0.0 (source-available) ([sfw-free](https://github.com/SocketDev/sfw-free)) |
+| Cost | Free | Free plan (1 seat, 1,000 scans a month); free Business plan for OSI-licensed public projects ([announcement](https://socket.dev/blog/free-business-plan-upgrades-for-open-source)); paid seats from $25 a month ([pricing](https://socket.dev/pricing)) |
+
+## Where Socket goes further
+
+- **It sees the whole registry.** A freshly published package with a
+  credential stealer in it can be flagged by Socket before you install it.
+  Penthera only sees what is in front of it, with rules from its last release.
+- **More ecosystems.** Penthera's dependency checks cover npm and Python today,
+  and its install firewall covers npm only.
+- **Human research.** Socket's researchers confirm and publish malware
+  findings. Penthera has no threat-research team.
+- **Reachability** on paid plans, which narrows a long CVE list to the code paths
+  you call.
+
+## Where Penthera adds something
+
+- **Your app, not only its packages.** Headers, auth, IDOR, OAuth, OpenAPI,
+  secrets in source, and fixes that are re-scanned to prove they worked.
+- **The AI tooling on your machine.** `penthera agents --home` reads your Claude
+  Code, Cursor and MCP config and flags hidden instructions, unpinned servers and
+  over-broad permissions.
+- **Offline and account-free**, which matters on air-gapped machines, in some
+  public-sector work, and for anyone who cannot send a dependency list to a
+  vendor.
+- **Readable verdicts.** Every finding points at a rule in this repository.
+
+## A note on AI verdicts
+
+Socket's AI scanner once flagged Penthera itself as malware. That is an
+understandable call: Penthera's test suite contains real attack payloads,
+because a security scanner has to be tested against them. It is also a fair
+illustration of the trade-off. An AI stage catches novel malware that no rule
+anticipated, and it can misread intent. Deterministic rules miss what they were
+not written for, and they always tell you exactly why they fired. The two
+approaches cover each other's gaps, which is a good reason to run both.
+
+## Run both
+
+```bash
+sfw npm install            # Socket Firewall: block known-bad packages at install
+npx penthera deps --base origin/main   # what the new packages can do, offline
+npx penthera agents --home             # your AI tooling
+```
+
+[All comparisons](README.md) · [Back to the README](../../README.md)

package/docs/compare/zap.md

@@ -0,0 +1,59 @@
+# Penthera and OWASP ZAP
+
+*Last checked: 2026-10-19 against zaproxy.org and the ZAP GitHub repositories.*
+
+## Use them together
+
+[ZAP](https://www.zaproxy.org) is the long-standing open-source dynamic scanner
+for web apps: a proxy, spiders, passive and active scan rules, scripting, and an
+automation framework. Since September 2024 it is branded ZAP by Checkmarx and
+remains Apache 2.0 ([announcement](https://www.zaproxy.org/blog/2024-09-24-zap-has-joined-forces-with-checkmarx/)).
+Penthera's URL scan covers a smaller, opinionated set of checks, and pairs them
+with the source code, your dependencies and your AI tooling.
+
+A reasonable setup: Penthera as the quick first pass on every preview URL,
+with source context and fixes. ZAP for deeper dynamic testing, manual
+exploration through its proxy, and anything that needs a logged-in browser crawl.
+
+## Side by side
+
+| | Penthera | ZAP |
+|---|---|---|
+| Dynamic testing | Headers, TLS, CORS, cookies, auth hardening, JWT, IDOR, OAuth, OpenAPI probes; injection and fuzzing are opt-in | Passive and active scan rules, spider and AJAX spider ([features](https://www.zaproxy.org/docs/desktop/start/features/), [AJAX spider](https://www.zaproxy.org/docs/desktop/addons/ajax-spider/)) |
+| API definitions | OpenAPI and FastAPI | OpenAPI, SOAP and GraphQL ([API scan](https://www.zaproxy.org/docs/docker/api-scan/)) |
+| Manual testing | No | Intercepting proxy and desktop UI |
+| Source code | Repo scan in the same run (`--repo .`) maps routes and finds secrets | No |
+| Dependencies, AI tooling | Yes | No |
+| Fixes | Framework-aware fix recipes, re-scanned to verify | Reports alerts |
+| Automation | CLI, GitHub Action, SARIF | YAML Automation Framework, Docker packaged scans, the ZAP Baseline Scan action ([automate](https://www.zaproxy.org/docs/automate/)) |
+| Runtime | Node.js 22+ | Java 17+, or Docker ([download](https://www.zaproxy.org/download/)) |
+| Licence | MIT | Apache 2.0 |
+
+## Where ZAP goes further
+
+- **Depth of dynamic testing**: many more active scan rules, a mature crawler
+  for JavaScript-heavy apps, and years of tuning.
+- **Manual work**: the intercepting proxy lets a person explore and replay.
+- **Authentication**: browser-based, scripted and OAuth2 logins in the
+  automation framework ([automation framework](https://www.zaproxy.org/docs/automate/automation-framework/)).
+  Penthera takes a cookie or bearer token.
+- **Community**: a large add-on ecosystem and documentation.
+
+## Where Penthera adds something
+
+- **Black box and white box together.** A URL finding can point at the route
+  handler in your repo, and the repo scan finds routes the crawler never saw.
+- **Fixes**, applied as diffs on a local branch and re-scanned.
+- **Beyond the app**: dependency capabilities, AI-tooling audit, NIS2 and CRA
+  evidence.
+- **A confidence label on every finding**, so a heuristic match never reads as a
+  confirmed vulnerability.
+
+## Run both
+
+```bash
+npx penthera http://localhost:3000 --repo . --sarif penthera.sarif
+docker run -t ghcr.io/zaproxy/zaproxy:stable zap-baseline.py -t http://host.docker.internal:3000
+```
+
+[All comparisons](README.md) · [Back to the README](../../README.md)

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

@@ -0,0 +1,244 @@
+# The local dashboard: `penthera ui`
+
+`penthera ui` opens a dashboard in your browser for what Penthera knows about
+your projects: where each one stands, what each finding means, what changed
+since the last scan, your dependencies and AI tooling, and evidence for an
+auditor. It can also run scans and the fix loop for you, stopping at every
+diff. It runs on `127.0.0.1` only, reads only the folders you give it and
+`~/.penthera`, and never contacts the network.
+
+| Dark | Light |
+|---|---|
+| ![Overview, dark theme](../assets/dashboard/overview-dark.jpg) | ![Overview, light theme](../assets/dashboard/overview-light.jpg) |
+
+## Start it
+
+```bash
+penthera ui --open                       # current folder, reports in ./reports
+penthera ui --project ~/code/shop --project ~/code/api --reports ~/code/shop/reports
+penthera ui --demo                       # fake data, nothing read from disk
+```
+
+| Option | Default | What it does |
+|--------|---------|--------------|
+| `--port <n>` | `0` (random free port) | Port on 127.0.0.1 |
+| `--open` | off | Open the one-time URL in your browser |
+| `--project <dir>` | the current folder | A folder the dashboard may read and run in. Repeat for more |
+| `--reports <dir>` | `<first project>/reports` | Where report JSON is read from, and where runs started here write theirs |
+| `--demo` | off | Realistic fake data and a scripted fix loop. For a first look, screenshots and docs |
+
+It prints a URL with a one-time token. Open it once: the token is swapped for
+a session cookie and stops working, so a second browser (or a link that leaked
+into history) gets a 403. Restart `penthera ui` for a new link. Ctrl-C stops
+the server.
+
+## User stories
+
+Each story names who it is for, what they want and why. Each one has a
+feature in the dashboard and a screenshot from `penthera ui --demo`.
+
+**1. First run, nothing scanned yet.** *As a solo founder the week before
+launch, I want the dashboard to tell me what to do first when there is no
+data yet, so that I am not staring at empty charts.* The overview turns into
+a three-step start: scan your app, check your dependencies, audit your AI
+tooling. Each step opens Run with the right mode and your project folder
+filled in.
+
+![Story 1: the Welcome screen with three steps](../assets/dashboard/story-first-run.jpg)
+
+**2. Run a scan from the UI.** *As a developer who does not live in the
+terminal, I want to start a scan from the page and watch it work, so that I
+know it ran and where the report went.* Run has four modes: scan app, check
+dependencies, audit AI tooling, fix loop. A URL that is not on this machine
+needs its hostname typed back first. Output streams into a terminal window;
+when it finishes, "What next?" offers the obvious next steps.
+
+![Story 2: a scan streaming in the terminal window](../assets/dashboard/story-scan.jpg)
+
+**3. Let the agent fix things, one approved diff at a time.** *As a founder
+with no security engineer, I want Penthera to propose fixes and apply only the
+ones I approve, so that nothing changes in my code without me seeing it.* The
+fix loop stops at every diff with a dialog: the recipe, the files, what the
+fix closes, what memory knows about this recipe, and the diff itself. Apply
+(`y`), Skip (`n`) or Stop the loop (`q`). Verified fixes are committed on a
+local branch; failed ones are reverted. Nothing is pushed.
+
+![Story 3: the approval dialog for a fix](../assets/dashboard/story-loop.jpg)
+
+**4. Understand one finding.** *As a product owner who is not a security
+expert, I want one finding explained in plain words, so that I can decide
+whether it matters today.* The detail panel opens with "In plain words": how
+serious it is, how sure Penthera is (and what that confidence level means),
+what to do, and the OWASP mapping. Below it: what was seen, the evidence, the
+sources, and the exact fix diff.
+
+![Story 4: a finding explained in plain words](../assets/dashboard/story-finding.jpg)
+
+**5. Compare over time.** *As a tech lead after a release, I want to compare
+two scans of the same project, so that I can see what got fixed and what is
+new.* History picks the most interesting project by default, compares the
+previous scan with the latest (or any two you choose), and lists new, fixed
+and still-open findings in three columns. Below them, a timeline draws every
+finding as a bar across the scans (S1, S2, ...): hatched while it is still
+open, an outline once it was fixed.
+
+![Story 5: history comparing two scans](../assets/dashboard/story-history.jpg)
+
+**6. Export evidence for an auditor.** *As the person who answers the NIS2
+questionnaire, I want a package an auditor can check without trusting me, so
+that the evidence holds up.* Evidence creates a bundle from the latest scan
+of a project (JSON, Markdown, SARIF, the auditor, owner and developer reports,
+and a manifest with a SHA-256 per file), verifies it straight away, and lets
+you download the auditor report as Markdown.
+
+![Story 6: a new bundle, verified, with downloads](../assets/dashboard/story-evidence.jpg)
+
+**7. Check what a dependency change can do.** *As a developer reviewing a
+pull request that bumps the lockfile, I want to see which packages gained new
+capabilities, so that I catch a malicious update before it runs.* Dependencies
+shows the capabilities in the tree, the capability diff against your base,
+typosquats, and every install firewall decision.
+
+![Story 7: the capability diff](../assets/dashboard/story-deps.jpg)
+
+**8. Trust my AI tooling.** *As someone who installs skills and MCP servers
+into Claude Code and Cursor, I want to know whether any of them hide
+instructions or changed since I reviewed them, so that my agent is not working
+for someone else.* AI tooling shows the A to F grade, hidden content with the
+decoded text, and drift against `penthera.lock`.
+
+![Story 8: grade, hidden content and lock drift](../assets/dashboard/story-ai-tooling.jpg)
+
+**9. Know where to start this week.** *As a solo founder on a Monday morning,
+I want one place that says what to fix first and what changed since the last
+scan, so that I do not have to read every report.* The overview opens with a
+"This week" window: fix first (every critical and high), new since the last
+scan, and fixed since the last scan, across all projects. Each line opens the
+finding.
+
+![Story 9: the This week window](../assets/dashboard/story-week.jpg)
+
+**10. Work in daylight.** *As someone who reads reports on a bright screen, I
+want a light theme, so that the dashboard is comfortable outside a dark room.*
+The `◐` button in the menu bar (and Settings) switches between the black
+terminal and the white paper theme. The first visit follows your system
+setting; the choice is remembered in this browser.
+
+| Narrow, dark | Narrow, light |
+|---|---|
+| <img src="../assets/dashboard/narrow-dark.jpg" alt="Overview at 390px, dark" width="280"> | <img src="../assets/dashboard/narrow-light.jpg" alt="History at 390px, light" width="280"> |
+
+## Where the data comes from
+
+| Screen | Source |
+|--------|--------|
+| Overview | The latest scan report per target in the reports folder, plus trend and time to fix from local memory |
+| Findings | The same reports. The fix preview runs the fix recipes against the project folder, read-only |
+| Run | Live runs started from this page; past `loopRun` files; memory stats |
+| History | Every scan report of one project in the reports folder |
+| Dependencies | `penthera deps -o reports/deps.json` and `penthera install <pkg> --dry-run --json > reports/install.json` (or Run → Check dependencies) |
+| AI tooling | `penthera agents . -o reports/agents.json` (or Run → Audit AI tooling) |
+| Evidence | Bundles below the reports folder, written with `--evidence` or from this screen |
+| Settings | Theme, egress mode for scans started here, data locations, memory chain status |
+
+The reports folder is read one level deep for `*.json` (anything that is not
+a Penthera report is ignored) and two levels deep for evidence bundles.
+Symlinks are skipped. A memory chain that does not verify is shown as broken
+and its contents are not used, the same rule scans follow.
+
+## Running things from the page
+
+Run calls the same functions as the CLI (`executeScan`, `scanDeps`,
+`scanAgents`, `runLoop`) with the same rules. The fix loop needs a clean git
+tree on a branch, works on a local `penthera/fix-<yyyymmdd-hhmm>` branch, runs
+only allow-listed local git commands with hooks off, is always offline with
+egress limited to the URL's host, and never pushes. On top of that:
+
+- The project folder must be inside one of the `--project` folders.
+- A URL that is not on this machine (anything but `localhost`, `127.x.x.x`,
+  `[::1]` and `*.localhost`) needs its hostname typed back before the run
+  starts. Only scan what you own or have written permission to test.
+- One run at a time. Closing the tab does not stop a run; come back to Run and
+  it reattaches. Stop finishes the current step, and the fix branch holds only
+  verified commits.
+- Reports land in the reports folder (`loop-<timestamp>.json`,
+  `deps_<timestamp>.json`, and so on), so every screen picks them up.
+
+## Security model
+
+The dashboard is a web server on your machine, so any page open in the same
+browser can send it requests. Every request passes, in this order:
+
+1. **Host check.** The `Host` header must be exactly `127.0.0.1:<port>` or
+   `localhost:<port>`. This blocks DNS rebinding, where `attacker.example`
+   re-resolves to 127.0.0.1 so the attacker's page can read the response. It
+   runs before the token check, so a rebinding page cannot even redeem the
+   link.
+2. **Path check.** No dot segments, encoded dots or slashes, backslashes or NUL
+   bytes. Static files come from an allowlist built at startup; no part of a
+   request path is ever joined onto a filesystem path.
+3. **Session.** The one-time URL token is exchanged for an `HttpOnly;
+   SameSite=Strict` cookie and a redirect to `/`, so the token leaves the
+   address bar. Every request, static files included, needs the cookie.
+   Requests without it are rate-limited (429 with `Retry-After`).
+4. **Origin.** Every `POST` needs an `Origin` equal to the server's own (and
+   `Sec-Fetch-Site: same-origin` when the browser sends it) and a JSON body, so
+   a cross-site form or `fetch` cannot change anything.
+
+Every response carries:
+
+```
+Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self';
+  font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self';
+  frame-ancestors 'none'; require-trusted-types-for 'script'
+X-Frame-Options: DENY            X-Content-Type-Options: nosniff
+Referrer-Policy: no-referrer     Cache-Control: no-store
+Cross-Origin-Opener-Policy / -Resource-Policy / -Embedder-Policy
+```
+
+There are no CORS headers, and `OPTIONS` gets a 405. The page has no inline
+script or style, loads nothing from another host (no CDN, fonts, analytics or
+chart library), and never turns data into HTML: finding titles and evidence
+come from the sites and repos you scanned, so they are only ever set as text.
+Report downloads are served as `text/markdown` attachments from the same
+checks; the audience is one of `auditor`, `owner` or `developer`, nothing else.
+
+Penthera scans its own dashboard clean with `--profile standard`, signed in and
+not; `tests/ui.test.js` runs that scan on every test run, alongside tests for
+the Host check, the token and cookie, Origin, the headers, the rate limit and
+path traversal.
+
+## Design
+
+A 1-bit desktop with a terminal inside. The window chrome comes from the Mac
+of the early 90s, and the layout from a planning board the maintainer keeps in
+the same style (every section a pinstriped window with its date on the right,
+bold-ruled columns, a Gantt with dashed milestones): a menu bar, pinstriped title bars with close and zoom boxes,
+a dithered desktop, rounded push buttons where the default one wears a thick
+ring, and alert dialogs with a double frame. The voice, the `▸` progress
+lines, the numbered "What next?" and the `#0000ed` block-letter wordmark come
+straight from the CLI and its demo GIF, so the terminal, the README and the
+dashboard read as one product.
+
+- **Black, white and patterns do the work.** Severity is a word plus a
+  pattern swatch (solid, hatched, half-tone, dotted, empty), and bars are drawn
+  with shade characters `█ ▓ ▒ ░ ·`. Charts fill with hatching and dithering,
+  not colour.
+- **One accent.** `#0000ed` marks the active screen, the default button,
+  selection, links and chart lines. On black it measures 2.2:1, so there it is
+  only a fill (white text on it, 9.5:1), a frame or a glow; text in that hue
+  uses the tint `#7a7aff` (6.1:1). On white, `#0000ed` is text-safe (9.3:1).
+- **Green** is kept for the cursor, the prompt and "OK".
+- **Calm where it counts.** Pinstripes only on real windows and dialogs; data
+  sits in hairline group boxes, one stat strip, and tables with figure captions
+  that say where each number came from.
+- **Both themes pass WCAG AA** for every text node on every screen (measured in
+  the browser, composited). Light text uses a 0.6 ink step where the dark
+  theme uses 0.5, because 0.5 measures 3.6:1 on paper.
+- **Motion.** The output types itself out and the cursor blinks. With
+  `prefers-reduced-motion`, both stop and output appears whole. Screens switch
+  with `1`-`8` and have no transition.
+- **Keyboard.** `1`-`8` screens, `/` filter findings, `j`/`k` move through
+  findings, `y`/`n`/`q` answer a diff. Every control is a real button or link;
+  the approval dialog takes focus when a diff arrives; screen readers get each
+  log line whole, never letter by letter.