Penthera

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.

Start in 30 seconds

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

Building with Cursor, Claude Code, Codex, VS Code, Windsurf, Gemini CLI, Zed, JetBrains or Kiro, or an app builder such as Lovable, Bolt, Base44, Replit or v0? Penthera in your coding tool has the setup for each.

In your terminal. Run this in your project folder:

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

In your coding agent. Pick yours, then ask "scan my app for security issues". The MCP lines pin the version.

The skill tells your agent how to run Penthera; the MCP server gives it six read-only tools. More routes: skill.md, mcp.md.

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

Public benchmarks

We test Penthera on public datasets that other people built, next to the free open-source tools that do the same job, scored the same way. Each dataset was split in half before we looked: we improved Penthera on one half and scored it once on the other, sealed half. The rules for scoring and ranking were written down before that run (protocol).

⁴ A tied range is a rank interval: the range Penthera's rank fell in, in 95% of 10,000 bootstrap redraws of each tool's counts (on SecBench.js, of its 64 test bugs). Penthera alone came out first in 76% of the redraws on npm, 82% on PyPI and 60% on SecBench.js. Exploratory: computed after the registered ranking.

Leaked secrets: 2nd by F1, the registered score; 1st by F0.5, which weighs precision more (0.82 against deepsecrets 0.80); 2nd by F2, which weighs recall more (0.68 against deepsecrets 0.77).

Some ranked tools are barely in the contest. Other ranked tools scoring below 0.10: 1 of 9 on CredData (trufflehog); 3 of 5 on npm (clamav, yara, ossgadget); 4 of 7 on PyPI (clamav, ossgadget, bandit4mal, aura); 1 of 7 on SecBench.js (njsscan).

If 1 package in 1,000 were malicious, the share of Penthera's malware flags that would be right: npm, about 2.7% at the top of the false-alarm interval (it raised no false alarm on that sample); PyPI, about 1.6% at the measured false-alarm rate, 0.9% at the top of its interval. Exploratory, like the rank intervals.

What these numbers do not show: a benchmark is not your code. CredData replaces real secrets with look-alikes, which favors pattern rules like ours over tools that verify keys; the free tools ran on their defaults while Penthera was tuned on the other half; GuardDog helped build the malware dataset. Accuracy on real projects is experiment E1. To reproduce every table, get the sealed split with npm run bench:public -- --fetch-split, then run npm run bench:public -- --split test --final and npm run bench:public -- --competitors --split test --final.

What it does

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

For the full black-box and white-box view, see Under the hood.

Before you deploy

What you build with

After you ship

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/. Compliance output is readiness tooling, not a certification and not legal advice.

AI mode (opt-in). 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).

How far each part has been taken

Under the hood

For developers and security specialists: the diagram above, as the code runs it. Black box tests the running app over HTTP. White box reads the code and config. Opt-in items say so. The limits of each part, such as what IDOR/BOLA or taint-lite can and cannot tell, are in METHODOLOGY.md.

flowchart LR    APP["Your running app<br/>penthera URL"]
    subgraph DEF["Default: no attack payloads"]        B1["Transport and headers<br/>TLS certificate, ciphers<br/>security headers, CSP<br/>cookie flags, CORS"]        B2["Discovery<br/>wordlist routes<br/>OpenAPI spec<br/>hidden parameters<br/>exposed files, templates"]        B3["Auth<br/>one invalid login POST<br/>JWT, with --auth-bearer<br/>OAuth redirect<br/>client-side auth<br/>IDOR/BOLA: human review"]        B4["Versions and leaks<br/>JS libraries, Retire.js<br/>keys in JS bundles<br/>server version advisories<br/>SPF and DMARC"]    end
    subgraph OPT["Opt-in"]        B5["No payloads<br/>--recon: crt.sh,<br/>Wayback, OTX<br/>--templates: Nuclei YAML"]        G{{"Gate<br/>type the hostname back<br/>or --confirm-target<br/>10 requests a second"}}        B6["Active<br/>--deep: SQLi, SSTI,<br/>SSRF, XSS, CMDi,<br/>open redirect,<br/>login burst<br/>--fuzz, --adaptive"]    end
    APP --> B1 & B2 & B3 & B4 & B5    APP --> G --> B6    B1 & B2 & B3 & B4 & B5 & B6 --> F[["Findings"]]
    classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff    classDef box fill:#ffffff,stroke:#000000,color:#000000    classDef gate fill:#ffffff,stroke:#0000ed,color:#000000,stroke-width:2px    class F core    class APP,B1,B2,B3,B4,B5,B6 box    class G gate    style DEF fill:none,stroke:#0000ed,stroke-width:2px    style OPT fill:none,stroke:#0000ed,stroke-width:2px,stroke-dasharray:6 4

flowchart LR    REPO["Your code<br/>and config"]
    subgraph RS["penthera --repo ."]        W1["Secrets<br/>provider key formats<br/>.gitignore aware<br/>code, config, HCL,<br/>notebooks"]        W2["Routes and boundaries<br/>Next.js, Express,<br/>Hono, Fastify<br/>auth per route<br/>risky patterns"]        W3["Code sinks, taint-lite<br/>eval, new Function,<br/>node:vm, shell exec<br/>with request data<br/>one file, no call graph"]        W4["Library mode<br/>exported parameters<br/>count as untrusted"]        W5["CI and runtimes<br/>Actions: pwn request,<br/>script injection,<br/>unpinned actions<br/>runtime pin advisories"]    end
    subgraph OWN["Their own commands"]        W6["penthera deps<br/>npm, requirements,<br/>poetry, uv, Pipfile,<br/>pdm, .venv<br/>capabilities, IOC packs<br/>typosquats, licenses<br/>upgrade diff"]        W7["penthera agents<br/>MCP servers, hooks<br/>skills, plugins<br/>permissions, rule files<br/>hidden content<br/>penthera.lock pins"]        W8["Before code lands<br/>penthera install<br/>penthera hook"]    end
    REPO --> W1 & W2 & W3 & W4 & W5 & W6 & W7 & W8    W1 & W2 & W3 & W4 & W5 & W6 & W7 & W8 --> F[["Findings"]]
    classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff    classDef box fill:#ffffff,stroke:#000000,color:#000000    class F core    class REPO,W1,W2,W3,W4,W5,W6,W7,W8 box    style RS fill:none,stroke:#0000ed,stroke-width:2px    style OWN fill:none,stroke:#0000ed,stroke-width:2px

flowchart LR    subgraph ENG["Engine: rules decide"]        R["Signed rule packs<br/>core, advisories, IOC<br/>SSH signature, SHA-256<br/>ship in the release"]        GI["--giants, opt-in<br/>gitleaks, TruffleHog,<br/>Semgrep, osv-scanner,<br/>Trivy, Checkov,<br/>nuclei, ZAP baseline<br/>if installed, no shell"]        AI["--ai, opt-in<br/>an Ollama model proposes<br/>asks consent every run"]        OFF["Offline by design<br/>no telemetry<br/>no rule downloads"]    end
    R --> FD[["Finding<br/>severity<br/>confidence: confirmed,<br/>likely, potential,<br/>needs-human-review<br/>file:line or URL"]]    GI --> FD    AI -. "a rule must confirm" .-> FD    FD --> EX{"Exit code<br/>0 none critical or high<br/>1 critical or high<br/>2 incomplete or refused"}
    subgraph OUT["Outputs and integrations"]        O1["Reports<br/>terminal, JSON,<br/>Markdown, SARIF<br/>audience reports<br/>agent brief"]        O2["penthera ui<br/>dashboard on 127.0.0.1"]        O3["penthera mcp<br/>six read-only tools"]        O4["GitHub Action<br/>PR capability diff<br/>SARIF upload"]        O5["Vercel Deployment Check<br/>relays the Action result"]        O6["Evidence bundle<br/>SHA-256 manifest<br/>SSH signature<br/>SBOM, AI-BOM<br/>NIS2 and CRA drafts"]    end
    EX --> O1 & O2 & O3 & O4 & O5 & O6
    classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff    classDef box fill:#ffffff,stroke:#000000,color:#000000    class FD core    class R,GI,AI,OFF,EX,O1,O2,O3,O4,O5,O6 box    style ENG fill:none,stroke:#0000ed,stroke-width:2px    style OUT fill:none,stroke:#0000ed,stroke-width:2px

How it is measured

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

• Method. The methodology 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: 158 verified references, in APA style, in 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/ 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.

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. Refresh the counts with npm run docs:numbers and npm run bench.

Cite this repository with the button on GitHub or CITATION.cff. APA and BibTeX forms are in the methodology.

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).
• Tested unplugged. Repo scans, agents, deps, brief, evidence bundles and URL scans with --offline made no outside connections. They gave the same result twice, and the same with the network blocked, on macOS and Ubuntu (E17 results). The test can't watch git, which Penthera uses only for local commands.
• 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, --adaptive, --all) is opt-in, asks for a confirmation bound to the target, and is rate-limited. It can change data, so read what active modes can change first.
• 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. 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 of eight gates (latest report).

The claim map ties these claims to the tests that hold them.

Verify it yourself. In an empty folder:

npm install [email protected] && npm audit signaturesnpx [email protected] rules list

The first checks npm's registry signature and the build provenance of the package you got. The second lists every bundled rule pack and the key that signed it; a pack whose signature does not verify is refused unless you pass --allow-unsigned-rules.

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.

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.

All comparisons, including Cloudflare's security-audit skill: docs/compare/.

Run the free tools you already have: --giants

--giants runs the free scanners installed on your machine after Penthera's own scan: gitleaks, TruffleHog, Semgrep with your local rules, osv-scanner, Trivy and Checkov for a repository, nuclei and the ZAP baseline for a URL. Their findings go into the same report and SARIF, each labelled with the tool, its version and its rule. Nothing is downloaded or uploaded, and an area that neither Penthera's rules nor another tool reached is reported as "not covered".

penthera giants              # which tools you havepenthera --repo . --giants   # Penthera, then each installed tool

This runs the tools you have and merges their findings. It is not a claim that the combination finds more: experiment E14 measured that (results). Details, safety rules and the policy key: docs/commands/giants.md.

Start here

The full map, by situation and from first scan to research, is in docs/index.md.

Ethics and authorization

Penthera sends HTTP requests to the targets you give it, and some modes (--deep, --fuzz, --adaptive, --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.

Building in public

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

[Star history]

[Walkthrough video: setup, a scan, the dashboard in Simple and Advanced mode, one fix approved, the report]

Watch the 80-second walkthrough: setup, a scan, the dashboard, a fix approved, the report. Demo data, no sound, captions in the video.

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.

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 an AI-Assisted: 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.

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 covers the project layout, the release cadence and the release checklist; AGENTS.md is the short version for coding agents. The roadmap shows what ships next, and the research plan what we measure. Issues and pull requests are welcome.

Penthera is free and stays free. If it caught something before you shipped it, you can sponsor its maintenance. Sponsorship pays for maintainer time and buys no influence over findings (tiers).

License

MIT. See LICENSE. Report vulnerabilities in Penthera itself through SECURITY.md.