penthera 1.1.0

package/lib/templates.js

@@ -0,0 +1,364 @@
+/**
+ * YAML Template Engine (inspired by Nuclei)
+ *
+ * Run declarative vulnerability checks defined in YAML files.
+ * Compatible with a subset of Nuclei's template format.
+ */
+import { joinUrl } from "../src/utils/url.js";
+
+/**
+ * Execute a single template check against a target.
+ *
+ * @param {string} baseUrl - Target URL
+ * @param {object} template - Parsed YAML template object
+ * @returns {Array<object>} Findings
+ */
+export async function executeTemplate(baseUrl, template) {
+  const findings = [];
+
+  for (const req of template.http || []) {
+    const url = joinUrl(baseUrl, req.path.replace("{{BaseURL}}", ""));
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
+
+    try {
+      const fetchOpts = {
+        method: req.method || "GET",
+        headers: req.headers || {},
+        signal: controller.signal,
+        redirect: "manual",
+      };
+      if (req.body && ["POST", "PUT", "PATCH"].includes(fetchOpts.method)) {
+        fetchOpts.body = req.body;
+        if (!fetchOpts.headers["Content-Type"]) {
+          fetchOpts.headers["Content-Type"] = "application/json";
+        }
+      }
+
+      const res = await fetch(url, fetchOpts);
+      const body = await res.text().catch(() => "");
+      const headerString = [...res.headers.entries()]
+        .map(([k, v]) => `${k}: ${v}`).join("\n");
+
+      // Run matchers
+      const matchResults = (req.matchers || []).map(matcher =>
+        runMatcher(matcher, { status: res.status, body, headers: headerString, res }),
+      );
+
+      // Evaluate matchers-condition (default: OR for single matcher, AND for multiple)
+      const condition = req["matchers-condition"] || (matchResults.length > 1 ? "and" : "or");
+      const matched = condition === "and"
+        ? matchResults.every(Boolean)
+        : matchResults.some(Boolean);
+
+      if (matched && matchResults.length > 0) {
+        // Run extractors
+        const extracted = {};
+        for (const extractor of req.extractors || []) {
+          const result = runExtractor(extractor, { body, headers: headerString });
+          if (result) extracted[extractor.name || "extracted"] = result;
+        }
+
+        findings.push({
+          templateId: template.id,
+          name: template.info?.name || template.id,
+          severity: template.info?.severity || "info",
+          tags: template.info?.tags || [],
+          description: template.info?.description || "",
+          matchedUrl: url,
+          status: res.status,
+          extracted,
+        });
+      }
+    } catch (err) {
+      if (err.name !== "AbortError") {
+        // Network error, skip
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Run a single matcher against response data.
+ */
+function runMatcher(matcher, ctx) {
+  const part = matcher.part || "body";
+  const target = part === "header" ? ctx.headers : ctx.body;
+
+  switch (matcher.type) {
+    case "status":
+      return (matcher.status || []).includes(ctx.status);
+
+    case "word": {
+      const words = matcher.words || [];
+      const check = (w) => target.includes(w);
+      return matcher.condition === "and"
+        ? words.every(check)
+        : words.some(check);
+    }
+
+    case "regex": {
+      const patterns = matcher.regex || [];
+      const check = (p) => new RegExp(p, matcher.flags || "").test(target);
+      return matcher.condition === "and"
+        ? patterns.every(check)
+        : patterns.some(check);
+    }
+
+    case "negative-word": {
+      const words = matcher.words || [];
+      return words.every(w => !target.includes(w));
+    }
+
+    case "negative-regex": {
+      const patterns = matcher.regex || [];
+      return patterns.every(p => !new RegExp(p).test(target));
+    }
+
+    default:
+      return false;
+  }
+}
+
+/**
+ * Run a single extractor against response data.
+ */
+function runExtractor(extractor, ctx) {
+  const part = extractor.part || "body";
+  const target = part === "header" ? ctx.headers : ctx.body;
+
+  switch (extractor.type) {
+    case "regex": {
+      for (const pattern of extractor.regex || []) {
+        const match = target.match(new RegExp(pattern));
+        if (match) return match[extractor.group || 0];
+      }
+      return null;
+    }
+
+    case "json": {
+      try {
+        const data = JSON.parse(target);
+        for (const path of extractor.json || []) {
+          const value = path.split(".").reduce((obj, key) => obj?.[key], data);
+          if (value !== undefined) return value;
+        }
+      } catch { /* not JSON */ }
+      return null;
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Built-in security templates (no YAML parser needed).
+ * These cover the most common web app vulnerabilities.
+ * Inspired by Nuclei's community templates.
+ */
+export const BUILT_IN_TEMPLATES = [
+  // ── Exposed sensitive files ──────────────────────────────────────────
+  {
+    id: "env-file-exposure",
+    info: { name: ".env file exposed", severity: "critical", tags: ["exposure", "config"] },
+    http: [{
+      method: "GET", path: "/.env",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["DB_", "API_KEY", "SECRET", "PASSWORD", "FIREBASE_", "STRIPE_"], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+  {
+    id: "env-local-exposure",
+    info: { name: ".env.local file exposed", severity: "critical", tags: ["exposure", "config"] },
+    http: [{
+      method: "GET", path: "/.env.local",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["="], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+  {
+    id: "git-config-exposure",
+    info: { name: "Git config exposed", severity: "high", tags: ["exposure", "git"] },
+    http: [{
+      method: "GET", path: "/.git/config",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["[core]", "[remote"], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+  {
+    id: "git-head-exposure",
+    info: { name: "Git HEAD exposed", severity: "medium", tags: ["exposure", "git"] },
+    http: [{
+      method: "GET", path: "/.git/HEAD",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["ref: refs/"] },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+  {
+    id: "service-account-key-exposure",
+    info: { name: "Service account key exposed", severity: "critical", tags: ["exposure", "firebase", "gcp"] },
+    http: [{
+      method: "GET", path: "/serviceAccountKey.json",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["private_key", "client_email"], condition: "and" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+
+  // ── Source map exposure ──────────────────────────────────────────────
+  {
+    id: "nextjs-sourcemap-exposure",
+    info: { name: "Next.js source maps exposed", severity: "medium", tags: ["exposure", "nextjs"],
+      description: "Source maps allow attackers to read your original source code" },
+    http: [{
+      method: "GET", path: "/_next/static/chunks/main.js.map",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["mappings", "sources"], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+
+  // ── Firebase specific ───────────────────────────────────────────────
+  {
+    id: "firebase-database-open-read",
+    info: { name: "Firebase Realtime DB open read", severity: "high", tags: ["firebase", "misconfiguration"] },
+    http: [{
+      method: "GET", path: "/.json",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "negative-word", words: ["Permission denied", "error"] },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+
+  // ── Security headers (also checked by lib/blackbox/headers.js) ────────
+
+  // ── Debug / internal endpoints ──────────────────────────────────────
+  {
+    id: "nextjs-debug-endpoint",
+    info: { name: "Next.js debug endpoint accessible", severity: "medium", tags: ["nextjs", "debug"] },
+    http: [{
+      method: "GET", path: "/api/__nextjs_original-stack-frame",
+      matchers: [{ type: "status", status: [200, 400] }],
+    }],
+  },
+  {
+    id: "graphql-introspection",
+    info: { name: "GraphQL introspection enabled", severity: "medium", tags: ["graphql", "misconfiguration"] },
+    http: [{
+      method: "POST", path: "/graphql",
+      headers: { "Content-Type": "application/json" },
+      body: '{"query":"{ __schema { types { name } } }"}',
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["__schema", "__type"], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+  {
+    id: "swagger-ui-exposed",
+    info: { name: "Swagger UI exposed", severity: "low", tags: ["exposure", "api-docs"] },
+    http: [{
+      method: "GET", path: "/api/docs",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["swagger", "openapi", "api-docs"], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+
+  // ── CVE checks ────────────��─────────────────────────────────────────
+  {
+    id: "cve-2025-29927-nextjs-middleware-bypass",
+    info: { name: "CVE-2025-29927: Next.js middleware bypass", severity: "critical",
+      tags: ["cve", "nextjs", "auth-bypass"],
+      description: "x-middleware-subrequest header can bypass Next.js middleware auth checks" },
+    http: [{
+      method: "GET", path: "/api/admin/users",
+      headers: { "x-middleware-subrequest": "middleware:middleware:middleware:middleware:middleware" },
+      matchers: [{ type: "status", status: [200] }],
+    }],
+  },
+
+  // ── CORS misconfiguration ───────────────────────────────────────────
+  {
+    id: "cors-wildcard",
+    info: { name: "CORS allows wildcard origin", severity: "medium", tags: ["cors", "misconfiguration"] },
+    http: [{
+      method: "GET", path: "/api/health",
+      headers: { Origin: "https://evil-attacker.com" },
+      matchers: [
+        { type: "word", words: ["https://evil-attacker.com"], part: "header" },
+      ],
+    }],
+  },
+  {
+    id: "cors-null-origin",
+    info: { name: "CORS allows null origin", severity: "high", tags: ["cors", "misconfiguration"] },
+    http: [{
+      method: "GET", path: "/api/health",
+      headers: { Origin: "null" },
+      matchers: [
+        { type: "regex", regex: ["access-control-allow-origin:\\s*null"], part: "header" },
+      ],
+    }],
+  },
+
+  // (An "open redirect via callback" template lived here but was removed: a
+  // declarative word-matcher on the Location header can't tell a real open
+  // redirect from a same-site canonicalization redirect that merely preserves
+  // the payload in the query string. The code-based OAuth probe covers this
+  // path correctly by resolving the redirect's destination origin.)
+
+  // ── Directory listing ───────────────────────────────────────────────
+  {
+    id: "directory-listing",
+    info: { name: "Directory listing enabled", severity: "low", tags: ["exposure", "misconfiguration"] },
+    http: [{
+      method: "GET", path: "/api/",
+      matchers: [
+        { type: "status", status: [200] },
+        { type: "word", words: ["Index of", "Directory listing", "<pre>"], condition: "or" },
+      ],
+      "matchers-condition": "and",
+    }],
+  },
+];
+
+/**
+ * Run all built-in templates against a target.
+ * @param {string} baseUrl
+ * @returns {Array<object>} All findings
+ */
+export async function runBuiltInTemplates(baseUrl) {
+  const allFindings = [];
+  for (const template of BUILT_IN_TEMPLATES) {
+    const findings = await executeTemplate(baseUrl, template);
+    allFindings.push(...findings);
+  }
+  return allFindings;
+}

package/lib/tls.js

@@ -0,0 +1,145 @@
+/**
+ * TLS/SSL Scanner
+ *
+ * Checks certificate validity, cipher strength, and protocol version
+ * using Node.js built-in `tls` module, zero dependencies.
+ *
+ * Inspired by: httpx (JARM fingerprinting), testssl.sh, ssl-labs
+ */
+import tls from "node:tls";
+
+const WEAK_CIPHERS = new Set([
+  "DES-CBC3-SHA", "RC4-SHA", "RC4-MD5", "DES-CBC-SHA",
+  "EXP-RC4-MD5", "EXP-DES-CBC-SHA", "EXP-RC2-CBC-MD5",
+  "NULL-MD5", "NULL-SHA", "NULL-SHA256",
+]);
+
+const WEAK_PROTOCOLS = new Set(["TLSv1", "TLSv1.1", "SSLv3"]);
+
+/**
+ * Check TLS configuration for a hostname.
+ *
+ * @param {string} hostname - Target hostname (no protocol)
+ * @param {number} port - Target port (default: 443)
+ * @param {number} timeout - Connection timeout in ms
+ * @returns {object} TLS scan result
+ */
+export function checkTls(hostname, port = 443, timeout = 10_000) {
+  return new Promise((resolve) => {
+    const socket = tls.connect(
+      { host: hostname, port, servername: hostname, rejectUnauthorized: false },
+      () => {
+        const cert = socket.getPeerCertificate(true);
+        const protocol = socket.getProtocol();
+        const cipher = socket.getCipher();
+        const authorized = socket.authorized;
+        const authError = socket.authorizationError || null;
+        socket.end();
+
+        const now = new Date();
+        const validFrom = new Date(cert.valid_from);
+        const validTo = new Date(cert.valid_to);
+        const daysUntilExpiry = Math.floor((validTo - now) / 86400000);
+
+        // Extract SAN (Subject Alternative Names)
+        const altNames = cert.subjectaltname
+          ? cert.subjectaltname.split(", ").map((s) => s.replace("DNS:", ""))
+          : [];
+
+        // Determine findings
+        const findings = [];
+
+        if (!authorized) {
+          findings.push({
+            severity: "high",
+            title: "TLS certificate not trusted",
+            description: authError || "Certificate validation failed",
+          });
+        }
+
+        if (daysUntilExpiry < 0) {
+          findings.push({
+            severity: "critical",
+            title: "TLS certificate expired",
+            description: `Expired ${Math.abs(daysUntilExpiry)} days ago (${validTo.toISOString().slice(0, 10)})`,
+          });
+        } else if (daysUntilExpiry < 30) {
+          findings.push({
+            severity: "medium",
+            title: "TLS certificate expiring soon",
+            description: `Expires in ${daysUntilExpiry} days (${validTo.toISOString().slice(0, 10)})`,
+          });
+        }
+
+        if (WEAK_PROTOCOLS.has(protocol)) {
+          findings.push({
+            severity: "high",
+            title: `Weak TLS protocol: ${protocol}`,
+            description: "TLSv1.0 and TLSv1.1 are deprecated. Use TLSv1.2 or TLSv1.3.",
+          });
+        }
+
+        if (WEAK_CIPHERS.has(cipher?.name)) {
+          findings.push({
+            severity: "high",
+            title: `Weak cipher suite: ${cipher.name}`,
+            description: "This cipher is considered insecure.",
+          });
+        }
+
+        if (cipher?.name && !cipher.name.includes("GCM") && !cipher.name.includes("CHACHA")) {
+          findings.push({
+            severity: "low",
+            title: `Non-AEAD cipher: ${cipher.name}`,
+            description: "Consider using AEAD ciphers (GCM, ChaCha20-Poly1305) for better security.",
+          });
+        }
+
+        resolve({
+          valid: authorized,
+          protocol,
+          cipher: cipher?.name || "unknown",
+          cipherVersion: cipher?.version || "unknown",
+          issuer: cert.issuer?.O || cert.issuer?.CN || "unknown",
+          subject: cert.subject?.CN || "unknown",
+          altNames,
+          validFrom: validFrom.toISOString(),
+          validTo: validTo.toISOString(),
+          daysUntilExpiry,
+          serialNumber: cert.serialNumber,
+          fingerprint256: cert.fingerprint256,
+          findings,
+        });
+      },
+    );
+
+    socket.setTimeout(timeout);
+    socket.on("timeout", () => {
+      socket.destroy();
+      resolve({
+        valid: false,
+        protocol: null,
+        cipher: null,
+        error: "Connection timeout",
+        findings: [{
+          severity: "medium",
+          title: "TLS connection timeout",
+          description: `Could not establish TLS connection within ${timeout}ms`,
+        }],
+      });
+    });
+    socket.on("error", (err) => {
+      resolve({
+        valid: false,
+        protocol: null,
+        cipher: null,
+        error: err.message,
+        findings: [{
+          severity: "medium",
+          title: "TLS connection failed",
+          description: err.message,
+        }],
+      });
+    });
+  });
+}

package/lib/whitebox/frameworks.js

@@ -0,0 +1,139 @@
+/**
+ * Discover API routes in Express, Hono, and Fastify projects.
+ */
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const SKIP = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", "vendor"]);
+const CODE_EXT = /\.(js|ts|mjs|cjs)$/;
+
+const ROUTE_DIRS = ["routes", "src/routes", "api", "src/api", "server/routes", "src/server/routes"];
+
+// Express / Hono / Fastify route patterns
+const ROUTE_RES = [
+  /(?:app|router|server|api|hono)\.(get|post|put|patch|delete|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+  /(?:app|router|server|api|hono)\.(get|post|put|patch|delete|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+  /fastify\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+  /\.(get|post|put|patch|delete)\s*\(\s*['"`](\/[^'"`]+)['"`]/gi,
+  /method:\s*['"](GET|POST|PUT|PATCH|DELETE)['"]\s*,\s*url:\s*['"`]([^'"`]+)['"`]/gi,
+];
+
+function walkCodeFiles(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir)) {
+    if (SKIP.has(entry)) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      walkCodeFiles(full, files);
+    } else if (CODE_EXT.test(entry)) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function extractRoutesFromSource(source, filePath, repoPath) {
+  const routes = [];
+  const seen = new Set();
+
+  for (const re of ROUTE_RES) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+      const method = m[1].toUpperCase();
+      let path = m[2];
+      if (!path.startsWith("/")) path = `/${path}`;
+      const key = `${method}:${path}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      routes.push({
+        url: path,
+        filePath: relative(repoPath, filePath),
+        methods: [method],
+        auth: classifyAuth(source),
+        inputs: [],
+        externalCalls: [],
+        securityPatterns: detectRisk(source),
+        hasParams: path.includes(":") || path.includes("*"),
+        framework: detectFramework(source),
+        sourceLength: source.length,
+      });
+    }
+  }
+
+  return routes;
+}
+
+function detectFramework(source) {
+  if (/from\s+['"]hono['"]|new Hono/.test(source)) return "hono";
+  if (/from\s+['"]fastify['"]|fastify\(/.test(source)) return "fastify";
+  if (/from\s+['"]express['"]|require\s*\(\s*['"]express['"]\)/.test(source)) return "express";
+  return "node";
+}
+
+function classifyAuth(source) {
+  const auth = [];
+  if (/verifyAdmin|isAdmin|requireAdmin/.test(source)) auth.push("admin");
+  if (/requireAuth|getSession|verifyToken|jwt\.verify/.test(source)) auth.push("user");
+  if (/CRON_SECRET|verifyCron/.test(source)) auth.push("cron");
+  if (auth.length === 0) auth.push("public");
+  return auth;
+}
+
+function detectRisk(source) {
+  const patterns = [];
+  if (/eval\s*\(/.test(source)) patterns.push("RISK:eval");
+  if (/innerHTML/.test(source)) patterns.push("RISK:innerHTML");
+  if (/exec\s*\(|spawn\s*\(/.test(source)) patterns.push("RISK:command-injection");
+  return patterns;
+}
+
+/**
+ * @param {string} repoPath
+ * @returns {object[]} routes in attack-surface shape
+ */
+export function discoverFrameworkRoutes(repoPath) {
+  const all = [];
+  const seen = new Set();
+
+  const scanFiles = (dir) => {
+    for (const file of walkCodeFiles(dir)) {
+      let source;
+      try {
+        source = readFileSync(file, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!/(express|hono|fastify|Router|\.get\s*\(|\.post\s*\()/i.test(source)) continue;
+
+      for (const route of extractRoutesFromSource(source, file, repoPath)) {
+        const key = `${route.methods[0]}:${route.url}:${route.filePath}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        all.push(route);
+      }
+    }
+  };
+
+  for (const dir of ROUTE_DIRS) {
+    scanFiles(join(repoPath, dir));
+  }
+
+  // Also scan top-level server entry files
+  for (const entry of ["server.js", "server.ts", "index.js", "index.ts", "app.js", "app.ts", "src/index.ts"]) {
+    const full = join(repoPath, entry);
+    if (!existsSync(full)) continue;
+    try {
+      const source = readFileSync(full, "utf-8");
+      for (const route of extractRoutesFromSource(source, full, repoPath)) {
+        const key = `${route.methods[0]}:${route.url}:${route.filePath}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        all.push(route);
+      }
+    } catch { /* skip */ }
+  }
+
+  return all.sort((a, b) => a.url.localeCompare(b.url));
+}