penthera 1.1.0

package/README.md

@@ -0,0 +1,561 @@
+<div align="center">
+
+<img src="assets/penthera-social.jpg" alt="Penthera, a security scanner for Claude, Cursor and CLI" width="840">
+
+<br/><br/>
+
+![version](https://img.shields.io/badge/version-1.1.0-0000ed)
+![node](https://img.shields.io/badge/node-%E2%89%A518-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)
+
+<br/>
+
+<img src="assets/demo.gif" alt="Penthera running an interactive security scan in the terminal" width="760">
+
+</div>
+
+---
+
+## Two ways to use it
+
+**As an Agent Skill (recommended).** Most people start here. Let Cursor or Claude
+Code drive it: [install once](#run-it), then ask it to "scan my app for security
+issues." The agent picks the scan, runs it, and gives you the fixes.
+
+**As a CLI.** Prefer the terminal? Run `penthera https://myapp.com`, or just
+`penthera` for the guided wizard. See the [quick start](#quick-start).
+
+---
+
+## Why Penthera
+
+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.
+
+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
+the top fixes in priority order. You do not need a DAST suite or a security
+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).
+
+---
+
+## Run it
+
+**One-line install** (clones the repo, links the CLI, and installs the skill into
+Cursor and Claude Code if it finds them):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/danoszz/penthera/main/install.sh | bash
+```
+
+**Or via the Agent Skills CLI** (Cursor, Claude Code, and [40+ agents](https://agentskills.io/clients)):
+
+```bash
+npx skills add danoszz/penthera
+```
+
+Then talk to your agent:
+
+```
+"Scan my localhost:3000 for security issues"
+"Run a pre-deploy security audit on staging.myapp.com"
+"Find hardcoded secrets in this repo before I push"
+```
+
+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
+> you do not own or are not authorized to test.
+
+---
+
+## What it does
+
+| 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 |
+| **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) |
+
+Pick a profile, or add individual flags for more depth:
+
+| Profile | Command | What runs |
+|---------|---------|-----------|
+| **quick** | `--profile quick` | Headers, OpenAPI, auth smoke tests (about 10s) |
+| **standard** | *(default)* | Full non-destructive scan |
+| **deep** | `--profile deep` | recon, injection probes, and API fuzzing |
+
+Individual flags: `--recon`, `--deep`, `--fuzz`, `--adaptive`, `--nuclei <path>`, `--templates <dirs>`, `--all`
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+    U["You / your AI agent"] -->|scan request| P((Penthera))
+
+    P --> BB["Black-box<br/>TLS, headers, CORS<br/>endpoint + OpenAPI discovery<br/>JWT, auth, IDOR/OAuth<br/>injection, fuzzing"]
+    P --> WB["White-box<br/>API routes<br/>secret scanning<br/>trust boundaries"]
+    P --> MA["Machine audit<br/>(macOS)"]
+
+    BB --> F[["Findings<br/>scored by severity"]]
+    WB --> F
+    MA --> F
+
+    F --> T["Terminal summary<br/>+ top 3 fixes"]
+    F --> MD["Markdown report"]
+    F --> J["JSON"]
+    F --> S["SARIF to GitHub Security"]
+```
+
+Findings map to the [OWASP Web Security Testing Guide](docs/owasp-wstg-coverage.md)
+(WSTG v4.2). The default scan is non-destructive. Payload-based testing is opt-in
+(`--deep`, `--fuzz`, `--all`) and gated behind explicit confirmation.
+
+---
+
+## 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
+# First time? Run with no args for guided setup
+penthera
+
+# Safe default scan (non-destructive)
+penthera https://myapp.com
+
+# Staging plus source code, full report set
+penthera https://staging.myapp.com --repo . --all -o reports/scan.json --sarif reports/scan.sarif
+
+# Baseline diff: show only new findings since the last scan
+penthera https://myapp.com -o reports/scan.json --baseline reports/previous.json
+
+# Authenticated scan (session cookie or bearer token)
+PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard
+penthera https://myapp.com --auth-cookie "session=abc123"
+```
+
+Writing to `-o reports/scan.json` also drops a human-readable `reports/scan.md`
+next to it. Reports are gitignored by default.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No critical or high findings |
+| `1` | Critical or high findings detected |
+| `2` | Scan failed (unreachable target, bad config) |
+
+---
+
+## Output
+
+| Format | Flag | Use |
+|--------|------|-----|
+| Terminal | *(default)* | Colored summary plus top 3 fixes |
+| **Markdown** | `--markdown file.md` or `-o file.json` | Human-readable report (exec summary, findings tables, fixes). Written next to `-o` automatically |
+| JSON | `--json` or `-o file.json` | CI pipelines, baseline diffs, custom tooling |
+| SARIF | `--sarif file.sarif` | GitHub Security / Code Scanning tab |
+
+---
+
+## For your AI coding agent
+
+Penthera ships as an [Agent Skill](https://agentskills.io), the open format used
+by Cursor, Claude Code, Claude.ai, and [40+ agent tools](https://agentskills.io/clients).
+The skill teaches an agent to run authorized scans, pick the right profile, and
+summarize findings, so you can just describe what you want.
+
+**Install** (any of these):
+
+```bash
+# Cross-agent, frictionless
+npx skills add danoszz/penthera
+
+# Or the one-line installer (also links the CLI)
+curl -fsSL https://raw.githubusercontent.com/danoszz/penthera/main/install.sh | bash
+
+# Or copy into a single project for team sharing
+cp -r skills/penthera .cursor/skills/penthera     # Cursor
+cp -r skills/penthera .claude/skills/penthera     # Claude Code
+```
+
+Or as a Claude Code plugin (installs the skill):
+
+```bash
+/plugin marketplace add danoszz/penthera
+/plugin install penthera@penthera
+```
+
+For Claude.ai (web), zip and upload the skill:
+
+```bash
+npm run package:skill   # produces penthera-skill.zip; upload in Settings > Capabilities > Skills
+```
+
+**Prompts that trigger it:**
+
+- "Scan my localhost app on port 3000 for security issues"
+- "Run a pre-deploy audit on staging.myapp.com and summarize critical findings"
+- "Scan this repo for hardcoded secrets and exposed API routes"
+- "Compare today's scan to last week's baseline and show only new findings"
+- "Generate a SARIF report for GitHub code scanning"
+
+The skill adds an authorization gate: it instructs the agent to refuse targets you
+do not own or are not authorized to test, and the wizard asks you to confirm before
+scanning a remote host. It is an agent-level and interactive safeguard, not something
+the raw CLI enforces. You are responsible for every target you pass it. Run preflight
+before the first scan:
+
+```bash
+bash skills/penthera/scripts/preflight.sh http://localhost:3000
+```
+
+Skill source and workflows live in [`skills/penthera/SKILL.md`](skills/penthera/SKILL.md).
+
+---
+
+## Scan and fix
+
+Penthera does not just report problems. It closes the loop: ask your agent to fix what it finds, and it detects the issue, applies a framework-aware fix to your code (shown as a diff for you to approve), and re-scans to prove it is resolved.
+
+```
+"Scan my app and fix what you find"
+"Fix the security headers on my Next.js app and re-scan to confirm"
+"Find and fix hardcoded secrets in this repo"
+```
+
+Fixes come from a [remediation playbook](skills/penthera/references/remediation.md) covering Next.js, Express, Fastify, Hono, and FastAPI. They are always shown as diffs for your approval and verified by a re-scan; nothing is applied blindly, and nothing touches production. To build secure-by-default in the first place, see [secure defaults](skills/penthera/references/secure-defaults.md).
+
+---
+
+## 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
+  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.
+
+---
+
+## Configuration
+
+For live integration tests against your own routes:
+
+```bash
+cp pentest.config.example.js pentest.config.js   # gitignored
+```
+
+Edit the route groups, then run `npm run pentest:live`. Set `PENTEST_BASE_URL` to
+point at staging without editing the file.
+
+---
+
+## Testing & contributing
+
+```bash
+npm test                 # full suite (live integration tests skip without a running target)
+npm run pentest:mock     # offline tests against a local mock vuln API
+npm run mock-server      # start the mock API on port 8765
+```
+
+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.
+
+---
+
+## Status
+
+**v1.0, production-ready.** URL, repo, and machine scanning, 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)
+for the full history.
+
+Penthera is actively maintained. Issues and PRs welcome.
+
+---
+
+## Support Penthera
+
+Penthera is free and MIT-licensed. If it caught something before you shipped it,
+you can help keep it maintained:
+
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub-db61a2?logo=githubsponsors)](https://github.com/sponsors/danoszz)
+
+Sponsorship funds new probes, broader framework coverage, and keeping the suite
+current with new attack patterns. Thank you.
+
+---
+
+## Privacy
+
+Penthera has no telemetry. It does not collect, store, or transmit any usage data, analytics, or personal information to the author or any third party. It does not phone home.
+
+- **Scan traffic goes only to the target you specify.** Auth tokens passed via `--auth-bearer`, `--auth-cookie`, or `PENTHERA_*` env vars are sent only to that target.
+- **Reports stay local.** Output is written to `reports/` (gitignored) on your machine.
+- **JS vulnerability checks** download a public database (Retire.js) from GitHub to compare your app's libraries against known CVEs locally. No details about your target are sent.
+- **Recon mode** (`--recon`) queries public OSINT sources (crt.sh, web.archive.org, AlienVault OTX) with the target domain to find subdomains and historical URLs. This shares the target domain with those third-party services. Omit `--recon` to avoid it.
+
+You are responsible for ensuring you are authorized to scan any target. See [Ethical use](#ethical-use--authorization).
+
+---
+
+## License & disclosure
+
+MIT. See [LICENSE](LICENSE). Report vulnerabilities in Penthera itself via
+[SECURITY.md](SECURITY.md). Only scan systems you own or are authorized to test.

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 1.0.x   | Yes       |
+| < 1.0   | 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.
+
+Please do **not** open public issues for undisclosed vulnerabilities. We aim to
+acknowledge reports within a few days.
+
+## Responsible use
+
+Penthera sends HTTP requests to targets you specify. Some modes (`--deep`,
+`--fuzz`, `--all`, `--profile deep`) send **attack payloads** (SQLi, SSTI, SSRF,
+XSS, command injection, API fuzzing).
+
+**Only scan systems you own or have explicit written permission to test.**
+Unauthorized scanning may be illegal in your jurisdiction. Penthera is built for
+defensive research and hardening your own applications — see the full
+[ethical-use policy](README.md#ethical-use--authorization) and
+[disclaimer](README.md#disclaimer) in the README.

package/bin/penthera.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+run();

package/bin/scan.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Interactive scan — delegates to PostHog-style onboarding wizard.
+ * Alias: penthera-scan
+ */
+import { runOnboarding } from "../src/cli/onboarding.js";
+
+runOnboarding().catch((e) => {
+  console.error(e.message);
+  process.exit(2);
+});

package/docs/index.md

@@ -0,0 +1,60 @@
+# Penthera documentation
+
+Lightweight security scanner for developers, scan live URLs, local repos, or macOS machines from the CLI.
+
+## Getting started
+
+| Guide | Description |
+|-------|-------------|
+| [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 |
+
+## Scanning
+
+| Topic | Link |
+|-------|------|
+| Scan profiles | `quick` · `standard` · `deep`, see `--profile` in `penthera --help` |
+| Authenticated scans | `--auth-cookie`, `--auth-bearer`, `PENTHERA_BEARER` env |
+| Adaptive probes | `--adaptive`, knowledge-graph-driven escalation on live routes |
+| Custom templates | `--templates ./my-templates`, Nuclei-compatible YAML dirs |
+| Baseline diff | `--baseline reports/previous.json` |
+
+## Reports
+
+| Format | Flag |
+|--------|------|
+| Markdown | `-o report.json` (auto `.md`) or `--markdown report.md` |
+| JSON | `-o report.json` or `--json` |
+| SARIF | `--sarif results.sarif`, GitHub Security tab |
+
+## Standards & CI
+
+| Topic | Link |
+|-------|------|
+| OWASP WSTG mapping | [owasp-wstg-coverage.md](./owasp-wstg-coverage.md) |
+| GitHub Actions CI | `.github/workflows/ci.yml` (mock scan + SARIF) |
+| Staging scans | `.github/workflows/scan.yml`, set `PENTEST_STAGING_URL` secret |
+| Docker | `docker build -t penthera . && docker run penthera https://localhost:3000` |
+
+## Agent skill
+
+| Topic | Location |
+|-------|----------|
+| Skill files | `skills/penthera/SKILL.md` |
+| Preflight | `bash skills/penthera/scripts/preflight.sh [URL]` |
+| Validate report | `npm run validate:report -- reports/scan.json` |
+| Release zip | `npm run package:skill` |
+
+## Programmatic API
+
+```javascript
+import { loadTemplatesFromPaths, runTemplateScan } from "penthera/plugins";
+import { runAdaptiveProbes } from "penthera/adaptive";
+```
+
+See `lib/plugins.js` and `lib/blackbox/adaptive-scan.js` for exports shipped in the npm package.
+
+## Security
+
+Report vulnerabilities in Penthera via [SECURITY.md](../SECURITY.md). Only scan systems you own or have authorization to test.