penthera 1.1.0

package/skills/penthera/references/remediation.md

@@ -0,0 +1,267 @@
+# Remediation playbook
+
+Step-by-step, framework-aware fixes for the issues Penthera finds. This is the
+"fix" half of the scan -> fix -> verify loop in Workflow 4 of [SKILL.md](../SKILL.md).
+
+## How to use this playbook
+
+1. **Scan** and read the findings (each has a `title`, `category`, and `severity`).
+2. **Detect the framework**: check `package.json`/imports for `next`, `express`,
+   `fastify`, `hono`; check `requirements.txt`/imports for `fastapi`, `flask`.
+3. **For each finding**, find the section below that matches its `category`, then
+   apply the snippet for the detected framework as a reviewable diff.
+4. **Re-scan** and confirm the finding is gone.
+
+Rules: work highest severity first, **show the diff and get the user's approval
+before applying**, never apply against production, and treat a fix as done only
+after a clean re-scan.
+
+| Finding category | Section |
+|------------------|---------|
+| `headers` | [Security headers](#security-headers) |
+| `auth`, `auth-bypass` | [Authentication](#authentication) |
+| `exposure` | [Exposed API docs](#exposed-api-docs) |
+| `cors`, `cors-misconfiguration` | [CORS](#cors) |
+| `rate-limiting` | [Rate limiting](#rate-limiting) |
+| `secrets` | [Hardcoded secrets](#hardcoded-secrets) |
+| `auth-bypass` (JWT) | [JWT](#jwt) |
+| `open-redirect` | [Open redirect](#open-redirect) |
+| `sqli`/`xss`/`ssti`/`ssrf`/`cmdi`/`injection` | [Injection](#injection) |
+| `transport`, `tls` | [HTTPS and TLS](#https-and-tls) |
+| `cookie` | [Insecure cookies](#insecure-cookies) |
+| `disclosure`, `info-leak` | [Information disclosure](#information-disclosure) |
+| `js-vulnerability`, `cve` | [Vulnerable JS libraries](#vulnerable-js-libraries) |
+
+---
+
+## Security headers
+
+**Findings:** Missing Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, HSTS.
+**Means:** responses lack headers that mitigate clickjacking, MIME sniffing, and content injection.
+
+**Next.js** (`next.config.js`):
+```js
+const securityHeaders = [
+  { key: "X-Frame-Options", value: "DENY" },
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+  { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=()" },
+  { key: "Content-Security-Policy", value: "default-src 'self'" },
+  { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" },
+];
+module.exports = {
+  async headers() {
+    return [{ source: "/:path*", headers: securityHeaders }];
+  },
+};
+```
+
+**Express** ([helmet](https://www.npmjs.com/package/helmet)):
+```js
+import helmet from "helmet";
+app.use(helmet()); // CSP, X-Frame-Options, HSTS, X-Content-Type-Options, Referrer-Policy
+```
+
+**Fastify:** `await app.register(import("@fastify/helmet"))`
+**Hono:** `import { secureHeaders } from "hono/secure-headers"; app.use("*", secureHeaders())`
+
+**FastAPI** (middleware):
+```python
+@app.middleware("http")
+async def security_headers(request, call_next):
+    resp = await call_next(request)
+    resp.headers["X-Frame-Options"] = "DENY"
+    resp.headers["X-Content-Type-Options"] = "nosniff"
+    resp.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+    resp.headers["Content-Security-Policy"] = "default-src 'self'"
+    return resp
+```
+
+**Verify:** re-scan; the "Missing ... header" findings disappear.
+
+---
+
+## Authentication
+
+**Findings:** Unauthenticated endpoint, Client-side-only authentication, Login accepts arbitrary credentials.
+**Means:** sensitive routes are reachable without server-side auth, or auth is only enforced in the browser (which is not security).
+
+**Next.js** (`middleware.ts` plus per-route verification):
+```ts
+import { NextResponse } from "next/server";
+export function middleware(req) {
+  const token = req.cookies.get("session")?.value;
+  if (!token) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+}
+export const config = { matcher: ["/api/:path*"] };
+```
+
+**Express:**
+```js
+function requireAuth(req, res, next) {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+  if (!token || !verify(token)) return res.status(401).json({ error: "Unauthorized" });
+  next();
+}
+app.use("/api/admin", requireAuth);
+```
+
+**FastAPI:**
+```python
+from fastapi import Depends, HTTPException
+def require_auth(token: str = Depends(oauth2_scheme)):
+    if not valid(token): raise HTTPException(status_code=401)
+
+@app.get("/api/admin", dependencies=[Depends(require_auth)])
+def admin(): ...
+```
+
+**Verify:** re-scan; the route returns 401 without a valid token and the "Unauthenticated endpoint" finding clears.
+
+---
+
+## Exposed API docs
+
+**Findings:** FastAPI/Swagger UI exposed, OpenAPI specification exposed.
+**Fix:** disable interactive docs and the spec in production.
+
+**FastAPI:** `FastAPI(docs_url=None, redoc_url=None, openapi_url=None)` in production (gate by an env flag).
+**Express + swagger-ui:** only mount when `process.env.NODE_ENV !== "production"`.
+
+**Verify:** `/docs` and `/openapi.json` return 404 in production.
+
+---
+
+## CORS
+
+**Finding:** the server reflects an arbitrary `Origin`, or uses `*` together with credentials.
+**Fix:** allowlist explicit origins; never reflect a user-supplied origin with credentials.
+
+**Express** ([cors](https://www.npmjs.com/package/cors)):
+```js
+import cors from "cors";
+app.use(cors({ origin: ["https://app.example.com"], credentials: true }));
+```
+
+**FastAPI:**
+```python
+from fastapi.middleware.cors import CORSMiddleware
+app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], allow_credentials=True)
+```
+
+**Next.js / Hono:** set `Access-Control-Allow-Origin` to a fixed allowlist value, not the request `Origin`.
+
+**Verify:** re-scan; the CORS finding clears once only allowlisted origins are reflected.
+
+---
+
+## Rate limiting
+
+**Finding:** No login rate limiting detected.
+**Fix:** throttle auth and other expensive endpoints.
+
+**Express** ([express-rate-limit](https://www.npmjs.com/package/express-rate-limit)):
+```js
+import rateLimit from "express-rate-limit";
+app.use("/api/login", rateLimit({ windowMs: 15 * 60 * 1000, max: 10 }));
+```
+
+**Fastify:** `@fastify/rate-limit`. **Next.js:** an edge limiter such as `@upstash/ratelimit` in `middleware.ts`.
+**FastAPI:** [slowapi](https://pypi.org/project/slowapi/) with `@limiter.limit("10/15minutes")`.
+
+**Verify:** re-scan; rapid repeated requests are throttled (HTTP 429).
+
+---
+
+## Hardcoded secrets
+
+**Finding:** an API key, token, password, or private key is committed in the repo.
+**Fix (do all three):**
+1. Move it to an environment variable: `const key = process.env.STRIPE_SECRET_KEY;` (was `const key = "sk_live_..."`).
+2. **Rotate the secret now**, once committed it is compromised, even after removal.
+3. Add the file to `.gitignore`; if it was pushed, scrub history (`git filter-repo`).
+
+**Verify:** re-scan the repo (`penthera --repo .`); the secret finding clears. Confirm the old secret is revoked.
+
+---
+
+## JWT
+
+**Findings:** JWT alg:none bypass accepted, Configured JWT is expired.
+**Fix:** pin the signing algorithm and verify expiry on every request.
+```js
+jwt.verify(token, publicKey, { algorithms: ["RS256"] }); // never accept "none"
+```
+
+**Verify:** re-scan; the alg:none and expiry findings clear.
+
+---
+
+## Open redirect
+
+**Finding:** OAuth open redirect, `redirect_uri` (or a `return`/`next` param) reflects an arbitrary URL.
+**Fix:** validate against an allowlist of exact registered URIs; never redirect to a raw user-supplied URL.
+```js
+const ALLOWED = new Set(["https://app.example.com/callback"]);
+if (!ALLOWED.has(redirectUri)) return res.status(400).send("Invalid redirect_uri");
+```
+
+**Verify:** re-scan; the open-redirect finding clears.
+
+---
+
+## Injection
+
+**Findings:** SQL error leaked, OS command injection, XSS, SSTI, SSRF.
+
+- **SQLi:** use parameterized queries; never concatenate input. `db.query("SELECT * FROM users WHERE id = $1", [id])`.
+- **XSS:** rely on framework auto-escaping; set a CSP; avoid `dangerouslySetInnerHTML`/`v-html`/`|safe` with user input.
+- **Command injection:** never pass input to a shell. Use `execFile(cmd, [args])` with an allowlist; avoid `exec`/`shell=True`.
+- **SSRF:** allowlist outbound hosts; block internal ranges and metadata endpoints (`169.254.169.254`, `127.0.0.0/8`, `10.0.0.0/8`).
+- **SSTI:** never render user input as a template; use sandboxed templating with autoescaping.
+
+**Verify:** re-scan with `--deep`; the injection probe no longer triggers.
+
+---
+
+## HTTPS and TLS
+
+**Findings:** No HTTPS (cleartext), TLS certificate expired / expiring / not trusted.
+**Fix:** serve over HTTPS, redirect HTTP -> HTTPS, add HSTS, and renew/replace the certificate (e.g. Let's Encrypt). For "not trusted", fix the certificate chain (include intermediates).
+
+**Verify:** re-scan; the transport/TLS findings clear.
+
+---
+
+## Insecure cookies
+
+**Finding:** a session cookie is missing `Secure`, `HttpOnly`, or `SameSite`.
+**Fix:**
+```js
+res.cookie("session", token, { httpOnly: true, secure: true, sameSite: "lax" });
+```
+**Next.js:** `cookies().set("session", token, { httpOnly: true, secure: true, sameSite: "lax" })`.
+
+**Verify:** re-scan; the cookie finding clears.
+
+---
+
+## Information disclosure
+
+**Findings:** Server version disclosed, stack traces or framework errors leaked.
+**Fix:** remove the `Server`/`X-Powered-By` headers (`app.disable("x-powered-by")` in Express) and return generic errors in production (no stack traces, no raw SQL errors).
+
+**Verify:** re-scan; the disclosure finding clears.
+
+---
+
+## Vulnerable JS libraries
+
+**Finding:** a front-end JavaScript library has known CVEs (detected via Retire.js).
+**Fix:** upgrade the library to a patched version (bump it in `package.json`, `npm update <pkg>`), or replace it. Re-run `npm audit`.
+
+**Verify:** re-scan; once the patched version is served, the JS CVE finding clears.
+
+---
+
+For building secure-by-default so these never appear, see [secure-defaults.md](secure-defaults.md).

package/skills/penthera/references/reporting.md

@@ -0,0 +1,113 @@
+# Owner-facing reports & questionnaire responses
+
+Turn a Penthera scan into documents a non-security owner can act on and send:
+a **remediation plan**, a **security-questionnaire response**, and a **NIS2
+duty-of-care evidence summary**. All three are generated by you (the agent) from
+the scan's JSON, grounded in what the scan actually found and tested.
+
+## Golden rule: evidence, not assertions
+
+You are drafting from technical evidence, not certifying compliance.
+
+- **Only claim what the scan supports.** If a finding or `executedProbes` entry
+  backs an answer, cite it. If it doesn't, mark the answer **`NEEDS HUMAN INPUT`**
+, never invent a control, a policy, or a "yes".
+- **Organisational questions are not answerable from a scan.** Incident-response
+  process, staff training, backups, vendor contracts, data-retention policy →
+  always `NEEDS HUMAN INPUT`. Say so plainly.
+- **Never state or imply certification.** Penthera produces evidence toward a
+  duty of care; it does not certify anything. Keep the disclaimer in every doc.
+- Prefer "as of <scan date>, an automated scan found…" phrasing over absolutes.
+
+## The data you have
+
+Run a scan with JSON + framework mapping, then read the report object:
+
+```bash
+penthera <url> --repo . --framework nis2 -o reports/scan.json
+```
+
+Key fields in `reports/scan.json`:
+
+| Field | Use |
+|-------|-----|
+| `findings[]` | `{severity, title, description, url, category, source, wstg[]}`, the raw evidence |
+| `actionPlan[]` | prioritised `{action, why, fix, effort, ownerAction, severity, findings[]}`, the owner remediation plan, already built |
+| `compliance` | NIS2 Article 21 per-measure status (`--framework nis2`), tested / evidence / planned / out-of-scope |
+| `executedProbes[]` | which probes actually ran, the basis for "we tested X" |
+| `emailAuth` | `{spf, dmarc, dmarcPolicy, mxCount}`, email posture |
+| `tls`, `fingerprint`, `endpoints` | transport, stack, and surface facts |
+
+## Document 1, Remediation plan (for the owner)
+
+The scan's Markdown report already contains an **Action plan** section built from
+`actionPlan[]`. To go further, expand each item into a ticket the owner can hand
+to a developer:
+
+For each `actionPlan[]` item, in order:
+1. **What & why**, from `action` + `why`.
+2. **How**, from `fix`, made specific to their stack (detect Next.js/Express/
+   Fastify/FastAPI from `package.json`/imports and give the exact config).
+3. **Owner vs developer**, if `ownerAction` is true, call it out (rotate secret,
+   renew cert, change DNS): the owner must do it; a developer/agent cannot.
+4. **Verify**, "re-scan with `--baseline` to confirm this finding is gone."
+
+Offer to apply the developer-side fixes via **Workflow 4** (scan → fix → verify).
+
+## Document 2, Security-questionnaire response
+
+Vendors get sent questionnaires (SIG Lite, CAIQ, or a customer's own list). Draft
+a response grounded in the scan. Use this table format and fill the **Evidence**
+column from scan data; mark anything unbacked `NEEDS HUMAN INPUT`.
+
+```markdown
+# Security questionnaire, <company>, as of <scan date>
+
+> Draft prepared from an automated Penthera scan of <target>. Answers marked
+> NEEDS HUMAN INPUT require confirmation by the owner. This is not a certification.
+
+| # | Question | Answer | Evidence |
+|---|----------|--------|----------|
+| 1 | Is all traffic served over HTTPS/TLS? | Yes/No | `tls.protocol`, HSTS in `fingerprint` |
+| 2 | Are security headers (CSP, X-Frame-Options…) set? | Partial | header findings / absence |
+| 3 | Is email spoofing protection (SPF/DMARC) in place? | Yes/Partial/No | `emailAuth` |
+| 4 | Are dependencies scanned for known CVEs? | Yes | Retire.js probe ran (`executedProbes`) + findings |
+| 5 | Is access control tested (authz, IDOR)? | Yes | auth/idor probes in `executedProbes` |
+| 6 | Are secrets kept out of source control? | Yes/No | secret-scan findings |
+| 7 | Do you have an incident-response process? | NEEDS HUMAN INPUT | organisational |
+| 8 | Do you run regular backups / DR tests? | NEEDS HUMAN INPUT | organisational |
+| 9 | Is staff security-trained? | NEEDS HUMAN INPUT | organisational |
+```
+
+Map each questionnaire item to evidence where it exists; be conservative. A
+"Yes" needs a backing probe/finding; otherwise "Partial" (with the gap) or
+`NEEDS HUMAN INPUT`.
+
+## Document 3, NIS2 duty-of-care evidence summary
+
+From `compliance` (`--framework nis2`). One row per Article 21(2) measure with
+its per-scan status and the evidence, plus the standard disclaimer.
+
+```markdown
+# NIS2 Article 21, technical evidence summary (<scan date>)
+
+> Automated technical evidence toward the duty of care (zorgplicht), not a
+> compliance determination, an audit, or a certification. Organisational
+> measures need human process; consult your national authority (NCSC in NL, CCB
+> in BE) or a qualified jurist.
+
+| Art. 21(2) | Measure | Status this scan | Evidence / gap |
+|-----------|---------|------------------|----------------|
+| (from compliance.measures: id, title, status, findings, note) |
+
+**Testable measures exercised this scan:** <compliance.summary.coveredThisScan>/<compliance.summary.testable>.
+```
+
+Fill each row from `compliance.measures[]`. For `planned` / `out-of-scope` /
+`evidence` measures, say so honestly rather than implying coverage.
+
+## Output
+
+Write drafts to `reports/` (gitignored) as Markdown. Offer to convert to DOCX/PDF
+if the user has a converter. Always end by listing every `NEEDS HUMAN INPUT` item
+so the owner knows exactly what only they can answer.

package/skills/penthera/references/secure-defaults.md

@@ -0,0 +1,41 @@
+# Secure defaults
+
+Build it right the first time so Penthera finds nothing. This is the proactive
+companion to [remediation.md](remediation.md): apply these while writing code,
+then run a scan to verify. For fixing issues that already exist, use the
+remediation playbook.
+
+## Checklist for every web app
+
+- [ ] **Security headers** set (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, HSTS).
+- [ ] **Server-side auth** enforced on every sensitive route. Client-side checks are not security.
+- [ ] **Parameterized queries** everywhere. No string-built SQL.
+- [ ] **Output encoding** on by default. No raw HTML injection with user input.
+- [ ] **Secrets in environment variables**, never in code. `.env` is gitignored.
+- [ ] **CORS allowlist** of explicit origins. No `*` with credentials.
+- [ ] **Rate limiting** on auth and expensive endpoints.
+- [ ] **Secure cookies**: `HttpOnly`, `Secure`, `SameSite`.
+- [ ] **API docs disabled** in production (`/docs`, `/openapi.json`).
+- [ ] **HTTPS only** with HSTS and a valid TLS certificate.
+- [ ] **JWT** with a pinned algorithm (no `alg:none`); verify `exp` and signature.
+- [ ] **Redirect targets** validated against an allowlist.
+
+## Per-framework starting points
+
+| Framework | Secure-by-default setup |
+|-----------|--------------------------|
+| **Next.js** | Security headers in `next.config.js`; auth in `middleware.ts`; cookies via `next/headers` with `httpOnly`/`secure`/`sameSite`. |
+| **Express** | `helmet()` + `cors({ origin: [...] })` + `express-rate-limit` + an auth middleware; `app.disable("x-powered-by")`. |
+| **Fastify** | `@fastify/helmet` + `@fastify/cors` + `@fastify/rate-limit` + an `onRequest` auth hook. |
+| **Hono** | `secureHeaders()` + `cors()` + custom auth middleware. |
+| **FastAPI** | header middleware + `CORSMiddleware` allowlist + `slowapi` + `docs_url=None` in production. |
+
+## Verify
+
+Run a scan to confirm the defaults hold:
+
+```bash
+penthera https://localhost:3000 --repo .
+```
+
+Anything it flags, fix with the [remediation playbook](remediation.md), then re-scan.

package/skills/penthera/references/troubleshooting.md

@@ -0,0 +1,100 @@
+# Troubleshooting
+
+## Exit code 2, scan failed
+
+**Symptoms:** CLI exits with code 2, "Target unreachable" or "Scan failed"
+
+**Causes and fixes:**
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Target unreachable | Server down, wrong URL, firewall | Verify URL in browser; check server is running |
+| No target specified | Missing URL and `--repo` | Provide URL, `--repo <path>`, or `--machine` |
+| Unknown profile | Invalid `--profile` value | Use `quick`, `standard`, or `deep` |
+| Scan failed (exception) | Network timeout, parse error | Retry with `--verbose`; increase `--timeout` |
+
+```bash
+penthera https://myapp.com --verbose --timeout 30000
+```
+
+## Node.js not found or wrong version
+
+**Symptoms:** `node: command not found` or engine error
+
+**Solution:** Install Node.js 18+ from [nodejs.org](https://nodejs.org/). Verify:
+
+```bash
+node -v   # should be v18.x or higher
+```
+
+## Penthera CLI not found
+
+**Symptoms:** `penthera: command not found`
+
+**Solutions:**
+
+```bash
+# From repo root (always works)
+node bin/penthera.js --version
+
+# Global install
+cd /path/to/penthera && npm link
+penthera --version
+```
+
+## Auth failures / empty authenticated findings
+
+**Symptoms:** Scan completes but misses protected endpoints
+
+**Causes:** Expired token, wrong cookie format, missing Bearer prefix
+
+**Solutions:**
+
+```bash
+# Bearer, prefix added automatically if missing
+penthera https://myapp.com --auth-bearer "eyJ..."
+
+# Or via env
+export PENTHERA_BEARER="eyJ..."
+penthera https://myapp.com -o reports/scan.json
+
+# Cookie, full header value
+penthera https://myapp.com --auth-cookie "session=abc123; path=/"
+```
+
+## Deep/fuzz warnings
+
+**Symptoms:** Yellow WARN about attack payloads
+
+**Expected:** `--deep` always prints a warning. Confirm user authorization before proceeding.
+
+## Baseline file not found
+
+**Symptoms:** Error reading baseline JSON
+
+**Solution:** Ensure previous scan exists:
+
+```bash
+ls reports/previous.json
+# Or run initial scan first:
+penthera https://myapp.com -o reports/previous.json
+```
+
+## SARIF upload fails in CI
+
+**Symptoms:** GitHub Actions SARIF upload error
+
+**Checks:**
+- `reports/scan.sarif` was generated (`--sarif` flag used)
+- `github/codeql-action/upload-sarif@v3` step has `if: always()`
+- Repository has code scanning enabled
+
+## Preflight script failures
+
+Run manually for diagnostics:
+
+```bash
+bash skills/penthera/scripts/preflight.sh https://myapp.com
+```
+
+Fix each reported check before scanning.

package/skills/penthera/scripts/preflight.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Penthera preflight, run before first scan in a session.
+# Usage: bash skills/penthera/scripts/preflight.sh [URL]
+
+set -euo pipefail
+
+TARGET_URL="${1:-}"
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+fail() {
+  echo "preflight: ERROR: $*" >&2
+  exit 1
+}
+
+warn() {
+  echo "preflight: WARN: $*" >&2
+}
+
+ok() {
+  echo "preflight: OK: $*"
+}
+
+# Node.js 18+
+if ! command -v node >/dev/null 2>&1; then
+  fail "Node.js not found. Install Node.js 18+ from https://nodejs.org/"
+fi
+
+NODE_MAJOR=$(node -e "process.stdout.write(String(process.version).replace(/^v/, '').split('.')[0])")
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  fail "Node.js $(node -v) is too old. Requires Node.js 18+."
+fi
+ok "Node.js $(node -v)"
+
+# Penthera CLI
+PENTHERA_CMD=""
+if command -v penthera >/dev/null 2>&1; then
+  PENTHERA_CMD="penthera"
+elif [ -f "$REPO_ROOT/bin/penthera.js" ]; then
+  PENTHERA_CMD="node $REPO_ROOT/bin/penthera.js"
+else
+  fail "Penthera CLI not found. Run 'npm link' from repo root or use node bin/penthera.js"
+fi
+
+VERSION=$($PENTHERA_CMD --version 2>/dev/null || true)
+if [ -z "$VERSION" ]; then
+  fail "Could not run Penthera CLI ($PENTHERA_CMD --version failed)"
+fi
+ok "Penthera $VERSION"
+
+# Reports directory (create if missing)
+mkdir -p "$REPO_ROOT/reports"
+ok "reports/ directory ready"
+
+# Non-localhost warning
+if [ -n "$TARGET_URL" ]; then
+  case "$TARGET_URL" in
+    http://localhost*|https://localhost*|http://127.0.0.1*|https://127.0.0.1*|http://[::1]*|https://[::1]*)
+      ok "Target is localhost, authorization satisfied for local testing"
+      ;;
+    *)
+      warn "Target is not localhost ($TARGET_URL). Confirm user owns this system or has written authorization before scanning."
+      ;;
+  esac
+fi
+
+echo "preflight: All checks passed. Ready to scan."

package/skills/penthera/scripts/validate-report.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Validate a Penthera JSON scan report.
+ * Usage: node skills/penthera/scripts/validate-report.mjs [report.json]
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const reportPath = resolve(process.argv[2] || "reports/scan.json");
+
+function fail(msg) {
+  console.error(`validate-report: ERROR: ${msg}`);
+  process.exit(1);
+}
+
+function ok(msg) {
+  console.log(`validate-report: OK: ${msg}`);
+}
+
+if (!existsSync(reportPath)) {
+  fail(`Report not found: ${reportPath}`);
+}
+
+let report;
+try {
+  report = JSON.parse(readFileSync(reportPath, "utf-8"));
+} catch (e) {
+  fail(`Invalid JSON: ${e.message}`);
+}
+
+if (!report.timestamp || typeof report.timestamp !== "string") {
+  fail("Missing or invalid 'timestamp' field");
+}
+
+if (!Array.isArray(report.findings)) {
+  fail("Missing or invalid 'findings' array");
+}
+
+const requiredFindingFields = ["severity", "title"];
+for (const [i, f] of report.findings.entries()) {
+  for (const field of requiredFindingFields) {
+    if (!f[field]) fail(`Finding #${i} missing '${field}'`);
+  }
+  const validSev = ["critical", "high", "medium", "low", "info"];
+  if (!validSev.includes(f.severity)) {
+    fail(`Finding #${i} has invalid severity: ${f.severity}`);
+  }
+}
+
+const mdPath = reportPath.replace(/\.json$/i, ".md");
+if (existsSync(mdPath)) ok(`Companion Markdown found: ${mdPath}`);
+
+ok(`${report.findings.length} findings in ${reportPath}`);

package/skills/penthera/scripts/validate-report.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Validate a Penthera JSON scan report.
+# Usage: bash skills/penthera/scripts/validate-report.sh [report.json]
+
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+REPORT="${1:-reports/scan.json}"
+node "$REPO_ROOT/skills/penthera/scripts/validate-report.mjs" "$REPORT"