Offline, rule-based security checks for your repo, dependencies, AI agent config and local app.
io.github.danoszz/penthera — Model Context Protocol (MCP) Server
The io.github.danoszz/penthera MCP server runs offline, rule-based security checks for a repository, its dependencies, AI agent configuration, and a local application. It focuses on assessing code and configuration inputs without requiring network-based analysis.
🛠️ Key Features
Offline operation
Rule-based security checks
Coverage for repos, dependencies, AI agent config, and local apps
🚀 Use Cases
Validate repository security using predefined rules
Check dependency security for the project
Review AI agent configuration for potential issues
Scan a local application’s security posture
⚡ Developer Benefits
Deterministic, rules-driven evaluation across multiple target types
Works for repository and local application contexts
⚠️ Limitations
Described as offline and rule-based; no additional scanning methods are specified
New in 2.4:penthera --card makes a security receipt of your repo to post, every surface counts one set of problems with the same words, and 13 ways to hide a finding or stall a scan are closed (what changed).
From your coding agent: add Penthera (one line per agent), then say "Hey Claude, run Penthera on this repo."
132 readable rules · 6 read-only MCP tools · 0 runtime dependencies · 0 requests past loopback in the benchmark · MIT, no telemetry
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:
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).
In your coding agent. Pick yours, then ask "scan my app for security
issues". The MCP lines pin the version.
Agent
Run this
Claude Code, plugin (skill only, runs the CLI)
claude plugin marketplace add danoszz/penthera, then claude plugin install penthera@penthera
Claude Code, MCP server only
claude mcp add penthera -- npx -y penthera@2.4.0 mcp
The skill tells your agent how to run Penthera; the MCP server gives it six
read-only tools. More routes: skill.md,
mcp.md.
Where AI fits. Rules decide every finding and every exit code. A model may
only propose:
Role
Who
How
Decides
Penthera's rules, always
Every finding, every exit code
Looks further (optional)
A model, with --ai
Proposes problems no rule describes; the rules check each one, and unchecked ones are listed apart and never fail CI (AI mode)
Fixes
Your own coding agent
Through the MCP server, the skill or penthera fix --plan
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.
Injection bugs in JavaScript libraries (SecBench.js)
Rank
Tool
Command injection
Code injection
Both
1
Penthera 2.0.0
35/47
10/17
0.70 [0.58, 0.80]
2
odgen c5157ee
36/46
6/16
0.68 [0.55, 0.78]
3
codeql 2.27.2 (used under the GitHub CodeQL terms, for research on open-source code)
37/47
4/17
0.64 [0.52, 0.75]
4
eslint-plugin-security 4.2.0
32/47
9/17
0.64 [0.52, 0.75]
5
semgrep 1.180.0
15/47
9/17
0.38 [0.27, 0.50]
6
graudit 849d7c7
12/47
10/17
0.34 [0.24, 0.47]
7
bearer 2.1.1
14/47
0/17
0.22 [0.14, 0.33]
8
njsscan 1.0.1
2/45
1/15
0.05 [0.02, 0.14]
–
semgrep, every file 1.180.0 (another setting of semgrep, not ranked)
16/47
9/17
0.39 [0.28, 0.51]
–
Penthera 1.9.0
0/47
10/17
0.16 [0.09, 0.26]
A rank is shown only where at least 5 other free tools were measured; otherwise "–". The rank column orders tools by score, and close scores can swap places. Penthera's 95% rank interval (bootstrap, exploratory): 2nd on CredData, 1st to 3rd on npm, 1st to 3rd on PyPI, 1st to 4th on SecBench.js.
Paid tools (GitGuardian, Socket, Snyk, Phylum, Semgrep Pro) publish no results on these benchmarks, so they are not in the tables.
Published elsewhere, on other datasets (context, not comparable):
¹ Not ranked: trained on this dataset by its authors. ² Found most samples in this dataset, so its rate is inflated by construction. ³ Not ranked: a lookup of already-reported packages, not detection.
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<br/>your agent"] --> P(("Penthera<br/>on your machine"))
P --> APP["Your app<br/>live and code"]
P --> DEP["Dependencies<br/>npm and Python"]
P --> AI["AI tooling<br/>skills, MCP, hooks"]
APP & DEP & AI --> F[["Findings<br/>rules decide"]]
F --> FIX["Fix<br/>asks first"]
F --> R["Reports<br/>SARIF, ui, MCP"]
F --> E["Evidence<br/>signed bundle"]
FIX -. "re-scan" .-> F
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
Advanced: black box, the running app over HTTP
The default scan sends no attack payloads. --deep, --fuzz and --adaptive
start only after you confirm the hostname, or pass --confirm-target <host> in
CI. Limits are in METHODOLOGY.md.
%%{init: {"flowchart": {"nodeSpacing": 24, "rankSpacing": 40}}}%%
flowchart LR
APP["Running app<br/>penthera URL"] --> DEF
APP --> ACT
subgraph DEF["Default: no attack payloads"]
direction TB
B1["TLS, headers<br/>cookies, CORS"]
B2["Routes<br/>OpenAPI, files"]
B3["Auth, JWT, OAuth<br/>IDOR: review"]
B4["JS libraries<br/>bundle keys"]
end
subgraph ACT["Opt-in, gated"]
direction TB
A1["--deep<br/>SQLi, XSS, SSRF"]
A2["--fuzz<br/>API bodies"]
A3["--adaptive<br/>may send DELETE"]
end
DEF & ACT --> F[["Findings"]]
classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff
classDef box fill:#ffffff,stroke:#000000,color:#000000
class F core
class APP,B1,B2,B3,B4,A1,A2,A3 box
style DEF fill:none,stroke:#0000ed,stroke-width:2px
style ACT fill:none,stroke:#0000ed,stroke-width:2px,stroke-dasharray:6 4
Advanced: white box, your code and config
Code sinks use taint-lite within one file, with no call graph. Dependency
capabilities are what code can do, not proof it is malicious.
%%{init: {"flowchart": {"nodeSpacing": 24, "rankSpacing": 40}}}%%
flowchart LR
REPO["Code and config"] --> RS
REPO --> OWN
subgraph RS["penthera --repo ."]
direction TB
W1["Secrets<br/>key formats"]
W2["Routes<br/>auth per route"]
W3["Code sinks<br/>eval, vm, exec"]
W4["CI, runtimes<br/>Actions, pins"]
end
subgraph OWN["Own commands"]
direction TB
W5["deps<br/>capabilities, IOCs"]
W6["agents<br/>MCP, skills, hooks"]
W7["install, hook<br/>before it lands"]
end
RS & OWN --> 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 box
style RS fill:none,stroke:#0000ed,stroke-width:2px
style OWN fill:none,stroke:#0000ed,stroke-width:2px
Advanced: engine and outputs, how a match becomes a result
Rules decide every finding. Exit code 0 means nothing critical or high, 1
critical or high, 2 an incomplete or refused scan. Under --ai a model only
proposes.
%%{init: {"flowchart": {"nodeSpacing": 30, "rankSpacing": 40}}}%%
flowchart LR
subgraph IN["Inputs"]
direction LR
R["Signed rule packs"]
GI["--giants, opt-in"]
AI["--ai, opt-in"]
end
IN --> FD[["Finding<br/>severity, confidence"]]
FD --> EX{"Exit<br/>0, 1 or 2"}
EX --> OUT
subgraph OUT["Outputs"]
direction LR
O1["Reports, SARIF"]
O2["penthera ui, MCP"]
O3["Action, Vercel check"]
O4["Evidence bundle"]
end
classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff
classDef box fill:#ffffff,stroke:#000000,color:#000000
class FD core
class R,GI,AI,EX,O1,O2,O3,O4 box
style IN fill:none,stroke:#0000ed,stroke-width:2px
style OUT fill:none,stroke:#0000ed,stroke-width:2px
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)
Shows what every npm and Python package can do (install scripts, shell, network, env, obfuscation), what an upgrade added, lookalike names and licenses
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
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
Part
Status
Scans: URL, repo, dependencies, AI tooling, installs, pre-commit hook
Stable: in every release since 1.x, covered by the tests and the release gate
Fix loop and local dashboard (penthera ui)
Stable; the dashboard was redesigned in 1.9.0
MCP server, Agent Skill, Claude Code plugin
Stable, since 1.9.0
Gemini CLI extension
Stable: it installs the newest release (2.4.0)
Evidence bundles, NIS2 and CRA drafts
Stable as readiness tooling, not a certification
AI mode (--ai)
Experimental: whether it finds more than the rules alone is not measured yet (AI mode)
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.
1st on npm and PyPI malware (tied 1st to 3rd), 1st on JS library injection bugs (tied 1st to 4th), 2nd on leaked secrets
4 public datasets, up to 10 free tools each (results, summary)
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). No run logs in, so it doesn't cover login or access rules
Detection rules, all readable
132 in this release: 16 URL scan templates, 24 secret and AI-key patterns, 15 dependency capabilities, 47 AI-tooling rules, 5 fix recipes, and 25 rules in the signed rule packs
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.
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.
Focus
Where it runs
How it decides
Penthera
Your app, dependencies and AI tooling; fixes; EU evidence
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".
bash
penthera giants # which tools you have
penthera --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.
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.
Where it stands
Read more
Latest release
2.4.0 (2026-11-08) on npm latest: penthera --card makes a security receipt to post, and 13 ways to hide a finding or stall a scan, found by Vercel Security Review, are closed. Crafted files that took seconds to hours now take under a second, and a file too big to finish makes the scan incomplete (exit 2). 2.3.2 brought: hostile files can no longer hang a scan, secrets stay masked in what reports quote
Public benchmarks (E11b) published: on a sealed half of four public datasets, 1st of the free tools on npm and PyPI malware (tied 1st to 3rd), 1st on JS library injection bugs (tied 1st to 4th), 2nd on leaked secrets (summary). 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
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.