penthera 1.2.0 → 1.4.0

package/docs/funding/due-diligence-checklist.md

@@ -0,0 +1,79 @@
+# Due diligence checklist
+
+What a funder, sponsor or acquirer is likely to check, what is already in
+place, and what is still open. Checked on 2026-10-19 against the `main` branch
+at commit 156eda6.
+
+Legend: **Done**, **Open** (needs action), **Decide** (maintainer's call).
+
+## 1. Contributions and sign-off (DCO)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Contributors are all known | Done | `git shortlog -sne --all`: 54 commits as "Daan van der Zwaag <daan@devign.it>", 6 as "Daan <daan@devign.it>" (same person, commits made in the GitHub web UI), 1 from dependabot. No outside human contributors. All 8 pull requests so far were opened by the maintainer or dependabot. |
+| DCO sign-off required | Open | The Developer Certificate of Origin 1.1 (https://developercertificate.org/) lets a contributor certify they have the right to submit their code under the project licence. This PR adds a DCO section to CONTRIBUTING.md. Enforcement is not on yet. To enforce, install a DCO check app on the repo, or turn on "Require contributors to sign off on web-based commits" in repository settings. |
+| Past commits | Decide | Past commits are not signed off, but all are by the maintainer, so no outside rights are in question. A short statement in the README or this file is enough; rewriting history is not worth it. |
+| Author identity | Open | Add a `.mailmap` mapping "Daan" to "Daan van der Zwaag" so tools show one author. |
+| AI-assisted commits | Done | 45 commit messages carry `Co-Authored-By: Claude ...` trailers, recording which work was AI-assisted. NLnet's GenAI policy names commit messages as one acceptable way to log this (https://nlnet.nl/foundation/policies/generativeAI/). |
+
+## 2. Licence and copyright
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Project licence | Done | MIT, in `LICENSE`, `package.json` and `.claude-plugin/plugin.json`. |
+| Copyright line | Open | `LICENSE` says "Copyright (c) 2026 daan". Change to the full legal name, or to a company if the maintainer moves the project into one: "Copyright (c) 2026 Daan van der Zwaag". |
+| Runtime dependencies | Done | One: `yaml` (ISC). Dev dependency: `vitest` (MIT). Both permissive. |
+| Third-party data in the source | Open | `lib/params.js` has a parameter wordlist with the comment "Curated from SecLists, Arjun defaults, and CommonCrawl analysis." SecLists is MIT and Arjun is AGPL-3.0 (GitHub licence metadata for both repositories). A list of common parameter names like `id` and `page` is unlikely to carry copyright on its own, but an acquirer's lawyer will ask. Options: document which entries came from where, or rebuild the list from MIT sources only and change the comment. Add a `THIRD_PARTY_NOTICES` file crediting SecLists. |
+| Other inspiration notes | Decide | The same file says "Inspired by: Arjun (6.2k stars), ParamSpider". Inspiration for an algorithm is fine; make sure no code was copied, and keep the note. |
+| Copyright of AI-assisted code | Decide | The US Copyright Office's report "Copyright and Artificial Intelligence, Part 2: Copyrightability" (29 January 2025, https://www.copyright.gov/ai/) addresses protection for AI-generated material. It is a US source; EU and Dutch law may differ. This matters little for an MIT project but may come up in an acquisition. Keep the co-author trailers as the record of human direction and review. Not legal advice. |
+| Assets | Done | `assets/` holds the project's own logo, social image and demo GIF. Confirm the logo was made by the maintainer or under a licence that allows transfer. |
+
+## 3. Name and trademark
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Existing "Penthera" company | Decide | Penthera (penthera.com) is a US company, founded around 2004 to 2005, that sells a video download SDK for mobile apps and describes itself as a SaaS company for streaming providers (https://www.penthera.com/about, https://pitchbook.com/profiles/company/61416-37). Different field (video delivery, not security), but the same word. A search found no registered PENTHERA mark; that search was not exhaustive. |
+| Similar name in security | Decide | Pentera (pentera.io), formerly Pcysys, sells automated security validation and pentesting software (https://en.wikipedia.org/wiki/Pentera). Pentera Security Ltd. has filed US trademark applications for PENTERA covering security software (https://trademarks.justia.com/owners/pentera-security-ltd-5403910). "Penthera" and "Pentera" differ by one letter in the same product category. This is the bigger risk: an acquirer will notice, and a confusion claim is plausible. |
+| Recommended next steps | Open | 1. Search EUIPO eSearch plus, TMview and the BOIP register for PENTHERA and PENTERA in classes 9 and 42. 2. Ask an IP lawyer for a short clearance opinion before spending on a filing or a brand. 3. If cleared, a Benelux filing at BOIP costs EUR 244 for one class (https://boip.int/en/node/2163, verify before filing); an EU trade mark at EUIPO costs more. 4. If not cleared, a rename is cheapest now, while adoption is small. |
+| npm and GitHub names | Done | `penthera` on npm and `danoszz/penthera` on GitHub are held by the maintainer. |
+
+## 4. Security posture of the project itself
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Pinned GitHub Actions | Done | Every `uses:` in `.github/workflows/` is pinned to a full commit SHA with the version in a comment. Dependabot proposes updates (an update to `actions/setup-node` is open as pull request #11). |
+| Staged npm publishing with 2FA | Done | `publish.yml` runs `npm stage publish`; nothing goes live until the maintainer approves the staged version with 2FA on npmjs.com. A hijacked workflow can stage, never ship. Merged in pull request #13. |
+| Trusted publishing, no stored token | Done | Publishing uses npm trusted publishing (OIDC). No npm token is stored in the repo or in secrets. |
+| npm provenance | Done | `--provenance` links each tarball to the workflow run and commit. |
+| CodeQL | Done | `.github/workflows/codeql.yml`. |
+| OpenSSF Scorecard | Done | Runs weekly and on push. Score 6.3 / 10 on 2026-10-19 (https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera). |
+| Scorecard: Token-Permissions 0 | Open | Scorecard reports workflow tokens with excessive permissions. `publish.yml` grants `contents: write` and `id-token: write` at the top level; move them to the job and set `permissions: read-all` or `{}` at the top. Check the other workflows the same way. |
+| Scorecard: Code-Review 0 | Decide | 0 of 15 changesets were reviewed by a second person. Expected for a solo project. A second maintainer or an outside reviewer would fix it. |
+| Scorecard: Signed-Releases 0 | Open | Scorecard looks for signatures or provenance attached to GitHub Releases. npm provenance exists, but the GitHub Release has no signed artefact. Attaching the packed tarball with a provenance attestation (for example `actions/attest-build-provenance`) would cover it. |
+| Scorecard: CII-Best-Practices 0 | Open | Apply for the OpenSSF Best Practices badge (https://www.bestpractices.dev/). Most criteria are already met. |
+| Scorecard: Fuzzing 0 | Decide | Penthera has property-based API fuzzing as a feature, but the project's own code is not fuzzed. Low priority. |
+| Scorecard: Branch-Protection not scored | Open | Scorecard could not read branch protection (needs an admin token). Check that `main` requires PRs and passing CI. |
+| Security policy | Done | `SECURITY.md` with private advisory reporting, response times and safe harbour. |
+| Offline tests | Done | Tests do not reach the internet (CONTRIBUTING.md). |
+| No telemetry | Done | Stated in README "Privacy". An acquirer may want to verify it; the egress guard on the roadmap would make it testable. |
+
+## 5. Business and governance
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Legal entity | Decide | The project is held by an individual. Funders such as NLnet accept individuals. An acquisition is simpler if the code, names and accounts sit in one entity. |
+| Accounts that would transfer | Open | List them: GitHub repo, npm package and its trusted publisher config, skills.sh listing, plugin marketplace entries, domain (if any), GitHub Sponsors profile. Make sure each has 2FA and a recovery path. |
+| Bus factor | Open | One maintainer. A documented release runbook exists (CONTRIBUTING.md, "Cutting a release"). Consider a second npm owner with 2FA for continuity. |
+| Funding history | Done | None so far. Keep a simple record of any grant or sponsorship income from the start. |
+| Claims in public material | Done | README and docs say "readiness" and "evidence", never "certified" or "compliant". Keep it that way in pitches. |
+
+## Sources
+
+- DCO 1.1: https://developercertificate.org/
+- NLnet GenAI policy: https://nlnet.nl/foundation/policies/generativeAI/
+- US Copyright Office AI reports: https://www.copyright.gov/ai/
+- Penthera (video SDK company): https://www.penthera.com/about , https://pitchbook.com/profiles/company/61416-37
+- Pentera: https://en.wikipedia.org/wiki/Pentera , https://trademarks.justia.com/owners/pentera-security-ltd-5403910
+- BOIP fees: https://boip.int/en/node/2163
+- OpenSSF Scorecard result: https://api.scorecard.dev/projects/github.com/danoszz/penthera
+- Arjun licence: https://github.com/s0md3v/Arjun ; SecLists licence: https://github.com/danielmiessler/SecLists

package/docs/funding/nlnet-ngi-zero-draft.md

@@ -0,0 +1,273 @@
+# NLnet application draft: Penthera
+
+Status: draft for the maintainer to edit. Nothing has been submitted.
+
+## Call status, checked on 2026-10-19
+
+The task asked for an NGI Zero application. NGI Zero is no longer taking
+proposals, so this draft targets its successor instead.
+
+| Item | What nlnet.nl says | Source |
+|------|--------------------|--------|
+| NGI Zero Commons Fund | Closed. "The thirteenth and final call of NGI Zero Commons Fund closed on June 1st 2026." | https://nlnet.nl/commonsfund/ |
+| NGI Zero Core | Closed. Final call closed on October 1st 2024. | https://nlnet.nl/core/ |
+| Transition | News item of 2026-06-12: "Transitioning from NGI to Open Internet Stack, open calls temporarily paused." | https://nlnet.nl/news/ |
+| Open now | Restack and CodeSupply, both part of the Open Internet Stack initiative (Horizon Europe, DG CNECT). | https://nlnet.nl/funding.html |
+| Deadline | **3 November 2026, 12:00 CET** (noon). NLnet now runs deadlines on the 3rd of every odd month. | https://nlnet.nl/propose/ , https://nlnet.nl/restack/ |
+| Amount | EUR 5,000 to 50,000 for a first grant. Above 50k needs a completed earlier grant. | https://nlnet.nl/propose/ , https://nlnet.nl/restack/guideforapplicants/ |
+| Scoring | Technical excellence and feasibility 30%, relevance and impact 40%, cost effectiveness 30%. Weighted score must exceed 5.0 of 7 to reach round two. | https://nlnet.nl/restack/guideforapplicants/ |
+
+### Which fund
+
+**Recommended: Restack.** Its scope explicitly lists "full stack security" and
+"software supply chain management", and it asks for tools that make the stack
+trustworthy. See https://nlnet.nl/restack/.
+
+**Risk to manage: Restack's AI exclusion.** The Restack page says
+"AI-related projects are not within scope", with an exception only for AI
+already used by more than 1 million active users. Penthera does not build or
+train AI. The relevant work audits configuration files and packages
+(skills, MCP servers, hooks, rule files) that developer tools install, using
+deterministic rules. This draft frames that work as software supply chain
+security, which is what it is, and leaves out the optional local-model part of
+the agent loop and the LLM endpoint probes. If the maintainer wants those in,
+the proposal is more likely to be ruled out of scope.
+
+**Alternative: CodeSupply.** A pilot on software supply chain metadata with
+about EUR 400,000 reserved for open calls. Its three objectives are about
+publishing software metadata and data sets. Penthera fits only if the proposal
+centres on publishing a data set (for example signed scan results for popular
+skills and MCP servers), which ROADMAP.md lists as "under consideration" and
+outside the offline core. Not recommended for a first proposal. See
+https://nlnet.nl/codesupply/.
+
+### Form fields (from https://nlnet.nl/propose/)
+
+| Field | Limit |
+|-------|-------|
+| Which fund (Restack / CodeSupply / Other, open call) | dropdown |
+| Proposal title | none stated |
+| Website(s) / repositories | none stated |
+| Abstract: summary of the project and expected results | 1000 characters |
+| Requested amount (EUR) | none stated |
+| Budget breakdown: tasks, effort, rate used, expenses | 4000 characters |
+| Comparison with other efforts, and whether you considered contributing to them | 4000 characters |
+| Expected technical challenges | 4000 characters |
+| Ecosystem, dependencies, main users | 2000 characters |
+| Why you are the right person(s), relevant experience | 2000 characters |
+| Other funding sources | 1000 characters |
+| Attachments | optional, 50 MB total |
+| Generative AI use: yes/no, model, purpose, prompts | 8000 characters, plus file upload |
+| Contact: name, email, optional OpenPGP key, phone, applicant type, organisation, country, European dimension | short fields |
+
+### Generative AI disclosure: this matters
+
+NLnet's GenAI policy (v1.1, effective 26 January 2026) allows AI help in
+writing a proposal but requires disclosure and a prompt provenance log: model,
+dates and times, the prompts, and the unedited output. Non-compliance can lead
+to rejection. See https://nlnet.nl/foundation/policies/generativeAI/.
+
+This draft was written with Claude (Anthropic, model Claude Opus 5.5) in
+Claude Code. If any of its text ends up in the submission, answer **Yes** on
+the form and attach the session transcript. The same policy also asks funded
+projects to mark AI-generated code contributions. Penthera already records
+this with `Co-Authored-By:` trailers in commit messages, which the policy
+names as one acceptable method. Say so in the proposal.
+
+---
+
+## Draft answers
+
+Edit before submitting. Character counts are approximate and include spaces.
+
+### Fund
+
+Restack
+
+### Proposal title
+
+Penthera: offline security and supply chain checks for small EU teams and their developer tooling
+
+### Website / repository
+
+https://github.com/danoszz/penthera
+https://www.npmjs.com/package/penthera
+
+### Abstract (limit 1000, draft about 950)
+
+Small organisations in the EU now face NIS2 and the Cyber Resilience Act, but
+most security tooling assumes a security team, a SaaS account, and sending
+code or findings to a vendor cloud. Penthera is an MIT-licensed scanner that
+runs entirely on the user's machine: it checks live web apps and APIs, scans
+repositories for secrets and risky routes, and produces NIS2 readiness evidence
+without claiming certification. It has no telemetry. This project extends it in
+three directions: (1) a deterministic audit of the software that developer
+tools install, such as plugins, MCP servers, hooks and rule files, including
+hidden-content detection, hash pinning and install-time package checks; (2) a
+local scan, fix and verify loop with a strict egress guard so the tool can only
+reach the target the user named; (3) CRA vulnerability reporting support and
+improved evidence output for auditors. All results ship as open source with
+tests and documentation.
+
+### Requested amount
+
+EUR 47,850 (placeholder, see budget)
+
+### Budget breakdown (limit 4000)
+
+Rate used: EUR 55 per hour (placeholder; the maintainer should set this to a
+rate they can justify for part-time work in the Netherlands). No other
+expenses. Work done before the grant, including `penthera agents` (pull
+request #12), is not charged.
+
+Milestone 1: Supply chain audit for developer tooling (290 h, EUR 15,950)
+- 1a Hidden-content engine: Unicode tag, zero-width and bidi characters,
+  whitespace padding, embedded `.pyc` files and archives, `curl | sh`,
+  auto-approve hooks, unpinned `npx -y` servers. Tests per pattern. 80 h
+- 1b `penthera.lock`: hash-pin installed skills, MCP tool definitions and
+  hooks; a CI check that fails on silent changes. 80 h
+- 1c Install-time package checks: non-existent or very new packages,
+  risky `postinstall` scripts, offline IOC packs for known npm worm
+  campaigns. 100 h
+- 1d Detect provider keys exposed in browser JavaScript bundles through
+  public build variables. 30 h
+
+Milestone 2: Local scan, fix and verify loop (300 h, EUR 16,500)
+- 2a `--offline` egress guard: one HTTP client that can only reach the named
+  target; recon sources and the CVE database become explicit opt-ins with a
+  vendored fallback. 80 h
+- 2b Deterministic fixes for common findings (headers, cookies, CORS), applied
+  on a local branch after human approval, then re-scanned to prove the fix.
+  No language model involved. 140 h
+- 2c Audience-specific reports (developer, owner, auditor), a found, fixed and
+  verified timeline, and a hashed evidence bundle. 80 h
+
+Milestone 3: Compliance support for small organisations (220 h, EUR 12,100)
+- 3a CRA Article 14 reporting helper, reusing the existing NIS2 incident
+  helper. 40 h
+- 3b Map checks for developer tooling to the OWASP MCP Top 10, with a per-run
+  coverage table. 50 h
+- 3c Extend the CycloneDX SBOM with installed plugins, MCP servers and skills.
+  70 h
+- 3d MFA probe, the last NIS2 Article 21 measure still marked as planned. 60 h
+
+Milestone 4: Release, documentation and outreach (60 h, EUR 3,300)
+- Documentation for each feature, a Dutch-language NIS2 guide for small
+  organisations, release engineering with staged npm publishing and
+  provenance, and two feedback sessions with small organisations. 60 h
+
+Total: 870 h, EUR 47,850.
+
+### Comparison with other efforts (limit 4000)
+
+Commercial platforms such as Snyk, Aikido, Socket, GitGuardian and Semgrep
+cover parts of this space, mostly as hosted services that need an account. Two
+are close to milestone 1:
+
+- Snyk Agent Scan (formerly Invariant Labs mcp-scan, Apache-2.0) scans MCP
+  servers, skills and agent configurations. It sends tool names, descriptions,
+  server configurations and skill content to a remote API for analysis, needs a
+  Snyk token, and starts stdio MCP servers from the config to read their tools.
+  Source: https://github.com/snyk/agent-scan
+- GitGuardian added AI hooks and an inventory of agents and MCP servers per
+  endpoint (September 2026), focused on secrets in prompts and tool calls. It is
+  part of a licensed product. Source:
+  https://docs.gitguardian.com/releases/saas/2026/09/07/changelog
+
+Penthera differs in three ways. It is offline and deterministic: rules, not a
+remote model, decide findings, so results are reproducible and nothing about
+the user's setup leaves the machine. It reads configuration files without
+executing the servers they describe. And it ties the result to evidence a
+small organisation can use for NIS2 and CRA, without claiming certification.
+
+On contributing instead: Snyk Agent Scan is open source, but its design
+depends on the remote analysis API, so offline operation would mean a different
+architecture rather than a patch. For web app checks, Penthera already accepts
+Nuclei-compatible templates, so it builds on that ecosystem rather than
+replacing it. SARIF output lets results flow into GitHub code scanning and
+other tools.
+
+### Expected technical challenges (limit 4000)
+
+- False positives from hidden-content rules. Many legitimate files contain
+  zero-width joiners or non-Latin text. Each rule needs a fixture corpus of
+  both malicious and benign samples, and a confidence label on every finding.
+- Hash pinning across tools that store configuration differently and update
+  without notice. `penthera.lock` must normalise formats so it flags real
+  changes, not reformatting.
+- Package checks without network access. Registry age and existence need a
+  network call, so the offline mode needs a vendored snapshot and a clear
+  label when data is stale.
+- A strict egress guard in Node.js. Every HTTP path, including dependencies,
+  must go through one client. This needs tests that fail if any other path
+  opens a socket.
+- Safe automated fixes. A fix must apply to a local branch only, never push,
+  and be proven by a re-scan. Framework detection must be conservative.
+- Keeping compliance output honest. NIS2 and CRA texts are interpreted
+  differently per member state. Jurisdiction data lives in config, and the
+  output says "readiness" and "evidence", never "compliant".
+
+### Ecosystem, dependencies, main users (limit 2000)
+
+Penthera is a Node.js (22+) CLI published on npm, and an Agent Skill installed
+through skills.sh and plugin marketplaces. Runtime dependencies are minimal:
+one (`yaml`). It reads OpenAPI, Nuclei-compatible templates and writes SARIF,
+JSON, Markdown and CycloneDX.
+
+Main users are developers and small teams who build web apps, often with AI
+coding assistants, and small organisations that need NIS2 evidence without a
+security department. Public adoption on 2026-10-19: 46 GitHub stars, 11 forks,
+59 installs on skills.sh, and 46 npm downloads in the 30 days to 2026-10-16
+(api.npmjs.org). The project is four months old.
+
+Outreach: the README and docs, the skills.sh listing, Dutch-language material
+for NIS2 (the Dutch Cyberbeveiligingswet entered into force on 15 August
+2026),
+and SARIF output that drops into existing CI.
+
+### Why you (limit 2000)
+
+Placeholder for the maintainer to write in their own words. Suggested points:
+background and years of experience; built and released Penthera v1.0 to v1.2
+in 2026; the release pipeline uses SHA-pinned actions, least-privilege
+workflows, CodeQL, OpenSSF Scorecard, npm trusted publishing with provenance,
+and staged releases approved with 2FA; based in the Netherlands, close to the
+NIS2 and CRA context of the target users.
+
+### Other funding sources (limit 1000)
+
+None. Penthera is maintained part-time without funding. A GitHub Sponsors
+profile has been requested; any sponsorship income will be reported here if it
+exists at submission time.
+
+### Applicant type and country
+
+Individual (or SME, if the maintainer applies through a company). Country:
+the Netherlands.
+
+---
+
+## Sources
+
+- NLnet funding overview: https://nlnet.nl/funding.html
+- Proposal form and deadline: https://nlnet.nl/propose/
+- Restack: https://nlnet.nl/restack/
+- Restack guide for applicants: https://nlnet.nl/restack/guideforapplicants/
+- CodeSupply: https://nlnet.nl/codesupply/
+- NGI Zero Commons Fund (closed): https://nlnet.nl/commonsfund/
+- NGI Zero Core (closed): https://nlnet.nl/core/
+- NLnet GenAI policy: https://nlnet.nl/foundation/policies/generativeAI/
+- CRA reporting from 11 September 2026: https://digital-strategy.ec.europa.eu/en/policies/cra-reporting
+- Dutch Cyberbeveiligingswet in force 15 August 2026: https://www.nldigitalgovernment.nl/nis2-directive-cyberbeveiligingswet-cbw/
+- Snyk Agent Scan: https://github.com/snyk/agent-scan
+- GitGuardian changelog, 2026-09-07: https://docs.gitguardian.com/releases/saas/2026/09/07/changelog
+- npm downloads: https://api.npmjs.org/downloads/point/last-month/penthera
+
+## Before submitting
+
+- [ ] Set a real hourly rate and recompute the budget.
+- [ ] Decide whether to keep AI-adjacent wording given the Restack scope note.
+- [ ] Write "Why you" in your own words.
+- [ ] Refresh the adoption numbers on the day you submit.
+- [ ] Answer the generative AI question honestly and attach the log.
+- [ ] Re-check the deadline on https://nlnet.nl/propose/ (3 November 2026, 12:00 CET at time of writing).

package/docs/funding/partner-one-pager.md

@@ -0,0 +1,84 @@
+# Penthera: a one-page brief for security platforms
+
+For: teams at security platforms such as Aikido, Socket, Snyk, GitGuardian and
+Semgrep. Draft, not sent to anyone.
+
+## What Penthera is
+
+An MIT-licensed security scanner that runs on the developer's own machine, as a
+CLI (`npx penthera`) and as an Agent Skill for Claude Code and Cursor. It has no
+accounts and no telemetry. It does three things:
+
+1. **Scans the app.** Black-box checks of a live URL (TLS, headers, CORS,
+   cookies, OpenAPI discovery, auth hardening, JWT, IDOR, OAuth redirects, opt-in
+   injection probes) and white-box checks of a repo (routes, trust boundaries,
+   hardcoded secrets including keys for a dozen AI providers).
+2. **Audits the AI developer toolchain.** `penthera agents` (in review, pull
+   request #12) reads `.mcp.json`, `~/.claude`, `~/.cursor`, hooks, plugins,
+   skills and rule files, and grades them A to F, with SARIF output.
+3. **Produces NIS2 evidence.** A per-measure readiness report, self-assessment,
+   policy pack, incident report drafts and a CycloneDX SBOM. It never claims
+   certification.
+
+## Where it differs from your products
+
+Checked against public product pages on 2026-10-19. These are differences in
+approach, not claims that one is better.
+
+| Penthera | What we found in public sources |
+|----------|--------------------------------|
+| **Offline, deterministic audit of agent configuration.** Rules decide findings; nothing about the user's setup leaves the machine; MCP servers are read from config, not started. | Snyk Agent Scan (formerly Invariant mcp-scan) covers MCP servers, skills and agent harnesses, but sends tool descriptions, server configs and skill content to a remote API, needs a Snyk token, and starts stdio servers to read their tools ([repo](https://github.com/snyk/agent-scan)). GitGuardian added AI hooks and an agent and MCP inventory in September 2026, focused on secrets in prompts and tool calls ([changelog](https://docs.gitguardian.com/releases/saas/2026/09/07/changelog)). We found no MCP or skill audit product in Socket's getting-started docs ([docs](https://docs.socket.dev/docs/getting-started)), though Socket does publish audits of individual skills listed on skills.sh. |
+| **App DAST inside the coding agent, with a scan, fix, verify loop.** The skill scans, proposes a framework-aware fix, and re-scans to prove it, all locally. | Aikido offers DAST, API scanning, AI pentesting and fix and verify agents as a hosted platform ([aikido.dev](https://www.aikido.dev/)). Snyk has DAST through its 2024 Probely acquisition ([Snyk news](https://snyk.io/news/snyk-acquires-developer-first-dast-provider-probely/)). Semgrep's product list covers SAST, supply chain and secrets, with no DAST listed ([semgrep.dev](https://semgrep.dev/)). |
+| **NIS2 and CRA evidence for small organisations.** Output is readiness and evidence for the Dutch Cyberbeveiligingswet and NIS2 Article 21, plus a CRA Article 14 reporting helper on the roadmap. | Aikido's homepage cites its own SOC 2 Type II and ISO 27001 status but does not mention NIS2 or CRA ([aikido.dev](https://www.aikido.dev/)). Semgrep's homepage does not mention them either ([semgrep.dev](https://semgrep.dev/)). We did not check Socket, Snyk or GitGuardian for this, and a homepage check can miss features documented elsewhere. |
+
+Where Penthera does not compete: hosted dashboards, organisation-wide policy,
+runtime protection, cloud posture, container scanning, and broad SAST rule sets.
+The platforms above are far ahead there, and Penthera has no plans to build
+them ([ROADMAP.md, "Not planned"](../../ROADMAP.md)).
+
+## How it fits next to a platform
+
+- **SARIF out.** Every scan can write SARIF, which GitHub code scanning accepts
+  from third-party tools ([GitHub docs](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)).
+  A platform that ingests third-party SARIF can show Penthera findings
+  next to its own. We have not yet confirmed which of the five platforms
+  accept third-party SARIF; that is a question for each partner.
+- **The local step before CI.** Penthera runs in the editor and agent before a
+  commit. A platform covers the repo, pipeline and runtime after it.
+- **The offline option for customers who need it.** For teams that cannot send
+  code or configuration to a vendor, Penthera can be the documented local
+  fallback.
+- **Planned: a "use alongside" guide** (`docs/use-alongside.md`, not yet
+  written) showing how to run Penthera with each platform without duplicate
+  findings.
+
+## Possible ways to work together
+
+- Ingest Penthera SARIF, or list it as a supported third-party source.
+- Sponsor the project ([sponsor-tiers.md](sponsor-tiers.md)).
+- Share detection research: for example Penthera's deterministic rules for
+  hidden content in skills and MCP tool descriptions.
+- Longer term, a closer arrangement. The maintainer is open to that
+  conversation. Any arrangement would keep the MIT core, the offline mode, and
+  the no-telemetry rule.
+
+## Adoption, honestly
+
+Fetched on 2026-10-19. Penthera is four months old (first release 2026-06-30)
+and small.
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| npm downloads, last 30 days | 46 (2026-09-17 to 2026-10-16) | https://api.npmjs.org/downloads/point/last-month/penthera |
+| npm downloads, since 2026-06-01 | 435 (to 2026-10-18) | https://api.npmjs.org/downloads/range/2026-06-01:2026-10-18/penthera |
+| skills.sh installs | 59 total | https://skills.sh/danoszz/penthera |
+| GitHub stars | 46 | https://github.com/danoszz/penthera |
+| GitHub forks | 11 | https://github.com/danoszz/penthera |
+| OpenSSF Scorecard | 6.3 / 10 (2026-10-19) | https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera |
+
+npm counts include CI and mirror downloads, so they overstate human users.
+There is no telemetry, so there is no other usage data.
+
+## Contact
+
+Daan van der Zwaag, maintainer. GitHub: [@danoszz](https://github.com/danoszz).

package/docs/funding/sponsor-tiers.md

@@ -0,0 +1,81 @@
+# GitHub Sponsors tiers (proposal)
+
+Status: proposal. The tiers below still need to be created on the GitHub
+Sponsors dashboard once the profile is approved. Prices are in US dollars
+because GitHub Sponsors tiers are priced in USD.
+
+## Tiers
+
+| Tier | Monthly | For | What you get |
+|------|---------|-----|--------------|
+| Individual | $5 | People who use Penthera on their own projects | Thanks, and your name on the sponsors list on GitHub if you want it. |
+| Supporter | $25 | Freelancers and consultants who use Penthera for clients | The above, plus a mention in the release notes of the next minor release. |
+| Startup | $100 | Small teams and startups | The above, plus your name and a link in the README under "Sponsors". |
+| Company | $500 | Companies that rely on Penthera or build on it | The above, plus your logo in the README under "Sponsors", and a 30-minute call per quarter to talk through the roadmap. |
+
+One-time sponsorships of any amount are also welcome.
+
+## What sponsorship pays for
+
+Maintainer time. Specifically, in rough order:
+
+1. Keeping detection rules current: new AI provider key formats, new
+   supply chain attack patterns, new checks for developer tooling.
+2. Security fixes and releases for Penthera itself.
+3. The roadmap in [ROADMAP.md](../../ROADMAP.md).
+
+## What sponsorship does not buy
+
+Written down so nobody is surprised:
+
+- **No influence over findings.** Sponsors' products are scanned and reported
+  the same way as everyone else's. A sponsor cannot have a rule removed or
+  softened.
+- **No roadmap control.** The quarterly call is a conversation, not a vote.
+  Priorities stay set by evidence of what users need.
+- **No support contract or SLA.** Penthera is maintained part-time. Bug reports
+  are handled in public issues, in the order the maintainer judges best.
+- **No early or private access to vulnerability information.** Security issues
+  follow [SECURITY.md](../../SECURITY.md) for everyone.
+- **No certification or endorsement.** A logo in the README means the company
+  supports the project. It does not mean Penthera has assessed or approved that
+  company's security, and the README will say so next to the logos.
+- **No change to the principles.** No telemetry, offline first, MIT licence.
+  Sponsorship will never add a feature that sends data off the user's machine.
+
+## Logo rules (Company tier)
+
+- One logo, at most 160 px wide, in the README "Sponsors" section, linked to the
+  company site.
+- Logos are listed in the order sponsorships started.
+- The logo is removed in the first README update after a sponsorship ends.
+- The maintainer may decline or end a sponsorship, for example for a company
+  whose product is malware or surveillance tooling. Any payment for a month not
+  yet started is then refunded.
+
+## Fees and money, for transparency
+
+From the GitHub Sponsors docs: GitHub charges no fees on sponsorships from
+personal accounts. Sponsorships from organisation accounts carry up to 6% in
+fees (3% card processing and 3% GitHub service fee; invoiced billing avoids the
+card fee). Tier prices cannot be edited after publishing; a tier has to be
+retired and replaced. Source:
+https://docs.github.com/en/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors
+
+The maintainer intends to publish a short yearly note on total sponsorship
+income and what it paid for.
+
+## Proposed edits in this PR
+
+- `.github/FUNDING.yml`: adds a `custom` link to this page, so the Sponsor
+  button explains the tiers before the GitHub Sponsors profile is live.
+- `README.md`, "Support Penthera": lists the tiers in short and links here.
+
+## Open questions for the maintainer
+
+- Are $100 and $500 right for startups and companies? They are deliberately
+  modest. Raise them if the first sponsors suggest so.
+- Is a quarterly call something you want to commit to? If not, drop it from the
+  Company tier before publishing, because published tiers cannot be edited.
+- Check with a tax adviser how sponsorship income should be reported in the
+  Netherlands before the first payout.

package/docs/index.md

@@ -1,6 +1,6 @@
 # Penthera documentation
 
-Security scanner for developers: scan live URLs, local repos, or macOS machines from your AI agent or the CLI.
+The routine work of a security team, on your own machine: app scanning, dependency and install checks, an AI-tooling audit, a local fix loop, and auditor-grade reports. Offline, deterministic, free.
 
 ## Getting started
 
@@ -9,6 +9,7 @@ Security scanner for developers: scan live URLs, local repos, or macOS machines
 | [README](../README.md) | Install, quick start, ethical use |
 | [Run it](../README.md#run-it) | Install + first-time wizard (`penthera` with no args) |
 | [CHANGELOG](../CHANGELOG.md) | Version history |
+| [Roadmap](../ROADMAP.md) and [release plan](./release-plan.md) | What ships next, in what order |
 
 ## Scanning
 
@@ -34,10 +35,20 @@ Security scanner for developers: scan live URLs, local repos, or macOS machines
 |-------|------|
 | 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) |
 | 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` |
 
+## Methodology & research
+
+| Topic | Link |
+|-------|------|
+| How detection works, confidence model, limits | [METHODOLOGY.md](./METHODOLOGY.md) |
+| 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) |
+
 ## Agent skill
 
 | Topic | Location |