penthera 1.5.0 → 1.6.1

package/docs/internal-audit.md

@@ -0,0 +1,83 @@
+# Internal testing audit
+
+Penthera is a security tool, so its own release bar has to be easy to check.
+The internal audit is that bar: one command that runs every check a release
+needs and writes the result to [`audit/REPORT.md`](../audit/REPORT.md).
+
+```bash
+npm run audit:internal
+```
+
+It exits 1 if any gate fails. A release is only tagged from a commit whose
+audit passed (see the release checklist in
+[CONTRIBUTING.md](../CONTRIBUTING.md#cutting-a-release)). The same audit runs
+every Monday in CI ([`internal-audit.yml`](../.github/workflows/internal-audit.yml))
+so drift shows up between releases.
+
+## The gates
+
+| Gate | What it checks | Fails when |
+|---|---|---|
+| Test suite | `npm test`, with the live suites pointed at the bundled mock server (`PENTEST_BASE_URL`) | Any test fails |
+| Benchmark | `npm run bench` (offline, seeded) against the **Total** row of the committed [`bench/RESULTS.md`](../bench/RESULTS.md) | Precision or recall drops by more than 0.02, or any request leaves loopback |
+| Self-scan | `penthera --repo .`, `penthera agents .`, `penthera deps .`, and `penthera hook run` on a copy of the tree with every file staged | A high or critical finding is not in [`audit/baseline.json`](../audit/baseline.json), or a baseline entry has no reason |
+| CLI smoke | `--help` for every subcommand, plus a fixture run of each: a mock-server scan in every report format, `agents` on a clean and a malicious fixture, `deps`, `install --dry-run`, `fix --plan`, an evidence bundle and its `verify`, one `agent --loop` iteration (every diff declined), `hook install/uninstall` and `memory show/verify` | Any command exits with an unexpected code or produces the wrong output |
+| Packaging | `npm pack --dry-run` | A file outside the allow-list ships, anything that looks like tests, fixtures, reports or secrets ships, or the package exceeds its size budget |
+| Offline | A full `--all --adaptive --offline` scan of the mock server | The report's `egress` field shows any third-party host |
+| Supply chain | `npm audit --omit=dev`; sha512 integrity for every lockfile entry; install scripts in runtime dependencies (via `penthera deps --prod`); every `uses:` in `.github/workflows`, `action.yml` and `docs/examples` | Any vulnerability, missing integrity, runtime install script, typosquat, action not pinned by commit SHA, or workflow without top-level `permissions:` |
+| Versions and docs | The version in `package.json`, the lockfile, the plugin manifests, `SKILL.md` and `CITATION.cff`; a `CHANGELOG.md` section for it; every relative link in `README.md` and `docs/` | Any mismatch or broken link |
+
+Everything runs on this machine against this repo or `127.0.0.1`. The only
+network use is `npm audit` (the npm registry) and, with `--with-docker`,
+pulling the Juice Shop image.
+
+## Options
+
+| Flag | Effect |
+|---|---|
+| `--only bench,versions-docs` | Run some gates (ids: `tests`, `bench`, `self-scan`, `smoke`, `packaging`, `offline`, `supply-chain`, `versions-docs`, `docker`). Prints results and writes nothing. |
+| `--update-baseline` | Rewrite `audit/baseline.json` from this run's self-scan. New entries get a `TODO` reason, which fails the gate until a person writes one. |
+| `--with-docker` | Add the optional heavier targets below. |
+| `--no-write` | Leave `audit/` untouched. |
+
+Command output from each run goes to `audit/logs/` (ignored by git, uploaded
+with the report as the CI artifact).
+
+## Optional targets: Juice Shop and crAPI
+
+`--with-docker` starts [OWASP Juice Shop](https://github.com/juice-shop/juice-shop)
+on `127.0.0.1:3300`, scans it with the benchmark's `juice-shop` target, and
+removes the container. Pin the image for reproducible numbers with
+`JUICE_SHOP_IMAGE=bkimminich/juice-shop@sha256:...`.
+
+[OWASP crAPI](https://github.com/OWASP/crAPI) needs its own Docker Compose
+stack, so the audit scans it only if it is already running at `CRAPI_URL`
+(default `http://127.0.0.1:8888`). Start it with the project's compose file
+first.
+
+Both are skipped by default. Neither has labelled ground truth yet, so the
+report lists their finding counts and shows precision and recall as
+"unlabelled" until they are labelled in `bench/ground-truth.json` (see
+[bench/README.md](../bench/README.md#optional-targets)).
+
+## When a gate fails
+
+- **Tests, smoke, offline, packaging, supply chain, versions:** fix the cause.
+  These describe what Penthera promises its users.
+- **Benchmark:** if the change is intended (a new rule that trades a little
+  precision for recall, a relabelled target), run `npm run bench`, commit the
+  new `bench/RESULTS.md`, and say why in the PR.
+- **Self-scan:** fix the finding. If it is a deliberate fixture, run
+  `--update-baseline` and replace the `TODO` with the reason, so the
+  acceptance is reviewed like any other change.
+
+Thresholds (the 0.02 benchmark drop, the package size budget, the allow-list)
+live at the top of [`scripts/audit/run.mjs`](../scripts/audit/run.mjs).
+Change them in their own PR, never to make a release pass.
+
+## The report
+
+`audit/REPORT.md` has a pass/fail table with the numbers behind each gate,
+the changes since the previous report (read from a data block at the end of
+the previous file), and per-gate details. Commit it with each release so the
+history of the gate lives in git.

package/docs/marketing.md

@@ -0,0 +1,151 @@
+# Marketing automation
+
+Penthera is maintained by one person with no budget, so the routine parts of
+getting the word out run by themselves. The rule is simple: **automation drafts
+and collects, a person posts.**
+
+- No social-media API tokens and no auto-posting. Every post is copied and
+  pasted by a person.
+- No analytics, tracking pixels or telemetry. The numbers come from public
+  pages and APIs that anyone can read.
+- Every workflow is SHA-pinned and has least-privilege permissions. Workflows
+  that write only open issues (`issues: write`). Only the demo-media workflow
+  pushes, and only to a `media/*` branch for a PR.
+- Nothing can embarrass the project without a person in the loop: drafts land
+  in issues, job summaries, a collapsed release section or a PR.
+
+## What runs
+
+| Automation | When | Output | Workflow / script |
+|------------|------|--------|-------------------|
+| Release post drafts | Every `v*` tag | LinkedIn (~600 chars) and X/Bluesky (≤280) drafts in the job summary and under "Share this release" in the GitHub Release (the read-only publish job drafts; the release job, which has no checkout, only attaches them) | `publish.yml` → `scripts/marketing/release-post.mjs` |
+| Incident radar | Daily 06:00 UTC | One issue per new malware advisory for a popular npm package (max 5 per run); every other new advisory as a comment on one standing batch issue | `incident-radar.yml` → `scripts/marketing/incident-radar.mjs` |
+| Product-led footer | Every report | One line at the end of Markdown reports, audience reports, the PR comment and the evidence bundle README | `src/report/footer.js` |
+| Demo media | Every published release, on demand | A PR with re-rendered GIFs from `assets/tapes/*.tape` | `demo-media.yml` |
+| Monthly stats | 1st of the month, 07:00 UTC | Issue "Penthera this month: <Month YYYY>" with a table, month-over-month changes and a draft post | `monthly-stats.yml` → `scripts/marketing/monthly-stats.mjs` |
+| Contributor flywheel | When an issue closes | If fewer than 3 `good first issue` issues are open: one reminder issue listing `TODO(good-first-issue)` markers | `contributor-flywheel.yml` → `scripts/marketing/contributor-flywheel.mjs` |
+
+### Release post drafts
+
+Built from the CHANGELOG section for the tag: the first sentence of the
+summary paragraph, then three bullets (bold-titled entries first, Added before
+Fixed), then the npm and GitHub release links. The X/Bluesky post is counted
+the way Bluesky counts (every character), which also fits X. Run it locally:
+
+```bash
+node scripts/marketing/release-post.mjs --tag v1.4.0
+```
+
+The npm release is staged, not live, until a maintainer approves it. Post after
+approving.
+
+### Incident radar
+
+Reads `/advisories?type=malware&ecosystem=npm` and `ecosystem=pip` from the
+public GitHub Advisory Database, published in the last 48 hours. About 20
+malware advisories appear every day and most are typosquats nobody installs,
+so by default only advisories for packages in `lib/deps/popular-packages.json`
+get their own issue (with the checklist and a draft "check if you're affected
+with one command" post). The rest go into one standing issue, "Incident radar:
+other new malware advisories", one comment per run. Set `mode: all` on a manual
+run to open one issue per advisory instead (still at most 5).
+
+State is the issues themselves: an advisory counts as seen when its GHSA id is
+in an `incident-radar` issue or a radar batch comment from the look-back
+window. There is no state file or branch.
+
+Each issue's checklist: add the IOCs to a rule pack in `lib/rules/` (or the
+deps rules until rule packs exist), verify `penthera deps` flags a fixture
+lockfile with the package, then post. Do not post before detection is
+verified.
+
+### Product-led footer
+
+Human-readable Markdown ends with:
+
+> Checked by Penthera, open-source security for the apps and AI systems you ship · https://github.com/danoszz/penthera
+
+It is never added to SARIF or JSON. Users turn it off with `--no-footer` (CLI)
+or `footer: "false"` (GitHub Action).
+
+### Demo media
+
+Tapes live in `assets/tapes/` (see its README). The workflow installs
+[VHS](https://github.com/charmbracelet/vhs) with `charmbracelet/vhs-action`,
+renders every tape, uploads the GIFs as a workflow artifact and, unless it is a
+dry run, opens a PR from a `media/*` branch. It needs **Settings → Actions →
+General → Allow GitHub Actions to create and approve pull requests**. PRs
+opened by `GITHUB_TOKEN` do not trigger CI; close and reopen the PR to run it.
+
+### Monthly stats
+
+Public sources only:
+
+- npm downloads for the calendar month (`api.npmjs.org`);
+- stars and forks at run time and PRs merged that month (GitHub API);
+- installs from the public skills.sh skill page;
+- dependent repositories from GitHub's dependents page.
+
+Each page is parsed strictly: if the markup changed, the number shows as
+`n/a`, never a guess. The issue keeps its numbers in a hidden JSON comment,
+and next month's issue reads them back for the change column.
+
+### Contributor flywheel
+
+Write `TODO(good-first-issue): <what to do>` in a comment next to a small,
+well-scoped change. When the open `good first issue` count drops below 3, the
+reminder issue lists these markers with links. Turn one or two into issues,
+then close the reminder. Closing the reminder itself never triggers a new one.
+
+## Dry runs
+
+Every scheduled workflow has a `workflow_dispatch` trigger whose `dry-run`
+input defaults to **on**: it prints what it would open to the job summary and
+writes nothing.
+
+| Workflow | Dry run |
+|----------|---------|
+| Incident radar | Actions → Incident radar → Run workflow (`dry-run` checked; optional `mode`, `since-hours`) |
+| Monthly stats | Actions → Monthly stats → Run workflow (`dry-run` checked; optional `month`, e.g. `2026-09`) |
+| Contributor flywheel | Actions → Contributor flywheel → Run workflow (`dry-run` checked) |
+| Demo media | Actions → Demo media → Run workflow (`dry-run` checked: GIFs as an artifact, no PR) |
+| Release posts | `node scripts/marketing/release-post.mjs --tag vX.Y.Z` locally |
+
+From a terminal with the GitHub CLI:
+
+```bash
+gh workflow run incident-radar.yml -f dry-run=true
+```
+
+The scripts also run locally with `--dry-run` (they use your `gh` login for
+reads only):
+
+```bash
+node scripts/marketing/incident-radar.mjs --repo danoszz/penthera --dry-run
+```
+
+## Turning things off
+
+- **One workflow:** Actions → the workflow → "…" → Disable workflow. Or delete
+  its file.
+- **Release drafts:** remove the "Draft release posts" and "Keep the drafts" steps (publish job) and the two share steps (release job) from `publish.yml`.
+- **Footer, for one run:** `--no-footer` or `footer: "false"` in the Action.
+  To drop it for everyone, make `footerLines()` in `src/report/footer.js`
+  return `[]`.
+- **Labels** (`incident-radar`, `monthly-stats`, `contributor-flywheel`) are
+  created on the first real run and can be deleted afterwards.
+
+## The weekly 30-minute routine
+
+1. **Incident radar (10 min).** Open the `incident-radar` issues. For a
+   popular package: add the IOCs, check `penthera deps` flags a fixture, post
+   the draft (LinkedIn, X, Bluesky), close the issue. Skim the batch issue for
+   names you recognise, then close it if it is long.
+2. **A clip (5 min).** If a demo-media PR is open, watch the GIFs, merge, and
+   post the best one as a short clip (Instagram, LinkedIn, X).
+3. **Contributors (5 min).** If the flywheel reminder is open, turn one or two
+   markers into `good first issue` issues. Reply to new contributors.
+4. **Release (5 min, when there is one).** Approve the staged npm package, then
+   copy the "Share this release" drafts from the GitHub Release, edit, post.
+5. **Monthly (5 min, first week).** Fill in "what shipped" in the stats issue,
+   post it, close it.

package/docs/plan.md

@@ -27,9 +27,10 @@ these three moments is out of scope.
 
 | Release | Theme | Done when |
 |---------|-------|-----------|
-| v1.5.0 | AI apps and compliance | Pre-commit hook, license policy, CRA helper, AI-BOM, signed rule packs, Python `deps`, dashboard, internal audit all merged and passing the audit |
-| v1.6.0 | Before you deploy | `penthera ship` and preview-deployment scanning work on a real Vercel and Netlify project |
-| v1.7.0 | After you ship | `penthera watch` runs weekly on three real production apps for a month without a false alarm anyone complained about |
+| v1.5.0 | AI apps and compliance | Tagged with the pre-commit hook, license policy, CRA helper and AI-BOM; held back from npm and shipped inside 1.6.0 |
+| v1.6.0 | Hardening and the rest of AI apps | Released with the 360 security review fixes, Python `deps`, the internal audit gate and the dashboard. Signed rule packs follow once the maintainer's key is set up |
+| v1.7.0 | Before you deploy | `penthera ship` and preview-deployment scanning work on a real Vercel and Netlify project |
+| v1.8.0 | After you ship | `penthera watch` runs weekly on three real production apps for a month without a false alarm anyone complained about |
 | v2.0.0 | Stable | Public interfaces frozen (CLI flags, JSON report schema, policy file, rule-pack format), documented, and covered by compatibility tests |
 
 ## What "perfect" means, concretely

package/docs/privacy.md

@@ -0,0 +1,38 @@
+# Privacy and network use
+
+Penthera has no telemetry. It does not collect, store, or transmit any usage data, analytics, or personal information to the author or any third party. It does not phone home.
+
+- **Scan traffic goes to the target you specify.** Auth tokens passed via `--auth-bearer`, `--auth-cookie`, or `PENTHERA_*` env vars are sent only to that target.
+- **Every request identifies itself** as `penthera/<version> (+https://github.com/danoszz/penthera)`, so a target's operator can tell where the traffic comes from. Override it with `--user-agent`.
+- **Reports stay local.** Output is written to `reports/` (gitignored) on your machine.
+- **Every scan lists the third-party hosts it contacted** besides the target, in the terminal summary and in the report's "Network egress" section.
+
+Without `--offline`, a scan may contact these third parties:
+
+| Host | When | What it learns |
+|---|---|---|
+| `raw.githubusercontent.com`, `cdn.jsdelivr.net` | Retire.js check (standard and deep profiles) | That someone downloaded the public database. Nothing about your target. |
+| `crt.sh`, `web.archive.org`, `otx.alienvault.com` | `--recon` only | The target domain. |
+| CDN hosts serving your page's `<script src>` | Retire.js check, when a script's version can only be read from its contents | That someone fetched that public script. |
+
+### Fully local: `--offline`
+
+```bash
+penthera http://localhost:3000 --offline
+```
+
+With `--offline`, the HTTP client refuses every host except the scan target. A redirect may only move to a host on the target's registrable domain (`example.com` to `www.example.com`). In practice:
+
+- **Recon is skipped.** No queries go to crt.sh, the Wayback Machine or OTX.
+- **The Retire.js database comes from the snapshot vendored in the package** (`lib/data/retire-jsrepository.json.gz`), refreshed at each release by `scripts/refresh-retire-db.mjs`. The source URL, fetch date and SHA-256 sit next to it in `retire-jsrepository.meta.json`, so you can check it against upstream. Online scans fall back to the snapshot too when the live download fails.
+- **Third-party scripts are not fetched.** A refused request is listed in the report as an inconclusive probe, not passed over silently.
+- **`--suppliers` is refused**, because it rates third-party domains.
+- **DNS:** reaching a remote target needs DNS. For non-local targets, the email-authentication check also looks up the target domain's SPF/DMARC/MX records through your system resolver. A `localhost` or IP target needs no DNS at all.
+
+Penthera never fetches rules or code at runtime: templates, wordlists and the vulnerability database ship in the package.
+
+### Inconclusive probes
+
+When a probe's requests time out, fail, or are refused by `--offline`, the scan records `{ probe, url, message }` in `result.errors`. The terminal summary shows "N probes inconclusive", and the Markdown report lists each one. A probe that could not run is not a clean result.
+
+You are responsible for ensuring you are authorized to scan any target. See [Ethical use](../README.md#ethical-use--authorization).

package/docs/references.bib

@@ -537,3 +537,13 @@
   urldate      = {2026-10-19},
   note         = {standards}
 }
+
+@misc{spdxlicenselist,
+  shorthand    = {SPDX License List},
+  author       = {{SPDX Workgroup, The Linux Foundation}},
+  title        = {{SPDX} License List},
+  howpublished = {Standardized short identifiers for open source licenses, used by package manifests and SBOMs},
+  url          = {https://spdx.org/licenses/},
+  urldate      = {2026-10-19},
+  note         = {standards}
+}

package/docs/references.md

@@ -75,3 +75,4 @@ Every entry was checked against the publisher or standards body (Crossref DOI me
 - `oasis2023sarif`: Fanning, Michael C.; Golding, Laurence J. (2023). *Static Analysis Results Interchange Format (SARIF) Version 2.1.0 Plus Errata 01*. OASIS Standard incorporating Approved Errata, 28 August 2023. <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html>
 - `eu2022nis2`: European Parliament; Council of the European Union (2022). *Directive (EU) 2022/2555 of the European Parliament and of the Council of 14 December 2022 on measures for a high common level of cybersecurity across the Union, amending Regulation (EU) No 910/2014 and Directive (EU) 2018/1972, and repealing Directive (EU) 2016/1148 (NIS 2 Directive)*. Official Journal of the European Union, L 333, 27.12.2022, p. 80. <https://eur-lex.europa.eu/eli/dir/2022/2555/oj>
 - `mitrecwe`: The MITRE Corporation. *CWE: Common Weakness Enumeration*. Community-developed list of software and hardware weakness types, sponsored by CISA. <https://cwe.mitre.org/>
+- `spdxlicenselist`: SPDX Workgroup, The Linux Foundation. *SPDX License List*. Standardized short identifiers for open source licenses, used by package manifests and SBOMs. <https://spdx.org/licenses/>

package/docs/research/socket-positioning-notes.md

@@ -0,0 +1,183 @@
+# How Socket positions itself: notes for Penthera's docs
+
+*Read on 2026-10-19. Everything below is paraphrased; the few quoted words are
+marked. Socket's pages change often, so treat numbers as a snapshot.*
+
+[Socket](https://socket.dev) is a well-funded supply-chain security company and
+one of the clearest communicators in the field. These notes look at how it
+explains itself, so Penthera can learn from the craft without copying the claims
+or picking a fight. Penthera is a complement to Socket, not a rival: Socket
+watches the registries from the cloud; Penthera checks your app and your machine
+offline.
+
+## 1. The headline promise
+
+- The hero line is about securing software at "AI speed", with a sub-line that
+  promises to stop malicious packages before they reach your code
+  ([home](https://socket.dev/)). The tab title frames it as blocking zero-day
+  supply-chain attacks.
+- The core argument is one contrast, repeated on nearly every page: a CVE
+  database lists accidental vulnerabilities after disclosure, while a malicious
+  package is intentional and has to be stopped before install. Socket claims the
+  second half that CVE scanners miss
+  ([features](https://socket.dev/features),
+  [supply-chain attack prevention](https://socket.dev/use-case/supply-chain-attack-prevention)).
+- AI is the urgency: coding agents pull in dependencies faster than people can
+  review them, so the attack surface grows
+  ([features](https://socket.dev/features), [Series C post](https://socket.dev/blog/series-c)).
+- A speed claim backs the promise: malicious packages flagged within minutes of
+  publication ([home](https://socket.dev/)).
+
+**Takeaway.** One sentence of promise, one contrast that explains why existing
+tools are not enough, and one reason it matters now. Penthera's equivalent: one
+promise (check, vet, keep watching, on your machine), one contrast (rules you can
+read versus a verdict from a service), and the same "now" (AI writes the code and
+picks the packages).
+
+## 2. Who they sell to
+
+- **Buyers are security leaders.** The case-study quotes come from a CISO
+  (Anthropic), a head of security (Vercel), senior security engineers (MetaMask,
+  Drata) ([customers](https://socket.dev/customers)).
+- **Developers are the way in.** The free GitHub app, the CLI and the `sfw`
+  firewall are the self-serve entry points, and comparison pages carry a wall of
+  developer tweets ([vs Snyk](https://socket.dev/compare/socket-vs-snyk)).
+- **AI-native companies** are named prominently: Anthropic, Cursor, Replit,
+  Vercel and others ([Series C post](https://socket.dev/blog/series-c)).
+- **Credibility from the team**: the founders present themselves as open-source
+  maintainers whose packages are downloaded at very large scale
+  ([FAQ](https://socket.dev/faq)).
+- **Pricing** is per developer seat ([pricing](https://socket.dev/pricing)):
+  a free plan for one seat with 1,000 scans a month and a lot included (GitHub
+  app, AI analysis, MCP server, install firewall); Team at $25 a seat a month
+  with a 5-seat minimum (adds reachability); Business at $50 with a 20-seat
+  minimum (adds SBOM, SSO, AI-model and Actions scanning); Enterprise on quote
+  (adds self-hosting options, other SCMs, and SAST, secrets and container scanning
+  under "Socket Basics").
+- **Open source**: public OSI-licensed projects can get the Business plan free
+  as of August 2026
+  ([announcement](https://socket.dev/blog/free-business-plan-upgrades-for-open-source)).
+  The pricing page still mentions the older free Team offer.
+
+**Takeaway.** Socket speaks to the person who signs off and lets the developer
+install it. Penthera has no buyer. Its audiences are people doing the work with
+no security team behind them: a founder before launch, a team adopting coding
+agents, a maintainer, a small EU company, an agency. So Penthera's use-case pages
+are organised by situation, not by job title.
+
+## 3. How use cases and comparisons are structured
+
+**Comparison pages** ([Snyk](https://socket.dev/compare/socket-vs-snyk),
+[Dependabot](https://socket.dev/compare/socket-vs-dependabot),
+[Semgrep](https://socket.dev/compare/socket-vs-semgrep)) share one template:
+
+1. "Socket vs X" with a benefit subtitle.
+2. Two paragraphs placing the competitor in the "known vulnerabilities only" box.
+3. Install and contact-sales buttons.
+4. A feature table of 8 or 9 rows with checks and dashes.
+5. A second row of buttons, then a tweet wall, then a footer call to action.
+
+They concede little. Snyk gets checks for known vulnerabilities, licence
+enforcement and an API; Dependabot only for known vulnerabilities. Categories
+where the competitor is stronger (SAST depth, containers, IaC, DAST) do not
+appear. There are no prices, benchmarks or third-party sources in the tables.
+
+**Use-case pages** ([open source](https://socket.dev/use-case/open-source-security),
+[SCA](https://socket.dev/use-case/sca),
+[supply-chain attack prevention](https://socket.dev/use-case/supply-chain-attack-prevention))
+mix an SEO definition ("what is SCA"), a problem framing, a feature checklist and
+a live feed of recently blocked packages. The feed is the most persuasive
+element: it shows the product working today.
+
+There is no standalone "Why Socket" page; it is a menu that groups the case
+studies and comparisons. The closest page is
+[features](https://socket.dev/features).
+
+**Takeaway.** Copy the shape (one page per audience, one per alternative, a
+table that is quick to scan), not the tone. Penthera's comparison pages say
+"use together", name where the other tool goes further, link every claim to the
+vendor's own docs, and carry a last-checked date. That honesty is the
+differentiator Penthera can afford and a funded vendor often cannot.
+
+## 4. How they use proof
+
+- **Big numbers** on the home page: about 11.6 million commits secured a month, 1.5 million repositories, 27,000
+  organisations, 10,000 attacks blocked a week ([home](https://socket.dev/)).
+  The same metric differs across pages (risk signals: 70, 80 or 85; unique threat
+  detections: 26,000 on [features](https://socket.dev/features) versus 300,000 on
+  the home page).
+- **Logos and case studies.** The strongest one, Anthropic, gives an outcome:
+  most dependency reviews automated and hours saved each week per engineer
+  ([Anthropic](https://socket.dev/case-study/anthropic)). Vercel and Drata
+  describe workflow and hygiene rather than numbers
+  ([Vercel](https://socket.dev/case-study/vercel), [Drata](https://socket.dev/case-study/drata)).
+  MetaMask's engineer says openly that some false positives are an acceptable
+  price for early warning ([MetaMask](https://socket.dev/case-study/metamask)).
+  The Replit story was not retrievable (HTTP 403); its index card is about
+  reducing false positives.
+- **Funding and badges**: total raised, a $1 billion valuation, SOC 2 Type 2, a
+  Fortune list, and an OpenAI early-access programme
+  ([home](https://socket.dev/), [Series C post](https://socket.dev/blog/series-c)).
+- **Research as proof**: threat write-ups with timestamps showing when the AI
+  scanner flagged an attack, plus downloadable indicators
+  ([Rust crates post](https://socket.dev/blog/popular-rust-crates-compromised)).
+- **No accuracy numbers.** No false-positive rate for malware verdicts is
+  published; false-positive language appears only for reachability cutting CVE
+  noise.
+
+**Takeaway.** Penthera has no logos, no funding and no usage telemetry (by
+design, it has no way to count users). What it can show is what a reader can
+check: benchmark precision and recall with every miss listed, rule and test
+counts generated from the code, a cited methodology, an OpenSSF Scorecard, and
+2FA-approved releases with provenance. That is the "By the numbers" block in the
+README, refreshed by `npm run docs:numbers`.
+
+## 5. Calls to action
+
+- Every page pairs a free self-serve action (install the GitHub app) with a sales
+  action (book a demo or contact sales) ([home](https://socket.dev/), compare and
+  use-case pages).
+- Product pages lead with the install command
+  ([CLI](https://socket.dev/features/cli),
+  [firewall](https://socket.dev/features/firewall)); every blog post ends with a
+  free firewall card.
+- An urgency line: a phone number for teams under active attack.
+
+**Takeaway.** Penthera has no sales step, so its call to action is the command
+itself. The README opens with three `npx` commands that each take under a
+minute and need no account.
+
+## 6. What they leave unsaid
+
+| Topic | What Socket's pages say | Room for Penthera |
+|---|---|---|
+| Offline use | No offline or air-gapped mode documented. Even self-hosted firewall modes check packages against Socket's API ([firewall free](https://docs.socket.dev/docs/socket-firewall-free), [pricing](https://socket.dev/pricing)). Only manifests and lockfiles are sent, not source ([FAQ](https://socket.dev/faq)) | Everything runs locally; `--offline` limits traffic to the named target |
+| Deterministic verdicts | Static analysis first, then an LLM stage, then human review before a package is labelled known malware ([AI alert](https://socket.dev/alerts/gptMalware)). No claim of reproducible results | Same input, same output, with the rule and `file:line` for each finding |
+| App and runtime security | No DAST or live-URL testing; first-party SAST and secrets only on Enterprise | URL and repo scans, fix recipes, verification |
+| AI tooling | Covers it as packages: an MCP server for package lookups ([MCP guide](https://docs.socket.dev/docs/guide-to-socket-mcp)), firewall ecosystems that include agent skills and models ([firewall](https://socket.dev/features/firewall)), research on malicious MCP servers ([labs](https://socket.dev/labs)). Nothing found that audits a repo's own agent config | `penthera agents`: CLAUDE.md, `.mcp.json`, hooks, permissions, plugins, rule files |
+| EU compliance | SBOM export (CycloneDX, SPDX, OpenVEX) on Business and up; no NIS2 or CRA page found; compliance messaging is SOC 2 and Vanta-style integrations | NIS2 readiness, CRA Article 14 drafts, SBOM and AI-BOM, signable evidence, free |
+
+Two cautions. Socket does cover parts of AI tooling, and says so; Penthera's docs
+should not claim it does not. And the AI-versus-rules point should be made
+calmly: Socket's AI scanner once flagged Penthera itself as malware because the
+repository contains real test payloads. That is a fair example of the trade-off,
+not a gotcha. AI stages catch novel attacks that no rule anticipated; rules
+explain themselves and do not misread intent. Running both is reasonable.
+
+## 7. What Penthera's docs take from this
+
+1. **A three-command "Try it in 60 seconds" block** near the top of the README,
+   as the call to action.
+2. **Use-case pages by situation**, each with the problem, what to run, real
+   example output, and what Penthera does not do
+   ([docs/use-cases/](../use-cases/README.md)).
+3. **Comparison pages framed as "use together"**, with factual tables, where the
+   other tool goes further, links to the vendor's docs, and a last-checked date
+   ([docs/compare/](../compare/README.md)).
+4. **Proof without logos**: a short "By the numbers" block in the README, every
+   number checkable and refreshable.
+5. **A shorter README** that points to per-command pages instead of carrying
+   every flag.
+
+Things deliberately not copied: inflated or inconsistent numbers, tweet walls,
+competitor tables that only list the author's strengths, and urgency language.

package/docs/use-cases/README.md

@@ -0,0 +1,14 @@
+# Use cases
+
+Each page starts from a situation, not a feature: the problem, what to run, what
+the output looks like, and what Penthera does not do for you.
+
+| You are | Page |
+|---|---|
+| A solo founder or vibecoder about to launch | [Before launch](solo-founder.md) |
+| A team adopting Claude Code or Cursor | [The AI-tooling supply chain](ai-coding-teams.md) |
+| An open-source maintainer | [For maintainers](open-source-maintainers.md) |
+| An EU SME with NIS2 or CRA duties | [Evidence for NIS2 and the CRA](eu-sme-compliance.md) |
+| An agency shipping client apps | [A repeatable handover check](agencies.md) |
+
+Using another security tool already? See [how Penthera fits with it](../compare/README.md).

package/docs/use-cases/agencies.md

@@ -0,0 +1,71 @@
+# A repeatable handover check: for agencies shipping client apps
+
+## The problem
+
+An agency ships many similar apps for clients who assume security was handled.
+Each project has a different team, a different deadline and a launch date that
+does not move. A security review by a person for every launch is too expensive,
+and "we followed best practice" does not survive a client's procurement
+questionnaire or an incident.
+
+## What to run
+
+The same three steps on every project, in CI or before handover:
+
+```bash
+npx penthera https://preview.client.example --repo . --profile standard \
+  --sarif reports/scan.sarif -o reports/scan.json
+npx penthera deps --license-policy permissive     # dependency capabilities and licences
+npx penthera agents                               # the agent config left in the repo
+```
+
+At handover, give the client a report written for them and a bundle they can
+keep:
+
+```bash
+npx penthera https://client.example --repo . --audience owner > security-summary.md
+npx penthera https://client.example --repo . --audience auditor \
+  --evidence handover/2026-10-19 --sign-key ~/.ssh/agency_ed25519
+```
+
+Pin the Penthera version in CI so every project is checked by the same rules,
+and use `--baseline` to show only what is new since the last scan.
+
+## What you get
+
+The owner report is in plain language. From Penthera's own mock target:
+
+```markdown
+# Security summary
+
+## In short
+
+Penthera checked http://localhost:8765 and found **2 serious problems** to fix
+this week, 5 moderate, 2 minor, 2 notes. The serious ones are things an attacker
+could use today.
+
+## What to do first
+
+1. **Harden authentication and access control** (involved, a developer can do this). ...
+2. **Remove the exposed file or interface from production** (quick, a developer can do this). ...
+3. **Add a Content-Security-Policy header** (moderate, a developer can do this). ...
+```
+
+The auditor version covers scope and method, every finding with its evidence and
+confidence, the hosts contacted, and the probes that could not run. The evidence bundle hashes every file in a
+signed manifest, so the client can check later that nothing was edited.
+`--report-template` puts the same data into your own Markdown template.
+[More on reports and evidence](../evidence.md).
+
+## What it does not do
+
+- It does not replace a penetration test where a contract or a regulator asks for
+  one. It makes that test cheaper, because the routine findings are already gone.
+- It only scans what you point it at, with the client's permission. Get the scope
+  in writing.
+- Fix recipes cover common JavaScript and TypeScript frameworks. Other stacks get
+  findings and guidance, not diffs.
+- It does not monitor client production after handover yet. That is on the
+  [roadmap](../../ROADMAP.md).
+
+[All use cases](README.md) · [Back to the README](../../README.md)