penthera 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,106 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-10-19
+
+The first step toward securing the AI toolchain itself: catch AI provider keys,
+harden Penthera's own supply chain, and make CI test what it says it tests. The
+[roadmap](ROADMAP.md) now sets out the AI supply-chain and local agent-loop
+tracks.
+
+### Added
+
+- **AI provider key detection** in repo scans: Anthropic, OpenAI project and
+  service-account keys, OpenRouter, Google (Gemini / Firebase), Groq, Hugging
+  Face, Replicate, xAI, Perplexity, LangSmith, and Pinecone. Jupyter notebooks
+  (`.ipynb`) are now scanned too. A provider key inside an `api_key = "..."`
+  assignment is reported once, under its provider, instead of twice
+- `findSecretsInText()` exported from `lib/whitebox/secrets.js`, so the same
+  rules can run on any text (groundwork for scanning JS bundles)
+- CodeQL and OpenSSF Scorecard workflows, Dependabot for npm and GitHub Actions
+  (with a 7-day cooldown before adopting new releases)
+- CI check that `package.json`, the lockfile, the skill, and both plugin
+  manifests carry the same version
+- Roadmap: AI supply-chain audit (`penthera agents`), a fully local
+  scan → fix → verify → learn loop, and LLM-endpoint probes. Principles now
+  state no telemetry, no auto-push, and no remote learning
+
+### Fixed
+
+- **Modern OpenAI keys were missed.** The old pattern stopped at the hyphen in
+  `sk-proj-...` and `sk-svcacct-...`, so the key format OpenAI has issued since
+  2024 never matched
+- The example scan workflow lived in `.github/workflows/`, so it ran on its
+  weekly cron and failed every Monday. It moved to
+  `docs/examples/github-actions-scan.yml` and now uses `npx penthera@<version>`,
+  so it works when copied into your own repo
+- CI ran only 4 of 24 test files; it now runs the full `npm test`
+- Removed `tests/pentest-static.test.js`, which tested functions defined inside
+  the test file rather than anything Penthera ships
+- `.claude-plugin/plugin.json` still said 1.0.0
+- `SECURITY.md` listed 1.0.x as supported. It now covers 1.2.x and gives response
+  times, scope, and safe-harbor terms
+
+### Changed
+
+- **Node.js 22 or newer is now required.** Node 18 and 20 are end-of-life, and
+  the test toolchain (vitest 5) needs 22. CI runs on Node 22 and 24
+- GitHub Actions are pinned to commit SHAs, and every workflow declares
+  least-privilege `permissions`
+- Releases use npm trusted publishing (OIDC, no stored token) and **staged
+  publishing**: CI stages each version, and it only goes live after a
+  maintainer approves it with 2FA. The workflow also creates the GitHub Release
+- The Docker image runs as the unprivileged `node` user on `node:22-alpine`
+- README reordered so install and quick start come before compliance. The full
+  NIS2 guide moved to [`docs/compliance-nis2.md`](docs/compliance-nis2.md)
+- vitest 3 → 5 (clears 8 dev-only advisories), yaml 2.8 → 2.9
+
+## [1.1.1] - 2026-08-16
+
+A correctness release. One of these was a live outage: if you are on 1.1.0,
+upgrade.
+
+### Fixed
+
+- **JS dependency scanning was silently dead.** The Retire.js vulnerability
+  database URL pointed at a fork that now returns 404, so every scan reported
+  "no vulnerable JS libraries" without ever running the check. It now reads from
+  upstream RetireJS with a mirror, validates the payload, and when no source is
+  reachable it says the check did not run instead of returning a clean result.
+  The probe is also excluded from coverage in that case, so a compliance report
+  cannot claim supply-chain evidence that was never collected
+- **Command injection in the machine audit.** Binary paths read from
+  attacker-writable plists were interpolated into a shell string, so a malicious
+  persistence entry could execute code inside the scanner. Paths are now argv
+  entries and signature checks use the exit status, failing closed
+- Two built-in templates fired on any single-page app with catch-all routing:
+  the `.env.local` matcher accepted a bare `=` (present in every HTML attribute)
+  and the Firebase one accepted any 200 without the word "error", so an
+  `index.html` served at those paths was reported as critical
+- Time-based SQL and command injection no longer report on a single slow
+  response. A candidate delay is re-sampled and only reported when the median
+  holds, which a garbage-collection pause or cold start does not survive
+- Community template regexes ran unbounded against whole response bodies. A
+  catastrophically-backtracking pattern would hang the scanner; patterns with
+  nested quantifiers are now refused and input is capped
+- Dedupe and baseline comparison used different keys that included severity, so
+  re-rating a finding reported it as one resolved plus one new. Both now share
+  the audit loop's fingerprint
+- A measure with nothing scanned and nothing attested was scored as a gap,
+  telling an entity that had not yet filled in the self-assessment that it had
+  failed. That state is now reported as not assessed
+- The XSS canary was a fixed, fingerprintable string; it is now randomised per
+  probe
+- XProtect staleness was computed and discarded; it is now reported
+
+### Changed
+
+- The Nuclei loader documents the subset it actually implements and reports per
+  template which unsupported features it needs, instead of letting a template
+  that cannot match look like a clean pass
+- Provenance (confidence, method, collection time) now travels into SARIF, and
+  the terminal marks findings a scanner cannot adjudicate
+
 ## [1.1.0] - 2026-08-16
 
 NIS2 / Cyberbeveiligingswet readiness work: a hardening pass over the
@@ -130,7 +230,7 @@ and generated documents.
   live integration tests report as skipped (not passed) without a running target
 - Corrected the built-in template count (14, not 17) in docs and progress output
 
-## [1.0.0], 2026-06-30
+## [1.0.0] - 2026-06-30
 
 First production-ready release.
 
@@ -155,14 +255,15 @@ First production-ready release.
 
 - URL trailing-slash normalization (double-slash 404 bug)
 
-## [0.2.0], 2026-04
+## [0.2.0] - 2026-04
 
 - Markdown reports, scan profiles, auth tooling, expanded API discovery
 
-## [0.1.x], 2026-04
+## [0.1.x] - 2026-04
 
 - Initial CLI: URL, repo, and machine scan modes
 - Built-in templates, TLS, CORS, SARIF export
 
+[1.1.1]: https://github.com/danoszz/penthera/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/danoszz/penthera/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/danoszz/penthera/compare/v0.2.0...v1.0.0

package/README.md

@@ -4,10 +4,11 @@
 
 <br/><br/>
 
-![version](https://img.shields.io/badge/version-1.1.0-0000ed)
-![node](https://img.shields.io/badge/node-%E2%89%A518-0000ed)
+[![npm](https://img.shields.io/npm/v/penthera?color=0000ed)](https://www.npmjs.com/package/penthera)
+![node](https://img.shields.io/badge/node-%E2%89%A522-0000ed)
 ![license](https://img.shields.io/badge/license-MIT-0000ed)
 [![CI](https://github.com/danoszz/penthera/actions/workflows/ci.yml/badge.svg)](https://github.com/danoszz/penthera/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/danoszz/penthera/badge)](https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera)
 
 <br/>
 
@@ -33,7 +34,8 @@ issues." The agent picks the scan, runs it, and gives you the fixes.
 You shipped something fast: vibecoded, AI-assisted, already live. The same models
 that helped you build it also make it easy for someone to probe it. Exposed API
 routes, missing security headers, weak auth, a hardcoded key in the repo. These
-are the common mistakes that get apps broken into.
+are the common mistakes that get apps broken into. An AI provider key in the
+frontend bundle is the newest and most expensive of them.
 
 Penthera is the check you run before you launch. Ask your agent to "scan my app
 for security issues" and it runs an authorized, non-destructive scan, then lists
@@ -43,6 +45,34 @@ background to use it.
 Penthera is for hardening systems you own. It is powerful, so please use it
 carefully. See [Ethical use](#ethical-use--authorization) and the [Disclaimer](#disclaimer).
 
+Shipping in the EU? Penthera also generates your
+[NIS2 readiness report, policy pack, incident-report drafts, SBOM, and prefilled
+customer security questionnaires](#compliance-nis2-and-the-cyberwetgeving).
+Offline, no accounts. Readiness tooling, not a certification.
+
+### What you get
+
+```
+  Findings
+
+  HIGH  IDOR/BOLA: GET /api/users/{user_id}
+         http://localhost:3000/api/users/1 → 200
+  HIGH  OAuth open redirect
+         http://localhost:3000/api/oauth/callback?redirect_uri=... → 302
+  MED   Missing Content-Security-Policy
+  MED   No login rate limiting detected
+         http://localhost:3000/api/login → 401
+  LOW   Missing X-Frame-Options
+  INFO  Missing Referrer-Policy
+
+  ──────────────────────────────────────────────────────────
+  2 high · 5 medium · 2 low · 2 info
+```
+
+Every finding carries a confidence label (`confirmed`, `likely`, `potential`,
+`needs-human-review`), so a heuristic never poses as a certainty. Reports come
+out as Markdown, JSON, and SARIF, with the fixes in priority order.
+
 ---
 
 ## Run it
@@ -68,6 +98,12 @@ Then talk to your agent:
 "Find hardcoded secrets in this repo before I push"
 ```
 
+**Or try it with no install at all:**
+
+```bash
+npx penthera https://your-app.example
+```
+
 Prefer the terminal? Run `penthera` with no arguments for a guided wizard.
 
 > The skill adds an authorization gate: it instructs your agent to refuse targets
@@ -80,7 +116,7 @@ Prefer the terminal? Run `penthera` with no arguments for a guided wizard.
 | Mode | Command | Coverage |
 |------|---------|----------|
 | **URL scan** | `penthera https://example.com` | TLS, fingerprinting, endpoint discovery, templates, CORS, cookies, JS CVEs, param discovery, OpenAPI/FastAPI probes, security headers, auth hardening |
-| **Repo scan** | `penthera --repo ./my-app` | API route discovery (Next.js, Express, Hono, Fastify), trust-boundary mapping, hardcoded-secret scanning |
+| **Repo scan** | `penthera --repo ./my-app` | API route discovery (Next.js, Express, Hono, Fastify), trust-boundary mapping, hardcoded-secret scanning (including Anthropic, OpenAI, Gemini, Groq, Hugging Face and other AI provider keys) |
 | **Combined** | `penthera https://staging.app --repo .` | Black-box and white-box in one run |
 | **Interactive** | `penthera` *(no args)* | Guided wizard (URL plus optional repo scan, Markdown report) |
 | **Machine audit** | `penthera --machine` | macOS checks (keyloggers, persistence, rootkits) |
@@ -123,245 +159,6 @@ Findings map to the [OWASP Web Security Testing Guide](docs/owasp-wstg-coverage.
 
 ---
 
-## Compliance: NIS2 and the cyberwetgeving
-
-The EU NIS2 directive and its national transpositions (the Cyberbeveiligingswet
-in the Netherlands, the NIS2-wet in Belgium) put a duty of care, the *zorgplicht*,
-on in-scope organisations. That duty is the set of risk-management measures in
-Article 21(2) of the directive. Most of them are organisational. Some are
-technical and testable, and that is the part Penthera helps with.
-
-Penthera does not make you compliant and does not certify anything. What it gives
-you is automated, repeatable technical evidence for the measures a scanner can
-honestly verify: the kind of artefact you can attach to a risk file, show an
-auditor, or run in CI so a regression shows up before it ships.
-
-| Art. 21(2) measure | What Penthera does | Coverage |
-|--------------------|--------------------|----------|
-| **(a)** Risk analysis & information-security policy | Findings, severity, and baseline history feed your risk analysis | Evidence |
-| **(b)** Incident handling | Report scaffolding (on the roadmap) | Planned |
-| **(c)** Business continuity, backup, crisis management | Organisational; outside a scanner's reach | Out of scope |
-| **(d)** Supply-chain security | Known-CVE checks on JS dependencies (Retire.js); leaked third-party credentials (secret scan) | Partial |
-| **(e)** Security in acquisition, development & maintenance; **vulnerability handling** | The core: black- + white-box scanning mapped to OWASP WSTG, SARIF → GitHub, baseline regression, scan-and-fix loop | **Strong** |
-| **(f)** Assessing the effectiveness of measures | Baseline diff + re-scan-to-verify is a repeatable effectiveness check | Partial |
-| **(g)** Cyber hygiene & training | Remediation playbook + secure-defaults guidance (guidance, not a training programme) | Partial |
-| **(h)** Cryptography & encryption | TLS protocol/cipher/certificate audit, HSTS, cookie `Secure` (transport layer only) | Partial |
-| **(i)** HR security, **access control**, asset management | Access control tested: JWT, IDOR/BOLA, OAuth redirect, client-side-auth, trust-boundary mapping | Partial |
-| **(j)** Multi-factor authentication & secure communications | MFA probe (on the roadmap) | Planned |
-
-**Coverage key:** *Strong* = automated technical testing · *Partial* = part of the
-measure · *Evidence* = output feeds the measure, no direct test · *Planned* = on the
-roadmap · *Out of scope* = organisational or physical.
-
-In practice, Penthera today gives you solid automated evidence for the
-secure-development and vulnerability-handling duty (e), which is the technical
-heart of the zorgplicht, plus meaningful coverage of supply chain (d),
-cryptography in transit (h), access control (i), and effectiveness testing (f).
-That is not the whole duty of care, but it is a real, defensible start you can run
-today and re-run on every deploy.
-
-> **Not legal advice, not a certification, not a guarantee of compliance.**
-> Penthera automates the technical-testing part of the duty of care. The
-> directive's organisational duties (governance, risk-management policy,
-> incident-notification processes, supply-chain contracts, staff training) need
-> human process and, where it matters, review by a qualified advisor. For an
-> authoritative reading, consult your national authority (the NCSC in the
-> Netherlands, the CCB and its CyFun framework in Belgium) or a specialised jurist.
-
-Generate this mapping for your own scan with `--framework nis2`. It adds a
-per-run coverage table (which measures *this* scan actually exercised, driven by
-the probes that ran) to the terminal, Markdown, and JSON reports:
-
-```bash
-penthera https://myapp.com --framework nis2 -o reports/scan.json
-```
-
-### Readiness report (clone → report in two commands)
-
-Go further than the mapping: combine the scan with a short offline
-self-assessment (the organisational measures a scanner can't test, like policies,
-backups, training, and MFA) into a full NIS2 readiness report. Every Article 21
-measure is marked `met / partial / gap / n-a`, with proportionality notes, your
-incident-reporting deadlines, and provenance on every piece of evidence.
-
-```bash
-# 1. Create your self-assessment (offline, one-time). Fill in yes | partial | no | na.
-penthera --assessment-init assessment.json
-
-# 2. Scan + self-assessment → readiness report (writes reports/scan-readiness.md)
-penthera https://myapp.com --repo . --readiness --assessment assessment.json -o reports/scan.json
-```
-
-The readiness report is **evidence and self-assessment tooling, not a
-certification**. It is provenance-linked (`source, method, collected_at,
-confidence`) and reproducible, and it lists exactly what only you can attest to.
-Jurisdiction specifics live in `lib/jurisdictions/nl.json` (NL today; BE and
-others are just added config).
-
-### Answer a customer's security questionnaire
-
-The questionnaire blocking your deal, drafted from evidence you already have:
-
-```bash
-# one question per line, pasted from the customer's form
-penthera https://myapp.com --readiness --assessment assessment.json --questionnaire questions.txt
-```
-
-Each question is mapped to the Article 21 measure it belongs to and answered
-from the scan and your self-assessment, with the backing evidence cited.
-Anything Penthera can't map is marked `NEEDS HUMAN INPUT` instead of guessed.
-Review every answer before you send it.
-
-### Policy pack
-
-Generate the proportionate written policies NIS2 expects, pre-filled from your
-readiness gaps and the NL incident deadlines:
-
-```bash
-penthera --policy-pack ./policies --org "Your Company" --readiness --assessment assessment.json
-```
-
-Writes editable Markdown starting points: information security, access control,
-incident response, backup/continuity, acceptable use, supplier security, and
-vulnerability management. **Templates, not legal advice.** Keep them short and
-used. A two-page policy that genuinely exists is what "proportionate" means.
-
-### Incident-report helper
-
-NIS2 has hard reporting deadlines (24h early warning, 72h notification, 1-month
-final report). If something happens, get the timeline and draft reports:
-
-```bash
-penthera --incident-init incident.json   # fill in what happened (set aware_at)
-penthera --incident incident.json        # writes incident-reports.md
-```
-
-It computes your three deadlines from when you became aware, flags anything
-overdue, and drafts the early-warning, notification, and final report against
-the required content, with `NEEDS INPUT` where you still have to fill in facts.
-**These are drafts to help you meet the deadlines, not a substitute for your
-authority's official form.**
-
-### Software bill of materials (SBOM)
-
-Emit a standard CycloneDX SBOM of your dependencies. It's what enterprises
-increasingly require of suppliers, and direct evidence for supply-chain security
-(measure d):
-
-```bash
-penthera --repo . --sbom sbom.cdx.json
-```
-
-Parses `package-lock.json` / `package.json` / `requirements.txt` offline (no
-network), with resolved versions and package URLs (purls).
-
-### Remediation tracking (the audit loop)
-
-Closing findings matters more than finding them. Track them over time:
-time-to-fix, ageing of open items, and what changed since the last scan (evidence
-for measure f, effectiveness):
-
-```bash
-penthera https://myapp.com --history reports/history.json -o reports/scan.json
-```
-
-Each run folds the current findings into a small history keyed by a **stable
-fingerprint** (so a re-worded or re-counted finding isn't mistaken for a new
-one), then reports open vs resolved, median time-to-fix, and ageing buckets.
-Re-run on a cadence to watch the trend.
-
-### Supplier rating (passive)
-
-Assess your suppliers' public security posture for supply-chain risk (measure d):
-
-```bash
-printf 'supplier1.com\nsupplier2.com\n' > suppliers.txt
-penthera --suppliers suppliers.txt
-```
-
-**Strictly passive and public-data-only.** One homepage GET (security headers),
-a TLS handshake (certificate), and public DNS lookups (SPF/DMARC/MX) per domain.
-No endpoint discovery, no auth probes, no intrusive testing. You get a
-red/amber/green rating per supplier. It's a screening aid for your own vendor
-risk assessment, **not** an authorised penetration test of the supplier.
-
-Because the mapping targets the NIS2 directive itself, it applies across the
-national transpositions; jurisdiction-specific profiles (NL, BE) are on the roadmap.
-
----
-
-## Ethical use & authorization
-
-Penthera sends HTTP requests to the targets you give it. Some modes (`--deep`,
-`--fuzz`, `--all`) send attack payloads designed to find vulnerabilities. Use it
-responsibly.
-
-**You may use Penthera when:**
-
-- You **own** the target (your app, your server, your project).
-- You have **written authorization** from the system owner (email, ticket, signed scope).
-- You scan **localhost** or private lab environments you control.
-- You use it for **defensive security**: research, coursework, CI hardening, pre-release audits.
-
-**You must not use Penthera to:**
-
-- Scan systems you do not own or lack explicit permission to test.
-- Probe government, healthcare, financial, or third-party production systems without authorization.
-- Exfiltrate data, disrupt services, or bypass access controls.
-- Use findings to attack, extort, or harm anyone.
-
-> Before scanning any URL that is not localhost, confirm you have permission.
-> **When in doubt, do not scan.**
-
-Unauthorized security testing may violate computer-misuse laws (for example the US
-CFAA, the UK Computer Misuse Act, and EU national equivalents) and can result in
-criminal prosecution, civil liability, IP blocking, account termination, and
-academic or professional penalties.
-
----
-
-## Disclaimer
-
-Penthera is provided for legitimate security research and defensive testing of
-systems you own or are authorized to test, and for that purpose only.
-
-- It is a research and self-assessment tool. Scan your own apps to find and fix
-  weaknesses before attackers do.
-- The same capabilities that harden a system can cause harm if pointed at someone
-  else's. Use it carefully and lawfully.
-- The author does not condone unauthorized or malicious use, and accepts no
-  liability for any damage, loss, or legal consequence arising from use or misuse
-  of this software.
-- The software is provided "as is", without warranty of any kind. See [LICENSE](LICENSE) (MIT).
-- You are solely responsible for ensuring every scan you run is authorized and
-  legal in your jurisdiction.
-
-By using Penthera you accept these terms.
-
----
-
-## Install
-
-The [one-line installer](#run-it) is the fastest path. To set it up manually:
-
-```bash
-git clone https://github.com/danoszz/penthera.git
-cd penthera
-npm install
-npm link            # exposes `penthera` and `penthera-scan` globally
-penthera --version
-```
-
-Requirements: Node.js 18+ and npm. Optional: nuclei-templates for `--nuclei`, and
-Docker. To run it in a container:
-
-```bash
-docker build -t penthera .
-docker run --rm penthera https://your-app.example
-```
-
----
-
 ## Quick start
 
 ```bash
@@ -476,19 +273,100 @@ Fixes come from a [remediation playbook](skills/penthera/references/remediation.
 
 ---
 
+## Compliance: NIS2 and the cyberwetgeving
+
+Shipping in the EU? NIS2 (the Cyberbeveiligingswet in the Netherlands, the
+NIS2-wet in Belgium) puts a duty of care on in-scope organisations. Penthera
+turns the technical, testable part of that duty into repeatable evidence, and
+helps with the paperwork around it. Offline, no accounts.
+
+| Command | What you get |
+|---------|--------------|
+| `--framework nis2` | Per-run Article 21(2) coverage table in every report |
+| `--readiness --assessment a.json` | Full readiness report: every measure marked met / partial / gap |
+| `--questionnaire questions.txt` | Customer security questionnaire drafted from your evidence |
+| `--policy-pack ./policies` | Proportionate policy templates, prefilled from your gaps |
+| `--incident incident.json` | 24h / 72h / 1-month incident report drafts and deadlines |
+| `--sbom sbom.cdx.json` | CycloneDX software bill of materials |
+| `--history history.json` | Time-to-fix, ageing, and drift across scans |
+| `--suppliers suppliers.txt` | Passive red/amber/green rating of your suppliers |
+
+**Full guide, the measure-by-measure coverage table, and the limits:**
+[docs/compliance-nis2.md](docs/compliance-nis2.md).
+
+> Readiness tooling, not a certification and not legal advice.
+
+---
+
 ## CI integration
 
 ```yaml
 # Scan a staging URL on a schedule and upload results to GitHub Security.
-# Set the PENTEST_STAGING_URL secret to enable. Full example: .github/workflows/scan.yml
-- run: npx penthera "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
-- uses: github/codeql-action/upload-sarif@v3
+- run: npx penthera@1.2.0 "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
+- uses: github/codeql-action/upload-sarif@v4
   with:
     sarif_file: reports/scan.sarif
 ```
 
-The repo's own CI (`.github/workflows/ci.yml`) runs the offline suites on Node 18,
-20, and 22, and self-scans a mock vulnerable API on every push.
+Copy the full workflow from
+[`docs/examples/github-actions-scan.yml`](docs/examples/github-actions-scan.yml)
+into your app's repo. Pin the Penthera version so a scheduled run never picks up
+code you have not reviewed.
+
+Penthera's own CI runs the full test suite on Node 22 and 24, self-scans a mock
+vulnerable API on every push, and runs CodeQL and OpenSSF Scorecard.
+
+---
+
+## Ethical use & authorization
+
+Penthera sends HTTP requests to the targets you give it. Some modes (`--deep`,
+`--fuzz`, `--all`) send attack payloads designed to find vulnerabilities. Use it
+responsibly.
+
+**You may use Penthera when:**
+
+- You **own** the target (your app, your server, your project).
+- You have **written authorization** from the system owner (email, ticket, signed scope).
+- You scan **localhost** or private lab environments you control.
+- You use it for **defensive security**: research, coursework, CI hardening, pre-release audits.
+
+**You must not use Penthera to:**
+
+- Scan systems you do not own or lack explicit permission to test.
+- Probe government, healthcare, financial, or third-party production systems without authorization.
+- Exfiltrate data, disrupt services, or bypass access controls.
+- Use findings to attack, extort, or harm anyone.
+
+> Before scanning any URL that is not localhost, confirm you have permission.
+> **When in doubt, do not scan.**
+
+Unauthorized security testing may violate computer-misuse laws (for example the US
+CFAA, the UK Computer Misuse Act, and EU national equivalents) and can result in
+criminal prosecution, civil liability, IP blocking, account termination, and
+academic or professional penalties.
+
+---
+
+## Install
+
+The [one-line installer](#run-it) is the fastest path. To set it up manually:
+
+```bash
+git clone https://github.com/danoszz/penthera.git
+cd penthera
+npm install
+npm link            # exposes `penthera` and `penthera-scan` globally
+penthera --version
+```
+
+Requirements: Node.js 22+ and npm. Optional: nuclei-templates for `--nuclei`, and
+Docker. To run it in a container:
+
+```bash
+docker build -t penthera .
+docker run --rm penthera https://your-app.example
+```
 
 ---
 
@@ -513,6 +391,10 @@ npm run pentest:mock     # offline tests against a local mock vuln API
 npm run mock-server      # start the mock API on port 8765
 ```
 
+See the [roadmap](ROADMAP.md) for what is next, including auditing the skills,
+MCP servers, and plugins in your AI toolchain, and what is deliberately not
+planned.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the project layout, how to add a probe
 or template, the test matrix, and the release and publishing checklist.
 
@@ -520,7 +402,7 @@ or template, the test matrix, and the release and publishing checklist.
 
 ## Status
 
-**v1.0, production-ready.** URL, repo, and machine scanning, scan profiles,
+**v1.2, production-ready.** URL, repo, and machine scanning, NIS2 readiness tooling, scan profiles,
 Markdown, JSON, and SARIF reports, session-aware auth, JWT, IDOR, OAuth, and
 header probes, adaptive knowledge-graph probing, a plugins and templates API,
 Docker, CI, and the Agent Skill are all shipped. See the [CHANGELOG](CHANGELOG.md)
@@ -555,6 +437,26 @@ You are responsible for ensuring you are authorized to scan any target. See [Eth
 
 ---
 
+## Disclaimer
+
+Penthera is provided for legitimate security research and defensive testing of
+systems you own or are authorized to test, and for that purpose only.
+
+- It is a research and self-assessment tool. Scan your own apps to find and fix
+  weaknesses before attackers do.
+- The same capabilities that harden a system can cause harm if pointed at someone
+  else's. Use it carefully and lawfully.
+- The author does not condone unauthorized or malicious use, and accepts no
+  liability for any damage, loss, or legal consequence arising from use or misuse
+  of this software.
+- The software is provided "as is", without warranty of any kind. See [LICENSE](LICENSE) (MIT).
+- You are solely responsible for ensuring every scan you run is authorized and
+  legal in your jurisdiction.
+
+By using Penthera you accept these terms.
+
+---
+
 ## License & disclosure
 
 MIT. See [LICENSE](LICENSE). Report vulnerabilities in Penthera itself via

package/SECURITY.md

@@ -2,21 +2,43 @@
 
 ## Supported versions
 
+Security fixes land on the latest minor release only. Upgrade to get them.
+
 | Version | Supported |
 | ------- | --------- |
-| 1.0.x   | Yes       |
-| < 1.0   | No        |
+| 1.2.x   | Yes       |
+| < 1.2   | No        |
 
 ## Reporting a vulnerability
 
 If you find a security issue in **Penthera itself** (not a finding produced by
 scanning a target), please report it privately:
 
-1. Open a [GitHub Security Advisory](https://github.com/danoszz/penthera/security/advisories/new), or
-2. Email the repository owner with a clear description and reproduction steps.
+1. Open a [GitHub Security Advisory](https://github.com/danoszz/penthera/security/advisories/new)
+   (preferred: it keeps the report private and lets us credit you), or
+2. Email the maintainer via the address on the [GitHub profile](https://github.com/danoszz)
+   with a clear description and reproduction steps.
+
+Please do **not** open public issues for undisclosed vulnerabilities.
+
+**What to expect.** Penthera is maintained part-time, but security reports come
+first:
+
+- Acknowledgement within 3 working days.
+- An initial assessment (accepted, needs more info, or out of scope) within 10
+  working days.
+- A fix or mitigation for accepted issues as fast as severity warrants, followed
+  by a release, a GitHub advisory, and credit to you unless you prefer otherwise.
+
+**In scope:** the CLI, the scanner engine (`lib/`, `src/`), the Agent Skill
+(`skills/penthera/`), the installer (`install.sh`), and the published npm package
+and its build pipeline. Examples: code execution from a malicious scan target or
+repo, a skill instruction that bypasses the authorization gate, a supply-chain
+weakness in our release workflow.
 
-Please do **not** open public issues for undisclosed vulnerabilities. We aim to
-acknowledge reports within a few days.
+**Safe harbor.** Good-faith research on Penthera's own code, done on your own
+machine, is welcome and we will not pursue action against it. This does not
+cover scanning third-party systems: the authorization rules below still apply.
 
 ## Responsible use