penthera 1.7.0 → 1.8.0

package/docs/references.md

@@ -1,119 +0,0 @@
-# References
-
-The research and standards that Penthera's [methodology](METHODOLOGY.md) and per-finding sources cite, in APA 7th edition style, grouped by topic and sorted alphabetically by first author within each group. The BibTeX source is [references.bib](references.bib); this page is generated from it by `node scripts/build-references.mjs`, and a test fails if the two drift or if a citation in METHODOLOGY.md does not resolve to an entry here.
-
-Every entry was checked against the publisher or standards body (Crossref DOI metadata, USENIX, NDSS, arXiv, the RFC Editor, OWASP, MITRE, OASIS, the EU Publications Office) on 2026-10-19. Entries that could not be verified were left out, and so were fields (pages, volume, issue, editors) that the publisher's metadata does not record. Each entry has an anchor named after its BibTeX key, for example [`#bau2010state`](#bau2010state), which is also the key reports and SARIF use.
-
-## Black-box scanning and benchmarking
-
-<a id="antunes2010benchmarking"></a>Antunes, N., & Vieira, M. (2010). Benchmarking vulnerability detection tools for web services. In *2010 IEEE International Conference on Web Services (ICWS)* (pp. 203–210). IEEE. <https://doi.org/10.1109/ICWS.2010.76>
-
-<a id="antunes2015assessing"></a>Antunes, N., & Vieira, M. (2015). Assessing and comparing vulnerability detection tools for web services: Benchmarking approach and examples. *IEEE Transactions on Services Computing*, *8*(2), 269–283. <https://doi.org/10.1109/TSC.2014.2310221>
-
-<a id="bau2010state"></a>Bau, J., Bursztein, E., Gupta, D., & Mitchell, J. (2010). State of the art: Automated black-box web application vulnerability testing. In *2010 IEEE Symposium on Security and Privacy* (pp. 332–345). IEEE. <https://doi.org/10.1109/SP.2010.27>
-
-<a id="doupe2010johnny"></a>Doupé, A., Cova, M., & Vigna, G. (2010). Why Johnny can't pentest: An analysis of black-box web vulnerability scanners. In C. Kreibich & M. Jahnke (Eds.), *Detection of Intrusions and Malware, and Vulnerability Assessment (DIMVA 2010)* (pp. 111–131). Springer. <https://doi.org/10.1007/978-3-642-14215-4_7>
-
-<a id="owaspbenchmark"></a>OWASP Foundation. (n.d.-a). *OWASP Benchmark project* (Version 1.2). Retrieved October 19, 2026, from <https://owasp.org/www-project-benchmark/>
-
-## Security design principles
-
-<a id="saltzer1975protection"></a>Saltzer, J. H., & Schroeder, M. D. (1975). The protection of information in computer systems. *Proceedings of the IEEE*, *63*(9), 1278–1308. <https://doi.org/10.1109/PROC.1975.9939>
-
-## Threat modeling
-
-<a id="kohnfelder1999threats"></a>Kohnfelder, L., & Garg, P. (1999). *The threats to our products* [Internal publication]. Microsoft. Retrieved October 19, 2026, from <https://shostack.org/files/microsoft/The-Threats-To-Our-Products.docx>
-
-<a id="shostack2014threat"></a>Shostack, A. (2014). *Threat modeling: Designing for security*. Wiley. <https://www.wiley-vch.de/de/fachgebiete/computer-und-informatik/threat-modeling-978-1-118-80999-0>
-
-## Software supply chain
-
-<a id="ladisa2023sok"></a>Ladisa, P., Plate, H., Martinez, M., & Barais, O. (2023). SoK: Taxonomy of attacks on open-source software supply chains. In *2023 IEEE Symposium on Security and Privacy (SP)* (pp. 1509–1526). IEEE. <https://doi.org/10.1109/SP46215.2023.10179304>
-
-<a id="lauinger2017thou"></a>Lauinger, T., Chaabane, A., Arshad, S., Robertson, W., Wilson, C., & Kirda, E. (2017). Thou shalt not depend on me: Analysing the use of outdated JavaScript libraries on the web. In *Proceedings 2017 Network and Distributed System Security Symposium*. Internet Society. <https://doi.org/10.14722/ndss.2017.23414>
-
-<a id="ohm2020backstabber"></a>Ohm, M., Plate, H., Sykosch, A., & Meier, M. (2020). Backstabber's knife collection: A review of open source software supply chain attacks. In C. Maurice, L. Bilge, G. Stringhini, & N. Neves (Eds.), *Detection of Intrusions and Malware, and Vulnerability Assessment (DIMVA 2020)* (pp. 23–43). Springer. <https://doi.org/10.1007/978-3-030-52683-2_2>
-
-<a id="samuel2010survivable"></a>Samuel, J., Mathewson, N., Cappos, J., & Dingledine, R. (2010). Survivable key compromise in software update systems. In *Proceedings of the 17th ACM Conference on Computer and Communications Security (CCS '10)* (pp. 61–72). ACM. <https://doi.org/10.1145/1866307.1866315>
-
-<a id="thompson1984reflections"></a>Thompson, K. (1984). Reflections on trusting trust. *Communications of the ACM*, *27*(8), 761–763. <https://doi.org/10.1145/358198.358210>
-
-<a id="torresarias2019intoto"></a>Torres-Arias, S., Afzali, H., Kuppusamy, T. K., Curtmola, R., & Cappos, J. (2019). in-toto: Providing farm-to-table guarantees for bits and bytes. In *28th USENIX Security Symposium (USENIX Security 19)* (pp. 1393–1410). USENIX Association. <https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias>
-
-<a id="zimmermann2019small"></a>Zimmermann, M., Staicu, C.-A., Tenny, C., & Pradel, M. (2019). Small world with high risks: A study of security threats in the npm ecosystem. In *28th USENIX Security Symposium (USENIX Security 19)* (pp. 995–1010). USENIX Association. <https://www.usenix.org/conference/usenixsecurity19/presentation/zimmerman>
-
-## Secret leakage
-
-<a id="basak2023secretbench"></a>Basak, S. K., Neil, L., Reaves, B., & Williams, L. (2023). SecretBench: A dataset of software secrets. In *2023 IEEE/ACM 20th International Conference on Mining Software Repositories (MSR)* (pp. 347–351). IEEE. <https://doi.org/10.1109/MSR59073.2023.00053>
-
-<a id="meli2019bad"></a>Meli, M., McNiece, M. R., & Reaves, B. (2019). How bad can it Git? Characterizing secret leakage in public GitHub repositories. In *Proceedings 2019 Network and Distributed System Security Symposium*. Internet Society. <https://doi.org/10.14722/ndss.2019.23418>
-
-## Web application security
-
-<a id="barth2008robust"></a>Barth, A., Jackson, C., & Mitchell, J. C. (2008). Robust defenses for cross-site request forgery. In *Proceedings of the 15th ACM Conference on Computer and Communications Security (CCS '08)* (pp. 75–88). ACM. <https://doi.org/10.1145/1455770.1455782>
-
-<a id="chen2018cors"></a>Chen, J., Jiang, J., Duan, H., Wan, T., Chen, S., Paxson, V., & Yang, M. (2018). We still don't have secure cross-domain requests: An empirical study of CORS. In *27th USENIX Security Symposium (USENIX Security 18)* (pp. 1079–1093). USENIX Association. <https://www.usenix.org/conference/usenixsecurity18/presentation/chen-jianjun>
-
-<a id="crosby2009opportunities"></a>Crosby, S. A., Wallach, D. S., & Riedi, R. H. (2009). Opportunities and limits of remote timing attacks. *ACM Transactions on Information and System Security*, *12*(3), 1–29. <https://doi.org/10.1145/1455526.1455530>
-
-<a id="fett2016comprehensive"></a>Fett, D., Küsters, R., & Schmitz, G. (2016). A comprehensive formal security analysis of OAuth 2.0. In *Proceedings of the 2016 ACM SIGSAC Conference on Computer and Communications Security (CCS '16)* (pp. 1204–1215). ACM. <https://doi.org/10.1145/2976749.2978385>
-
-<a id="hodges2012rfc6797"></a>Hodges, J., Jackson, C., & Barth, A. (2012). *HTTP strict transport security (HSTS)* (RFC 6797). RFC Editor. <https://doi.org/10.17487/RFC6797>
-
-<a id="jones2015rfc7519"></a>Jones, M., Bradley, J., & Sakimura, N. (2015). *JSON web token (JWT)* (RFC 7519). RFC Editor. <https://doi.org/10.17487/RFC7519>
-
-<a id="kitterman2014rfc7208"></a>Kitterman, S. (2014). *Sender policy framework (SPF) for authorizing use of domains in email, version 1* (RFC 7208). RFC Editor. <https://doi.org/10.17487/RFC7208>
-
-<a id="kocher1996timing"></a>Kocher, P. C. (1996). Timing attacks on implementations of Diffie-Hellman, RSA, DSS, and other systems. In N. Koblitz (Ed.), *Advances in Cryptology – CRYPTO '96* (pp. 104–113). Springer. <https://doi.org/10.1007/3-540-68697-5_9>
-
-<a id="kucherawy2015rfc7489"></a>Kucherawy, M., & Zwicky, E. (2015). *Domain-based message authentication, reporting, and conformance (DMARC)* (RFC 7489). RFC Editor. <https://doi.org/10.17487/RFC7489>
-
-<a id="lekies2013flows"></a>Lekies, S., Stock, B., & Johns, M. (2013). 25 million flows later: Large-scale detection of DOM-based XSS. In *Proceedings of the 2013 ACM SIGSAC Conference on Computer and Communications Security (CCS '13)* (pp. 1193–1204). ACM. <https://doi.org/10.1145/2508859.2516703>
-
-<a id="lodderstedt2025rfc9700"></a>Lodderstedt, T., Bradley, J., Labunets, A., & Fett, D. (2025). *Best current practice for OAuth 2.0 security* (RFC 9700, BCP 240). RFC Editor. <https://doi.org/10.17487/RFC9700>
-
-<a id="owaspwstg42"></a>OWASP Foundation. (n.d.-b). *OWASP Web Security Testing Guide, version 4.2*. Retrieved October 19, 2026, from <https://wstg.owasp.org/v4.2/>
-
-<a id="owasp2021top10"></a>OWASP Foundation. (2021). *OWASP Top 10:2021*. Retrieved October 19, 2026, from <https://top10.owasp.org/2021>
-
-<a id="owasp2023api"></a>OWASP Foundation. (2023). *OWASP Top 10 API security risks – 2023*. OWASP API Security Project. Retrieved October 19, 2026, from <https://owasp.org/API-Security/editions/2023/en/0x11-t10/>
-
-<a id="owasp2025top10"></a>OWASP Foundation. (2025c). *OWASP Top 10:2025*. Retrieved October 19, 2026, from <https://top10.owasp.org/2025>
-
-<a id="sakimura2015rfc7636"></a>Sakimura, N., Bradley, J., & Agarwal, N. (2015). *Proof key for code exchange by OAuth public clients* (RFC 7636). RFC Editor. <https://doi.org/10.17487/RFC7636>
-
-<a id="sheffer2020rfc8725"></a>Sheffer, Y., Hardt, D., & Jones, M. (2020). *JSON web token best current practices* (RFC 8725, BCP 225). RFC Editor. <https://doi.org/10.17487/RFC8725>
-
-<a id="stock2014precise"></a>Stock, B., Lekies, S., Mueller, T., Spiegel, P., & Johns, M. (2014). Precise client-side protection against DOM-based cross-site scripting. In *23rd USENIX Security Symposium (USENIX Security 14)* (pp. 655–670). USENIX Association. <https://www.usenix.org/conference/usenixsecurity14/technical-sessions/presentation/stock>
-
-<a id="weichselbaum2016csp"></a>Weichselbaum, L., Spagnuolo, M., Lekies, S., & Janc, A. (2016). CSP is dead, long live CSP! On the insecurity of whitelists and the future of Content Security Policy. In *Proceedings of the 2016 ACM SIGSAC Conference on Computer and Communications Security (CCS '16)* (pp. 1376–1387). ACM. <https://doi.org/10.1145/2976749.2978363>
-
-## LLM and agent security
-
-<a id="greshake2023signed"></a>Greshake, K., Abdelnabi, S., Mishra, S., Endres, C., Holz, T., & Fritz, M. (2023). Not what you've signed up for: Compromising real-world LLM-integrated applications with indirect prompt injection. In *Proceedings of the 16th ACM Workshop on Artificial Intelligence and Security (AISec '23)* (pp. 79–90). ACM. <https://doi.org/10.1145/3605764.3623985>
-
-<a id="liu2023prompt"></a>Liu, Y., Deng, G., Li, Y., Wang, K., Wang, Z., Wang, X., Zhang, T., Liu, Y., Wang, H., Zheng, Y., Zhang, L. Y., & Liu, Y. (2023). *Prompt injection attack against LLM-integrated applications* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.2306.05499>
-
-<a id="mitreatlas"></a>The MITRE Corporation. (n.d.-b). *MITRE ATLAS: Adversarial Threat Landscape for AI Systems*. Retrieved October 19, 2026, from <https://atlas.mitre.org/>
-
-<a id="owasp2024llmtop10"></a>OWASP Foundation. (2024, November 17). *OWASP Top 10 for LLM applications 2025*. OWASP Gen AI Security Project. Retrieved October 19, 2026, from <https://genai.owasp.org/resource/owasp-top-10-for-llm-applications-2025/>
-
-<a id="owasp2025mcptop10"></a>OWASP Foundation. (2025a). *OWASP MCP Top 10* [Beta]. Retrieved October 19, 2026, from <https://owasp.org/www-project-mcp-top-10/>
-
-<a id="owasp2025agentic"></a>OWASP Foundation. (2025b, December 9). *OWASP Top 10 for agentic applications for 2026*. OWASP Gen AI Security Project. Retrieved October 19, 2026, from <https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/>
-
-<a id="perez2022ignore"></a>Perez, F., & Ribeiro, I. (2022). *Ignore previous prompt: Attack techniques for language models* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.2211.09527>
-
-<a id="spracklen2025package"></a>Spracklen, J., Wijewickrama, R., Sakib, A. H. M. N., Maiti, A., Viswanath, B., & Jadliwala, M. (2025). We have a package for you! A comprehensive analysis of package hallucinations by code generating LLMs. In *34th USENIX Security Symposium (USENIX Security 25)* (pp. 3687–3706). USENIX Association. <https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen>
-
-## Standards and regulation
-
-<a id="eu2022nis2"></a>European Parliament and 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. Retrieved October 19, 2026, from <https://eur-lex.europa.eu/eli/dir/2022/2555/oj>
-
-<a id="oasis2023sarif"></a>Fanning, M. C., & Golding, L. J. (2023, August 28). *Static Analysis Results Interchange Format (SARIF) version 2.1.0 plus errata 01* [OASIS Standard incorporating Approved Errata]. OASIS. Retrieved October 19, 2026, from <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html>
-
-<a id="mitrecwe"></a>The MITRE Corporation. (n.d.-a). *CWE: Common Weakness Enumeration*. Retrieved October 19, 2026, from <https://cwe.mitre.org/>
-
-<a id="scarfone2008sp800115"></a>Scarfone, K. A., Souppaya, M. P., Cody, A., & Orebaugh, A. D. (2008). *Technical guide to information security testing and assessment* (NIST Special Publication 800-115). National Institute of Standards and Technology. <https://doi.org/10.6028/NIST.SP.800-115>
-
-<a id="spdxlicenselist"></a>SPDX Workgroup, The Linux Foundation. (n.d.). *SPDX License List*. Retrieved October 19, 2026, from <https://spdx.org/licenses/>

package/docs/release-plan.md

@@ -1,228 +0,0 @@
-# Release plan: v1.2.0 → v1.4.0
-
-The engineering plan behind the [roadmap](../ROADMAP.md): what ships in each
-release, in what order, what each piece depends on, and how we know it is done.
-Dates are targets, not promises. Building is fast; review, real-world testing,
-and the 2FA release approval set the pace.
-
-Written 2026-10-19. **Status:** both milestones shipped together as 1.4.0 on 2026-10-19, a few weeks ahead of the targets below.
-
-## The bet
-
-Two releases that move Penthera from "a good scanner" to a system that competes
-with commercial supply-chain and AppSec platforms on their core value, while
-keeping what they cannot copy: local, deterministic, explainable, no telemetry.
-
-| Commercial platforms sell | Penthera answers with | Release |
-|---------------------------|-----------------------|---------|
-| Dependency capability alerts and upgrade diffs | `penthera deps` and `deps --diff` | v1.3.0 |
-| Skill, extension, and MCP scanning | `penthera agents` and `penthera.lock` | v1.3.0 |
-| PR comments on dependency changes | GitHub Action that comments the capability diff | v1.4.0 |
-| An install firewall | `penthera install`: check before install scripts run | v1.4.0 |
-| Auto-fix PRs | A local scan → fix → verify → learn loop that never pushes | v1.4.0 |
-| Proof that it works | Published methodology, verified citations, a benchmark | v1.3.0 |
-
-## Timeline at a glance
-
-| When | Milestone |
-|------|-----------|
-| Oct 19–20 | v1.2.0 live on npm (2FA approval), old npm token deleted |
-| Oct 20–22 | v1.3.0 PRs merged in order, release staged |
-| Oct 23 | v1.3.0 live, launch write-up published |
-| Oct 23–30 | v1.4.0 wave 1: HTTP client and egress guard, learning store, fix recipes, install firewall |
-| Oct 30–Nov 6 | v1.4.0 wave 2: agent loop, custom reports, PR-comment Action |
-| Nov 6–10 | Release gate: real-app test, benchmark diff, security review |
-| Nov 10 | v1.4.0 live |
-| From Nov 16 | Internal testing audit, landing page (see "Scheduled for later") |
-| December | v1.5.0 (staged on the roadmap) |
-
----
-
-## v1.2.0: finish the release
-
-| Step | Owner | Done when |
-|------|-------|-----------|
-| Approve the staged version on npmjs.com (Staged Packages, 2FA) | Maintainer | `npm view penthera version` is 1.2.0 with provenance |
-| Delete the `NPM_TOKEN` repository secret | Maintainer | Secret gone; publishing is OIDC-only |
-| Decide Dependabot #11 (`setup-node` v6 → v7) | Maintainer + CI | v7 changes how `NODE_AUTH_TOKEN` is handled. With no token left this is likely safe, but merge it only with a dry-run of `publish.yml` (`npm stage publish --dry-run`) on a branch first |
-
-## v1.3.0 "AI toolchain": target Oct 22, live Oct 23
-
-All four pieces are already built or in progress. The work is review and merge
-order, because three of them touch `src/cli.js`, the README, and the CHANGELOG.
-
-**Merge order:**
-
-1. **#12 `penthera agents`.** Offline audit of `.mcp.json`, `~/.claude`,
-   `~/.cursor`, hooks, plugins, skills, and rule files. Includes the
-   hidden-content engine, `penthera.lock`, an A–F grade, and OWASP MCP / Agentic
-   mapping. Rebase on main, review, merge.
-2. **Research and methodology.** `docs/METHODOLOGY.md`, verified
-   `references.bib`, per-finding citations in Markdown and SARIF,
-   `CITATION.cff`, an offline benchmark with precision and recall. Rebase
-   after #12 (both touch the reporters).
-3. **`penthera deps`.** Static capability detection on `node_modules`,
-   `--diff` between lockfiles, typosquat check against a vendored list, and an
-   opt-in `--online` registry check. Rebase after the research PR.
-4. **Funding pack.** Docs only, any order.
-
-**Also in v1.3.0:**
-
-| Item | Why | Size |
-|------|-----|------|
-| Bump to 1.3.0 everywhere, CHANGELOG, tag, approve | Release | S |
-| Launch write-up: an offline audit of popular public skills and MCP servers with `penthera agents` | The post that earns attention. Read-only analysis of public repos, findings reported to authors privately first | M |
-
-**Release gate:** `npm test` green, benchmark numbers in `bench/RESULTS.md` no
-worse than v1.2.0, `penthera agents` and `penthera deps` run cleanly on this
-repo, every citation verified.
-
-## v1.4.0 "Local loop + competitive": target Nov 10
-
-### Wave 1 (parallel, Oct 23–30)
-
-Each workstream owns different files, so they can be built side by side.
-
-**W1. One HTTP client, `--offline` egress guard, User-Agent, inconclusive probes**
-- Every network call goes through `src/utils/http.js`. Today `crawler`,
-  `injections`, `fuzzer`, `templates`, `recon`, `params`, `retirejs`, and
-  `adaptive-probes` each build their own fetch wrapper.
-- `--offline`: the client refuses any host other than the scan target. Recon
-  sources (crt.sh, Wayback, OTX) become explicit opt-ins.
-- Vendor a Retire.js database snapshot, refreshed by a release script, so JS
-  CVE checks work offline.
-- Send `penthera/<version> (+repo url)` as the User-Agent (closes #7).
-- Probe errors are recorded and reported as "inconclusive" instead of passing
-  silently (closes #8).
-- While rewriting `lib/injections.js` and `lib/fuzzer.js`: an honest header,
-  and payload strings moved into a clearly named data file. Socket's AI judge
-  flagged Penthera as malware for containing test payloads; this gives any
-  reviewer the context a snippet lacks. Then ask Socket to review the alert.
-- **Done when:** a test that blocks all egress except the target passes for
-  every profile, and the vendored database matches upstream at release time.
-
-**W2. Local learning store**
-- `~/.penthera/memory/<project-hash>/events.jsonl`: append-only; each event
-  carries the hash of the previous one.
-- Events: scan summary, fix applied (recipe, diff hash), fix verified or
-  failed, false positive suppressed (fingerprint, reason), probe yield per
-  stack.
-- Derived views: recipe success rate per framework, active suppressions,
-  probe ranking. Used only to re-rank and suppress; never executes anything.
-- `penthera memory show | verify | forget`. `verify` detects any edit to the
-  chain.
-- Never read from the scanned repo. A suppression committed to a repo is shown
-  in the report as "suppressed by repo file" so a reviewer sees it.
-- **Done when:** tampering with any line fails `verify`, and suppressions and
-  re-ranking are covered by tests.
-
-**W3. Fix recipes**
-- `lib/fix/`: deterministic codemods that produce a unified diff for the most
-  common findings:
-  - security headers for Next.js, Express (helmet), Fastify, and Hono;
-  - cookie flags;
-  - a CORS allowlist;
-  - a rate-limit stub on auth routes;
-  - moving a hardcoded secret to an environment variable, with "rotate it" as
-    an owner action.
-- Framework detection reuses `lib/whitebox/frameworks.js`.
-- Optional local model adapter (Ollama on localhost, enforced by W1) for
-  findings without a recipe. Its output is labelled "model-suggested,
-  needs-human-review".
-- **Done when:** each recipe has before/after fixtures, and every produced diff
-  applies cleanly and makes its finding disappear on re-scan in the fixture app.
-
-**W4. Install firewall**
-- `penthera install [pkg...]`: resolve the dependency tree with scripts
-  disabled, run the `deps` capability diff against the current lockfile, show
-  what is new (install scripts, network, shell, env), and only then run the
-  real install, either after a prompt or under a policy file
-  (`penthera.policy.json`).
-- **Done when:** a fixture package that gains an install script is stopped
-  before its script runs.
-
-### Wave 2 (Oct 30–Nov 6)
-
-**W5. Agent loop: `penthera agent --loop`** (depends on W1, W2, W3)
-- State machine: scan → triage (ranked by memory) → plan (recipe or model
-  suggestion) → patch on a local branch `penthera/fix-<date>` → verify
-  (re-scan, plus the project's tests if present) → learn → repeat.
-- Stops when nothing fixable remains or `--max-iterations` is reached.
-- Every diff needs approval by default. `--auto low` auto-applies only
-  recipes with a verified success history in memory.
-- Hard guarantees, each with a test:
-  - never pushes, never opens pull requests, never calls a remote;
-  - egress is limited to the target;
-  - the working tree must be clean before it starts.
-- **Done when:** on the fixture app the loop takes the findings to zero in a
-  bounded number of iterations, and a second run is faster because memory
-  re-ranked the recipes.
-
-**W6. Custom reports and evidence bundle** (depends on W2)
-- Audience templates: developer, owner, auditor. User templates via
-  `--report-template file.md` with a small placeholder syntax that evaluates
-  no code.
-- Loop timeline: found → fixed → verified, with time-to-fix from memory.
-- `--evidence <dir>`: reports plus a `manifest.json` with the SHA-256 of
-  every artifact. Optional signing with a local SSH key
-  (`ssh-keygen -Y sign`), no new dependency.
-- **Done when:** an auditor can verify a bundle with one documented command.
-
-**W7. PR-comment GitHub Action** (depends on `deps` from v1.3.0)
-- A composite action published from this repo: on PRs that change a lockfile
-  it runs `penthera deps --diff` against the base branch, posts or updates a
-  single comment ("2 packages gained network access, 1 new install script"),
-  and uploads SARIF.
-- Pinned by SHA in the docs; no secrets needed beyond the default token.
-- **Done when:** it runs on a test PR in this repo and the comment updates in
-  place on a new push.
-
-**W8. Skill and docs**
-- SKILL.md workflow "scan and fix" uses `penthera agent`.
-- `docs/local-loop.md` explains the threat model: why nothing leaves the
-  machine, why the store is hash-chained, why rules never update at runtime.
-
-### Release gate (Nov 6–10)
-
-- Run the loop on one real app the maintainer owns, not only fixtures.
-- Benchmark: precision and recall no worse than v1.3.0.
-- Self-scan with `penthera --repo .`, `penthera agents`, and `penthera deps`:
-  no new high findings.
-- Security review of the diff since v1.3.0, focused on the loop and the
-  firewall (they run commands and write code).
-- Then bump to 1.4.0, tag, approve.
-
-## Risks
-
-| Risk | Mitigation |
-|------|------------|
-| Three PRs conflict in `src/cli.js` | Strict merge order, rebase each after the previous one lands. Consider splitting subcommands into `src/commands/` early in v1.4.0 |
-| Fix recipes break someone's app | Diffs only, approval by default, verify by re-scan and tests, a local branch only |
-| The learning store becomes an attack surface | Home directory only, hash chain, re-rank and suppress only, nothing executable |
-| Install firewall false positives annoy users | Show the capability diff, not a verdict; a policy file to allow known packages |
-| Another AI-judge false positive on new modules | Honest headers, payloads in data files, Socket review requested |
-
----
-
-## Scheduled for later (from Nov 16)
-
-**Internal testing audit.** A standing quality gate run before every release:
-- Penthera against itself and a fixed set of deliberately vulnerable apps
-  (mock server, OWASP Juice Shop, crAPI).
-- `agents` and `deps` against fixture configs.
-- A diff of results against the previous release, with false positives and
-  false negatives triaged into issues.
-- A scheduled weekly run, so drift shows up between releases.
-- The results feed `bench/RESULTS.md`.
-
-**Landing page.** A one-page site: what it does, the 30-second install, the
-trust story (offline, staged releases, methodology, benchmark), and links to
-the docs. Static, hosted on GitHub Pages, with no tracking scripts, in keeping
-with the no-telemetry principle.
-
-## v1.5.0 and beyond
-
-Staged on the [roadmap](../ROADMAP.md): LLM endpoint probes, OWASP LLM
-mapping, the CRA Article 14 helper, the AI-BOM, a pre-commit hook, license
-policy, and signed rule packs. After that: the local dashboard (`penthera ui`)
-and a team pack.

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

@@ -1,183 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,71 +0,0 @@
-# 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)