penthera 1.1.0

package/lib/blackbox/idor.js

@@ -0,0 +1,113 @@
+/**
+ * IDOR / BOLA probes, test object-level authorization on parameterized routes.
+ */
+import { joinUrl } from "../../src/utils/url.js";
+import { probeFetch } from "../../src/utils/http.js";
+
+const ID_PARAM_RE = /\{([^}]+)\}/g;
+const ID_LIKE_NAMES = /^(id|uuid|uid|user_?id|account_?id|resource_?id|item_?id|order_?id|seat_?id|project_?id)$/i;
+const PROBE_IDS = ["1", "2", "999", "0", "admin"];
+const SENSITIVE_BODY_RE = /email|password|role|admin|token|secret|billing|ssn|phone|address|user_id/i;
+
+export function extractIdRoutes(spec, paths = []) {
+  const routes = [];
+  const seen = new Set();
+
+  const add = (template, method = "GET") => {
+    if (!template.includes("{")) return;
+    const params = [...template.matchAll(ID_PARAM_RE)].map((m) => m[1]);
+    if (!params.some((p) => ID_LIKE_NAMES.test(p) || p.toLowerCase().includes("id"))) return;
+    const key = `${method}:${template}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    routes.push({ template, method, params });
+  };
+
+  if (spec?.paths) {
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      for (const method of Object.keys(methods)) {
+        if (["get", "put", "patch", "delete"].includes(method)) add(path, method.toUpperCase());
+      }
+    }
+  }
+
+  for (const path of paths) {
+    if (path.includes("{")) add(path, "GET");
+  }
+
+  for (const path of paths) {
+    const m = path.match(/^(.+\/)([a-zA-Z0-9-]{1,64})$/);
+    if (!m) continue;
+    const prefix = m[1].replace(/\/$/, "");
+    if (!/\/(users|accounts|orders|items|projects|resources|seats|documents)/i.test(prefix)) continue;
+    add(`${prefix}/{id}`, "GET");
+  }
+
+  return routes.slice(0, 12);
+}
+
+function fillTemplate(template, values) {
+  let path = template;
+  for (const [key, val] of Object.entries(values)) {
+    path = path.replace(`{${key}}`, encodeURIComponent(val));
+  }
+  return path;
+}
+
+export async function probeIdorBola(baseUrl, opts = {}) {
+  const timeout = opts.timeout || 8_000;
+  const authHeaders = opts.authHeaders || {};
+  const findings = [];
+  const routes = extractIdRoutes(opts.spec, opts.paths || []);
+
+  if (routes.length === 0) return findings;
+
+  for (const route of routes.slice(0, opts.maxRoutes || 8)) {
+    const results = [];
+
+    for (const id of PROBE_IDS) {
+      const values = {};
+      for (const p of route.params) values[p] = id;
+
+      const path = fillTemplate(route.template, values);
+      const res = await probeFetch(joinUrl(baseUrl, path), {
+        timeout,
+        method: route.method,
+        headers: authHeaders,
+      });
+
+      if (!res || res.status >= 400 || res.body.length < 3) continue;
+      results.push({ id, path, status: res.status, body: res.body });
+    }
+
+    const sensitive = results.filter((r) => SENSITIVE_BODY_RE.test(r.body));
+    if (sensitive.length >= 2) {
+      findings.push({
+        severity: "high",
+        title: `IDOR/BOLA: ${route.method} ${route.template}`,
+        description:
+          `Multiple object IDs (${sensitive.map((r) => r.id).join(", ")}) returned HTTP 200 with sensitive fields.`,
+        url: joinUrl(baseUrl, sensitive[0].path),
+        status: 200,
+        category: "auth",
+        source: "idor-probe",
+      });
+      continue;
+    }
+
+    const adminHit = results.find((r) => /999|admin/.test(r.id) && SENSITIVE_BODY_RE.test(r.body));
+    if (adminHit && !Object.keys(authHeaders).length) {
+      findings.push({
+        severity: "high",
+        title: `BOLA: privileged ID accessible on ${route.template}`,
+        description: `ID "${adminHit.id}" returned sensitive data without authorization.`,
+        url: joinUrl(baseUrl, adminHit.path),
+        status: 200,
+        category: "auth",
+        source: "idor-probe",
+      });
+    }
+  }
+
+  return findings;
+}

package/lib/blackbox/jwt.js

@@ -0,0 +1,73 @@
+/**
+ * JWT misconfiguration probes.
+ */
+import { joinUrl } from "../../src/utils/url.js";
+import { probeFetch } from "../../src/utils/http.js";
+
+function decodeJwtPayload(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const payload = Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8");
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+
+export async function probeJwt(baseUrl, opts = {}) {
+  const findings = [];
+  const timeout = opts.timeout || 8_000;
+  const token = opts.bearerToken;
+
+  if (!token) return findings;
+
+  const payload = decodeJwtPayload(token);
+  if (!payload) {
+    findings.push({
+      severity: "low",
+      title: "Configured bearer token is not a valid JWT",
+      description: "Token could not be decoded, verify auth configuration.",
+      url: baseUrl,
+      category: "auth",
+      source: "jwt-probe",
+    });
+    return findings;
+  }
+
+  if (payload.exp && new Date(payload.exp * 1000) < new Date()) {
+    findings.push({
+      severity: "medium",
+      title: "Configured JWT is expired",
+      description: "Scans with this token may not reflect authenticated routes.",
+      url: baseUrl,
+      category: "auth",
+      source: "jwt-probe",
+    });
+  }
+
+  if (opts.testPath) {
+    const header = Buffer.from(JSON.stringify({ alg: "none", typ: "JWT" })).toString("base64url");
+    const body = Buffer.from(JSON.stringify({ ...payload, exp: Math.floor(Date.now() / 1000) + 3600 })).toString("base64url");
+    const forged = `${header}.${body}.`;
+
+    const res = await probeFetch(joinUrl(baseUrl, opts.testPath), {
+      timeout,
+      headers: { Authorization: `Bearer ${forged}` },
+    });
+
+    if (res?.status === 200) {
+      findings.push({
+        severity: "critical",
+        title: "JWT alg:none bypass accepted",
+        description: `Forged unsigned JWT accepted on ${opts.testPath}.`,
+        url: joinUrl(baseUrl, opts.testPath),
+        status: res.status,
+        category: "auth",
+        source: "jwt-probe",
+      });
+    }
+  }
+
+  return findings;
+}

package/lib/blackbox/oauth.js

@@ -0,0 +1,50 @@
+/**
+ * OAuth / open redirect misconfiguration probes.
+ */
+import { joinUrl, redirectsToHost } from "../../src/utils/url.js";
+import { probeFetch } from "../../src/utils/http.js";
+
+const OAUTH_PATHS = [
+  "/api/auth/callback",
+  "/api/oauth/callback",
+  "/auth/callback",
+  "/oauth/callback",
+];
+
+const EVIL = "https://evil-attacker.example/capture";
+
+export async function probeOAuthMisconfig(baseUrl, opts = {}) {
+  const timeout = opts.timeout || 8_000;
+  const findings = [];
+
+  for (const path of OAUTH_PATHS) {
+    for (const qs of [
+      `redirect_uri=${encodeURIComponent(EVIL)}`,
+      `redirect=${encodeURIComponent(EVIL)}`,
+    ]) {
+      const url = joinUrl(baseUrl, `${path}?${qs}`);
+      const res = await probeFetch(url, { timeout });
+
+      if (!res) continue;
+
+      const location = res.headers.location || "";
+      // Only a real open redirect if the Location resolves to the attacker's
+      // host, not if the attacker URL merely rides along in the query of a
+      // same-site canonicalization redirect (e.g. apex → www).
+      if (redirectsToHost(location, url, "evil-attacker.example")) {
+        findings.push({
+          severity: "high",
+          title: "OAuth open redirect",
+          description: `${path} redirects to attacker-controlled URL.`,
+          url,
+          status: res.status,
+          category: "auth",
+          source: "oauth-probe",
+        });
+        break;
+      }
+    }
+  }
+
+  return findings;
+}

package/lib/blackbox/openapi.js

@@ -0,0 +1,227 @@
+/**
+ * OpenAPI / Swagger discovery and misconfiguration checks.
+ */
+import { joinUrl } from "../../src/utils/url.js";
+import { probeFetch } from "../../src/utils/http.js";
+
+const SPEC_CANDIDATES = [
+  "/openapi.json",
+  "/swagger.json",
+  "/api/openapi.json",
+  "/openapi.yaml",
+];
+
+const DOC_CANDIDATES = [
+  { path: "/docs", name: "FastAPI/Swagger UI" },
+  { path: "/redoc", name: "ReDoc API docs" },
+  { path: "/swagger", name: "Swagger UI" },
+  { path: "/api/docs", name: "API docs" },
+];
+
+/**
+ * @param {string} baseUrl
+ * @returns {Promise<{ spec: object|null, specUrl: string|null, paths: string[], findings: object[] }>}
+ */
+export async function scanOpenApi(baseUrl, opts = {}) {
+  const timeout = opts.timeout || 8_000;
+  const findings = [];
+  let spec = null;
+  let specUrl = null;
+
+  for (const path of SPEC_CANDIDATES) {
+    const res = await probeFetch(joinUrl(baseUrl, path), { timeout });
+    if (!res || res.status !== 200) continue;
+    try {
+      spec = JSON.parse(res.body);
+      specUrl = joinUrl(baseUrl, path);
+      break;
+    } catch {
+      // not JSON, skip
+    }
+  }
+
+  for (const doc of DOC_CANDIDATES) {
+    const res = await probeFetch(joinUrl(baseUrl, doc.path), { timeout });
+    if (!res || res.status !== 200) continue;
+    const looksLikeDocs = /swagger|openapi|redoc|rapidoc/i.test(res.body);
+    if (!looksLikeDocs && doc.path !== "/docs") continue;
+
+    findings.push({
+      severity: "medium",
+      title: `${doc.name} exposed`,
+      description: `API documentation is publicly accessible at ${doc.path}. Disable in production or protect with authentication.`,
+      url: joinUrl(baseUrl, doc.path),
+      status: res.status,
+      category: "exposure",
+      source: "openapi-scan",
+    });
+  }
+
+  if (specUrl) {
+    findings.push({
+      severity: "medium",
+      title: "OpenAPI specification exposed",
+      description: "Machine-readable API spec reveals all routes, parameters, and schemas to attackers.",
+      url: specUrl,
+      status: 200,
+      category: "exposure",
+      source: "openapi-scan",
+    });
+  }
+
+  const paths = spec?.paths ? Object.keys(spec.paths) : [];
+  const unprotectedRoutes = [];
+
+  for (const path of paths) {
+    const methods = spec.paths[path] || {};
+    const hasSecurity = Object.values(methods).some((op) => op?.security?.length > 0);
+    const globalSecurity = spec.security?.length > 0;
+    if (hasSecurity || globalSecurity) continue;
+
+    for (const [method, op] of Object.entries(methods)) {
+      if (!["get", "post", "put", "delete", "patch"].includes(method)) continue;
+      unprotectedRoutes.push({ path, method: method.toUpperCase(), summary: op.summary || path });
+    }
+  }
+
+  for (const route of unprotectedRoutes
+    .filter((r) => r.method === "GET")
+    .sort((a, b) => sensitivePathScore(a.path) - sensitivePathScore(b.path))) {
+    const res = await probeFetch(joinUrl(baseUrl, route.path), { timeout });
+    if (!res || res.status >= 400) continue;
+
+    const hasBody = res.body && res.body.length > 2;
+    const looksSensitive = /password|secret|token|user_id|email|seat|participant/i.test(res.body);
+
+    if (hasBody) {
+      findings.push({
+        severity: looksSensitive ? "high" : "medium",
+        title: `Unauthenticated endpoint: ${route.method} ${route.path}`,
+        description: route.summary
+          ? `${route.summary}, responds HTTP ${res.status} without authentication.`
+          : `Responds HTTP ${res.status} without authentication.`,
+        url: joinUrl(baseUrl, route.path),
+        status: res.status,
+        category: "auth",
+        source: "openapi-scan",
+      });
+    }
+  }
+
+  return {
+    spec,
+    specUrl,
+    paths,
+    unprotectedRoutes,
+    findings,
+  };
+}
+
+/**
+ * Does an invalid-credential response actually look like a *successful* login?
+ * A bare HTTP 200 is not enough, SPA/JSON login endpoints routinely return 200
+ * with `{ "success": false }` or an error body. Only flag when there's a real
+ * success signal (an auth cookie or a token/success body) and no failure signal.
+ */
+export function looksAuthenticated(res) {
+  if (!res || res.status !== 200) return false;
+  const body = (res.body || "").toLowerCase();
+  const failure = /invalid|incorrect|unauthor|denied|forbidden|"success"\s*:\s*false|\berror\b|\bfail|wrong|not found|missing|require/;
+  if (failure.test(body)) return false;
+  const setCookie = (res.headers?.["set-cookie"] || "").toLowerCase();
+  const authCookie = /(sess|token|auth|jwt|sid)[\w-]*=[^;\s]+/.test(setCookie);
+  const successBody = /"?(access_token|refresh_token|\btoken\b|jwt|session)"?\s*[:=]|"success"\s*:\s*true|authenticated|welcome/.test(body);
+  return authCookie || successBody;
+}
+
+/**
+ * Basic authentication hardening checks for login endpoints.
+ */
+export async function probeAuthEndpoints(baseUrl, opts = {}) {
+  const timeout = opts.timeout || 8_000;
+  const findings = [];
+  const loginUrl = joinUrl(baseUrl, "/api/login");
+
+  const validAttempt = await probeFetch(loginUrl, {
+    timeout,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username: "penthera-probe-invalid", password: "invalid-password-12345" }),
+  });
+
+  if (!validAttempt) return findings;
+  // A redirect (e.g. apex→www), 404, or 405 means there's no real POST login
+  // handler at this path, don't run the arbitrary-creds / rate-limit / SQLi
+  // checks against a non-endpoint (avoids a false "no rate limiting" on a 308).
+  if (validAttempt.status === 404 || validAttempt.status === 405 ||
+      (validAttempt.status >= 300 && validAttempt.status < 400)) {
+    return findings;
+  }
+
+  if (looksAuthenticated(validAttempt)) {
+    findings.push({
+      severity: "critical",
+      title: "Login accepts arbitrary credentials",
+      description: "POST /api/login returned a successful, authenticated response (auth cookie or token) for invalid test credentials.",
+      url: loginUrl,
+      status: validAttempt.status,
+      category: "auth",
+      source: "auth-probe",
+    });
+  }
+
+  // Rate limiting, 8 rapid attempts
+  let rateLimited = false;
+  for (let i = 0; i < 8; i++) {
+    const res = await probeFetch(loginUrl, {
+      timeout,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ username: "rate-test", password: `attempt-${i}` }),
+    });
+    if (res && (res.status === 429 || /rate.?limit/i.test(res.body))) {
+      rateLimited = true;
+      break;
+    }
+  }
+
+  if (!rateLimited && validAttempt.status !== 404) {
+    findings.push({
+      severity: "medium",
+      title: "No login rate limiting detected",
+      description: "8 rapid login attempts did not trigger HTTP 429 or a rate-limit response.",
+      url: loginUrl,
+      status: validAttempt.status,
+      category: "auth",
+      source: "auth-probe",
+    });
+  }
+
+  // SQL injection smoke test, error-based
+  const sqli = await probeFetch(loginUrl, {
+    timeout,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username: "' OR '1'='1", password: "' OR '1'='1" }),
+  });
+
+  if (sqli && /sql|syntax error|sqlite|postgres|mysql|ORA-/i.test(sqli.body)) {
+    findings.push({
+      severity: "critical",
+      title: "SQL error leaked on login",
+      description: "Login endpoint returned a database error message for SQLi probe payload.",
+      url: loginUrl,
+      status: sqli.status,
+      category: "injection",
+      source: "auth-probe",
+    });
+  }
+
+  return findings;
+}
+
+function sensitivePathScore(path) {
+  if (/data|json|user|admin|config|secret|env|export/i.test(path)) return 0;
+  if (path === "/" || path.includes("{")) return 2;
+  return 1;
+}

package/lib/compliance/incident.js

@@ -0,0 +1,169 @@
+/**
+ * Incident-report helper (NIS2 measure b).
+ *
+ * Given the facts of an incident, lay out the reporting timeline (the 24h early
+ * warning, 72h notification, and 1-month final report) with real due dates, and
+ * produce a draft for each against the jurisdiction's required content. Fields
+ * the user hasn't provided are marked NEEDS INPUT, never invented.
+ *
+ * Offline. Drafts are starting points to send to your CSIRT / authority, not a
+ * substitute for the authority's own form or for legal advice.
+ */
+
+/** Fields collected about an incident (all optional; blanks become NEEDS INPUT). */
+export function incidentTemplate() {
+  return {
+    _about: "Penthera incident-report helper. Fill in what you know; leave the rest blank. `aware_at` is when you became aware (ISO 8601, e.g. 2026-08-15T09:30:00Z), it drives the deadlines. Offline; nothing is sent anywhere.",
+    title: "",
+    aware_at: "",
+    detected_at: "",
+    description: "",
+    systems_affected: "",
+    data_affected: "",
+    users_affected: "",
+    severity: "",
+    unlawful_or_malicious: "",
+    cross_border: "",
+    indicators: "",
+    mitigations: "",
+    root_cause: "",
+    contact: "",
+  };
+}
+
+function addOffset(date, { offsetHours, offsetMonths }) {
+  const x = new Date(date.getTime());
+  if (offsetHours) x.setTime(x.getTime() + offsetHours * 3600 * 1000);
+  if (offsetMonths) x.setUTCMonth(x.getUTCMonth() + offsetMonths);
+  return x;
+}
+
+/**
+ * Build the reporting timeline and per-deadline drafts.
+ * @param {object} incident - fields from incidentTemplate()
+ * @param {object} jurisdiction - nl.json (uses incidentDeadlines, authorities)
+ */
+export function buildIncidentReports(incident = {}, jurisdiction = {}) {
+  const deadlines = jurisdiction.incidentDeadlines || [];
+  const awareValid = incident.aware_at && !Number.isNaN(new Date(incident.aware_at).getTime());
+  const awareness = awareValid ? new Date(incident.aware_at) : null;
+
+  const notif = deadlines.find((d) => d.id === "notification");
+  const notifDue = awareness && notif ? addOffset(awareness, notif) : null;
+
+  const dueFor = (d) => {
+    if (!awareness) return null;
+    const base = d.from === "notification" ? (notifDue || awareness) : awareness;
+    return addOffset(base, d).toISOString();
+  };
+
+  const timeline = deadlines.map((d) => ({
+    id: d.id,
+    within: d.within,
+    dueBy: dueFor(d),
+    to: d.to,
+    content: d.content,
+  }));
+
+  const v = (field) => {
+    const val = incident[field];
+    return val && String(val).trim() ? String(val).trim() : null;
+  };
+
+  // Which incident fields each report should surface.
+  const REPORT_FIELDS = {
+    "early-warning": [
+      ["unlawful_or_malicious", "Suspected unlawful or malicious"],
+      ["cross_border", "Possible cross-border impact"],
+      ["description", "What we know so far"],
+    ],
+    notification: [
+      ["description", "Description"],
+      ["severity", "Severity"],
+      ["systems_affected", "Systems affected"],
+      ["data_affected", "Data affected"],
+      ["users_affected", "Users affected"],
+      ["cross_border", "Cross-border impact"],
+      ["indicators", "Indicators of compromise"],
+      ["mitigations", "Mitigations so far"],
+    ],
+    "final-report": [
+      ["description", "Detailed description"],
+      ["root_cause", "Root cause"],
+      ["mitigations", "Mitigations applied and ongoing"],
+      ["cross_border", "Cross-border impact"],
+      ["severity", "Final severity assessment"],
+    ],
+  };
+
+  const reports = deadlines.map((d) => ({
+    id: d.id,
+    within: d.within,
+    dueBy: dueFor(d),
+    content: d.content,
+    fields: (REPORT_FIELDS[d.id] || []).map(([field, label]) => ({
+      label,
+      value: v(field),
+    })),
+  }));
+
+  return {
+    incident: {
+      title: v("title"),
+      aware_at: awareValid ? incident.aware_at : null,
+      contact: v("contact"),
+    },
+    authority: jurisdiction.authorities || null,
+    timeline,
+    reports,
+    generated_at: null,
+  };
+}
+
+/** Render the timeline + drafts as Markdown. */
+export function formatIncidentMarkdown(result, opts = {}) {
+  if (!result) return "";
+  const now = opts.now ? new Date(opts.now) : null;
+  const L = [];
+  L.push(`# Incident report drafts${result.incident?.title ? `, ${result.incident.title}` : ""}`);
+  L.push("");
+  L.push("> **Draft reports to help you meet NIS2 deadlines, not a substitute for your authority's official form or for legal advice.** Fields marked NEEDS INPUT must be completed before sending.");
+  L.push("");
+  if (!result.incident?.aware_at) {
+    L.push("> ⚠️ No valid `aware_at` timestamp provided, so deadlines can't be computed. Set when you became aware (ISO 8601) and re-run.");
+    L.push("");
+  }
+
+  L.push("## Reporting timeline");
+  L.push("");
+  L.push(`Report to **${result.authority?.csirt || "your CSIRT"}** (supervisor: ${result.authority?.supervisor || "your supervisor"}).`);
+  L.push("");
+  L.push("| Report | Due by | Status |");
+  L.push("|--------|--------|--------|");
+  for (const t of result.timeline) {
+    let status = ", ";
+    if (t.dueBy && now) {
+      const due = new Date(t.dueBy);
+      status = now > due ? "⚠️ OVERDUE" : "on track";
+    }
+    L.push(`| ${t.within}, ${t.id} | ${t.dueBy || "set aware_at"} | ${status} |`);
+  }
+  L.push("");
+
+  for (const r of result.reports) {
+    L.push(`## Draft: ${r.id} (within ${r.within}${r.dueBy ? `, by ${r.dueBy}` : ""})`);
+    L.push("");
+    L.push(`_${r.content}_`);
+    L.push("");
+    for (const f of r.fields) {
+      L.push(`- **${f.label}:** ${f.value || "**NEEDS INPUT**"}`);
+    }
+    L.push("");
+  }
+
+  L.push("---");
+  L.push("");
+  L.push("*Generated by Penthera. Complete every NEEDS INPUT field, confirm the authority and its official channel, and send within the deadlines above.*");
+  L.push("");
+  return L.join("\n");
+}