penthera 1.7.0 → 1.8.0

package/docs/use-cases/ai-coding-teams.md

@@ -1,81 +0,0 @@
-# The AI-tooling supply chain: for teams adopting Claude Code or Cursor
-
-## The problem
-
-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 of these
-arrive from a teammate's pull request, some from a marketplace, some from a
-blog post. In 2025 and 2026 attackers used exactly 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.
-
-## What to run
-
-```bash
-npx penthera agents --home         # this repo plus your user-level Claude Code, Cursor and Claude Desktop config
-npx penthera agents ./some-skill   # vet a downloaded skill before you install it
-npx penthera agents --pin          # record hashes in penthera.lock; later runs show what changed
-```
-
-For a team, add the pre-commit hook so agent-config changes are checked before
-they are committed, and the GitHub Action in `agents` mode on pull requests:
-
-```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
-```
-
-Each finding names the OWASP MCP Top 10 and Agentic Top 10 ids it maps to, and
-the rule that fired is readable in [`lib/agents/`](../../lib/agents/). The audit
-is offline and read-only: no model judges the skill, so a skill cannot talk its
-way past it. [More on `penthera agents`](../commands/agents.md).
-
-`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. [More on `penthera deps`](../commands/deps.md).
-
-## 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.
-- 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](../compare/socket.md) covers that.
-- Its rules cover the patterns in the [methodology](../METHODOLOGY.md). A new
-  trick needs a new rule and a release.
-
-[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/eu-sme-compliance.md

@@ -1,68 +0,0 @@
-# Evidence for NIS2 and the CRA: for EU SMEs
-
-## The problem
-
-NIS2 puts a duty of care on in-scope organisations, written into national law
-(the Cyberbeveiligingswet in the Netherlands, the NIS2-wet in Belgium). The
-Cyber Resilience Act adds reporting duties for manufacturers of products with
-digital elements, with deadlines measured in hours. Large customers now send
-security questionnaires as part of procurement. A small company has to show
-that it tests, fixes and records, without a compliance team or a budget for a
-platform.
-
-## What to run
-
-```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 an auditor can verify with standard
-tools.
-
-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
-```
-
-## What you get
-
-The CRA helper prints the deadlines and writes draft reports, marking every fact
-it still needs:
-
-```
-CRA Article 14 report drafts written to cra-reports.md
-  Early warning (24 hours): n/a, set aware_at
-  Vulnerability notification (72 hours): n/a, set aware_at
-  Final report (14 days after a corrective or mitigating measure is available): ...
-  ⚠️ No valid `aware_at` timestamp, so deadlines can't be computed. Set when you became aware (ISO 8601) and re-run.
-```
-
-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. Guides:
-[NIS2](../compliance-nis2.md), [CRA](../compliance-cra.md),
-[evidence bundles](../evidence.md).
-
-## 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 advisers
-  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 today; other member states are
-  configuration still to be added.
-
-[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/open-source-maintainers.md

@@ -1,75 +0,0 @@
-# For open-source maintainers
-
-## The problem
-
-Your project is someone else's dependency. A compromised maintainer account, a
-malicious contributor pull request that bumps a lockfile, or a leaked publish
-token can turn it into the attack. Most maintainers do this unpaid, without a
-security budget, and many cannot send their dependency list or code to a vendor
-service, or would rather not sign up for one.
-
-## What to run
-
-On every pull request that touches the lockfile, comment what the change lets
-code do:
-
-```yaml
-- uses: danoszz/penthera@<release-commit-sha> # pin to a release commit
-  with:
-    mode: deps
-    fail-on: none
-```
-
-The full workflow, with permissions and a paths filter, is in
-[`docs/examples/pr-dependency-review.yml`](../examples/pr-dependency-review.yml).
-The action runs Penthera from its own checkout: no install from npm and no
-registry lookups. On pull requests from forks the token is read-only, so the
-diff goes to the job summary instead of a comment.
-
-Locally, before you cut a release:
-
-```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
-```
-
-## What you get
-
-```
-  ▲ 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.
-[More on `penthera deps`](../commands/deps.md) and [the action](../commands/action.md).
-
-If your project ships agent skills or MCP configuration, `penthera agents` on
-your own repo is a reasonable release check too: it is what your users' tools
-will load.
-
-## How Penthera handles its own releases
-
-The same practices are worth copying. Penthera releases are published with npm
-provenance through trusted publishing and are staged: each version waits on npm
-until a maintainer approves it with 2FA. CI actions are pinned by SHA, CodeQL
-runs on every push, and the
-[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera)
-is public. See [`.github/workflows/publish.yml`](../../.github/workflows/publish.yml).
-
-## 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](../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.
-
-[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/solo-founder.md

@@ -1,65 +0,0 @@
-# Before launch: for solo founders and vibecoders
-
-## The problem
-
-You built the app in weeks, much of it with an AI assistant. It works. You have
-not had time to check the things that tend to go wrong in AI-written apps: an
-API route that returns any user's data if you change the id, an OpenAI key in a
-client bundle, a missing security header, a CORS policy of `*`, a login with no
-rate limit. Nobody on the team does security, because there is no team.
-
-## What to run
-
-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](../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.
-
-## What you get
-
-```
-  Findings
-
-  HIGH  IDOR/BOLA: GET /api/users/{user_id}
-         http://localhost:3000/api/users/1 → 200
-  HIGH  OAuth open redirect
-         http://localhost:3000/api/oauth/callback?redirect_uri=... → 302
-  MED   Missing Content-Security-Policy
-  MED   No login rate limiting detected
-         http://localhost:3000/api/login → 401
-  LOW   Missing X-Frame-Options
-  INFO  Missing Referrer-Policy
-
-  ──────────────────────────────────────────────────────────
-  2 high · 5 medium · 2 low · 2 info
-```
-
-`penthera fix --plan` then prints a unified diff per fix it knows (security
-headers, cookie flags, a CORS allowlist, a login rate limit, moving a
-hardcoded secret to an environment variable) for Next.js, Express, Fastify and
-Hono. Nothing is written until you apply a plan by id, and the repo is
-re-scanned afterwards to confirm the finding is gone.
-[More on fixes](../commands/fix.md).
-
-## 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](../../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.
-
-[All use cases](README.md) · [Back to the README](../../README.md)