penthera 1.5.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/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.

package/docs/evidence.md

@@ -14,7 +14,7 @@ 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
+npx penthera evidence verify ./evidence --allowed-signers allowed_signers --require-signature
 ```
 
 Exit code `0` means every file matches the manifest and the manifest was signed
@@ -55,9 +55,13 @@ symlinked files.
   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 signed bundle only verifies with `--allowed-signers`. Without it,
+  `verify` cannot tell whose key made the signature (anyone can re-sign a
+  rewritten manifest with their own key), so it fails with status
+  `unverified`. A manifest that declares a signature with no `.sig` file
+  fails too.
+- An unsigned bundle passes with an `UNSIGNED` warning. Pass
+  `--require-signature` (with `--allowed-signers`) to make it fail.
 - A scan is a snapshot. The bundle is evidence of what Penthera saw at
   `generated_at`, not a statement that the system is secure.
 

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

@@ -35,18 +35,18 @@ jobs:
     env:
       PENTHERA_VERSION: latest # pin, e.g. 1.3.0
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: head
           persist-credentials: false
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.base.sha }}
           path: base
           persist-credentials: false
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 22
 
@@ -89,7 +89,7 @@ jobs:
             gh pr comment "$PR" --repo "$REPO" --body-file "$body"
           fi
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         if: always()
         with:
           name: penthera-deps

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

@@ -24,7 +24,7 @@ jobs:
       contents: read
       security-events: write
     steps:
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 22
 
@@ -34,7 +34,7 @@ jobs:
         run: |
           mkdir -p reports
           set +e
-          npx --yes penthera@1.5.0 "$PENTEST_URL" \
+          npx --yes penthera@1.6.0 "$PENTEST_URL" \
             --profile standard \
             -o reports/scan.json \
             --sarif reports/scan.sarif
@@ -43,12 +43,12 @@ jobs:
           # Exit 1 = critical or high findings (reported via SARIF); only 2 (scan error) fails the job.
           if [ "$code" -eq 2 ]; then exit 2; fi
 
-      - uses: github/codeql-action/upload-sarif@v4
+      - uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         if: always()
         with:
           sarif_file: reports/scan.sarif
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         if: always()
         with:
           name: penthera-reports

package/docs/index.md

@@ -8,6 +8,9 @@ Open-source security for the apps and AI systems you ship: check it before you d
 |-------|-------------|
 | [README](../README.md) | Install, quick start, ethical use |
 | [Run it](../README.md#run-it) | Install + first-time wizard (`penthera` with no args) |
+| [Use cases](./use-cases/README.md) | By situation: [before launch](./use-cases/solo-founder.md), [AI-coding teams](./use-cases/ai-coding-teams.md), [maintainers](./use-cases/open-source-maintainers.md), [EU SMEs](./use-cases/eu-sme-compliance.md), [agencies](./use-cases/agencies.md) |
+| [Comparisons](./compare/README.md) | Using Penthera with [Socket](./compare/socket.md), [Snyk](./compare/snyk.md), [GitHub](./compare/github.md), [ZAP](./compare/zap.md), [Semgrep](./compare/semgrep.md) |
+| [Commands](./commands/README.md) | One page per command: [scan](./commands/scan.md), [agents](./commands/agents.md), [deps](./commands/deps.md), [install](./commands/install.md), [fix](./commands/fix.md), [hook](./commands/hook.md), [action](./commands/action.md), [skill](./commands/skill.md) |
 | [CHANGELOG](../CHANGELOG.md) | Version history |
 | [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 |
 
@@ -36,6 +39,10 @@ Open-source security for the apps and AI systems you ship: check it before you d
 | OWASP WSTG mapping | [owasp-wstg-coverage.md](./owasp-wstg-coverage.md) |
 | NIS2 compliance guide | [compliance-nis2.md](./compliance-nis2.md) |
 | Local loop and learning store | [local-loop.md](./local-loop.md) |
+| CRA reporting and AI-BOM | [compliance-cra.md](./compliance-cra.md) |
+| Reports and evidence bundles | [evidence.md](./evidence.md) |
+| Privacy, network use, `--offline` | [privacy.md](./privacy.md) |
+| Local dashboard (`penthera ui`) | [dashboard.md](./dashboard.md) |
 | Scan your app in GitHub Actions | [examples/github-actions-scan.yml](./examples/github-actions-scan.yml), set `PENTEST_STAGING_URL` |
 | Penthera's own CI | `.github/workflows/ci.yml` (full tests + mock scan), `codeql.yml`, `scorecard.yml` |
 | Docker | `docker build -t penthera . && docker run penthera https://localhost:3000` |
@@ -48,6 +55,8 @@ Open-source security for the apps and AI systems you ship: check it before you d
 | Cited research and standards | [references.md](./references.md) ([BibTeX](./references.bib)) |
 | Accuracy benchmark (`npm run bench`) | [bench/README.md](../bench/README.md), latest [results](../bench/RESULTS.md) |
 | Citing Penthera | [CITATION.cff](../CITATION.cff) |
+| Refresh the README's numbers | `npm run docs:numbers` (`-- --tests` to count tests) |
+| How Socket positions itself, and what Penthera took from it | [research/socket-positioning-notes.md](./research/socket-positioning-notes.md) |
 
 ## Agent skill