penthera 1.1.0

package/lib/nuclei-loader.js

@@ -0,0 +1,283 @@
+/**
+ * Nuclei Community Template Loader
+ *
+ * Parses and executes community-authored Nuclei YAML templates.
+ * Supports the most common Nuclei template features:
+ *   - HTTP requests with method, path, headers, body
+ *   - Matchers: status, word, regex, negative-word, negative-regex, dsl
+ *   - Extractors: regex, json, kval
+ *   - Variables and dynamic helpers ({{BaseURL}}, {{Hostname}}, {{rand_int}})
+ *   - Multi-request templates with matchers-condition
+ *
+ * Requires the `yaml` npm package (zero-dependency YAML parser).
+ *
+ * Usage:
+ *   import { loadTemplatesFromDir, executeTemplates } from "./lib/nuclei-loader.js";
+ *   const templates = await loadTemplatesFromDir("/path/to/nuclei-templates/http");
+ *   const findings = await executeTemplates("https://target.com", templates);
+ */
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, extname } from "node:path";
+import { executeTemplate } from "./templates.js";
+
+let yamlParse = null;
+
+/** Lazy-load YAML parser (fails gracefully if not installed) */
+async function getYamlParser() {
+  if (yamlParse) return yamlParse;
+  try {
+    const mod = await import("yaml");
+    yamlParse = mod.parse || mod.default?.parse;
+    return yamlParse;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load Nuclei YAML templates from a directory (recursively).
+ *
+ * @param {string} dir - Path to templates directory
+ * @param {object} opts - { maxDepth, tags, severity, exclude }
+ * @returns {object[]} Parsed template objects
+ */
+export async function loadTemplatesFromDir(dir, opts = {}) {
+  const parse = await getYamlParser();
+  if (!parse) {
+    throw new Error(
+      'YAML parser not installed. Run: npm install yaml\n' +
+      'The "yaml" package is zero-dependency and needed to parse Nuclei community templates.',
+    );
+  }
+
+  if (!existsSync(dir)) {
+    throw new Error(`Template directory not found: ${dir}`);
+  }
+
+  const templates = [];
+  const maxDepth = opts.maxDepth || 5;
+  const tags = opts.tags ? new Set(opts.tags) : null;
+  const severity = opts.severity ? new Set(opts.severity) : null;
+  const exclude = opts.exclude ? new Set(opts.exclude) : null;
+
+  function walk(currentDir, depth = 0) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const full = join(currentDir, entry);
+      try {
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+          walk(full, depth + 1);
+        } else if (extname(entry) === ".yaml" || extname(entry) === ".yml") {
+          const template = parseTemplateFile(full, parse);
+          if (template && shouldInclude(template, { tags, severity, exclude })) {
+            templates.push(template);
+          }
+        }
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  }
+
+  walk(dir);
+  return templates;
+}
+
+/**
+ * Parse a single Nuclei YAML template file.
+ */
+function parseTemplateFile(filePath, parse) {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const doc = parse(content);
+
+    if (!doc || !doc.id || !doc.info) return null;
+
+    // Only support HTTP templates for now
+    if (!doc.http && !doc.requests) return null;
+
+    // Normalize: some templates use "requests" instead of "http"
+    const http = doc.http || doc.requests || [];
+
+    return {
+      id: doc.id,
+      info: {
+        name: doc.info.name || doc.id,
+        severity: doc.info.severity || "info",
+        tags: typeof doc.info.tags === "string"
+          ? doc.info.tags.split(",").map((t) => t.trim())
+          : (doc.info.tags || []),
+        description: doc.info.description || "",
+        reference: doc.info.reference || [],
+        classification: doc.info.classification || {},
+      },
+      variables: doc.variables || {},
+      http: http.map(normalizeHttpBlock),
+      _source: filePath,
+    };
+  } catch {
+    return null; // Skip unparseable templates
+  }
+}
+
+/**
+ * Normalize an HTTP request block to our internal format.
+ */
+function normalizeHttpBlock(block) {
+  const normalized = {
+    method: block.method || "GET",
+    path: Array.isArray(block.path) ? block.path[0] : (block.path || "/"),
+    headers: block.headers || {},
+    body: block.body || null,
+    matchers: (block.matchers || []).map(normalizeMatcher),
+    "matchers-condition": block["matchers-condition"] || "or",
+    extractors: block.extractors || [],
+  };
+
+  // Handle raw requests
+  if (block.raw && Array.isArray(block.raw)) {
+    const rawReq = block.raw[0];
+    const methodMatch = rawReq.match(/^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+(\S+)/);
+    if (methodMatch) {
+      normalized.method = methodMatch[1];
+      normalized.path = methodMatch[2];
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize a matcher to our internal format.
+ */
+function normalizeMatcher(matcher) {
+  const norm = { ...matcher };
+
+  // Nuclei uses "status" as an array, we do too
+  if (norm.type === "status" && typeof norm.status === "number") {
+    norm.status = [norm.status];
+  }
+
+  // Handle "negative" flag on word/regex matchers
+  if (norm.negative && norm.type === "word") {
+    norm.type = "negative-word";
+    delete norm.negative;
+  }
+  if (norm.negative && norm.type === "regex") {
+    norm.type = "negative-regex";
+    delete norm.negative;
+  }
+
+  return norm;
+}
+
+/**
+ * Check if a template should be included based on filters.
+ */
+function shouldInclude(template, filters) {
+  const { tags, severity, exclude } = filters;
+
+  if (exclude && exclude.has(template.id)) return false;
+
+  if (severity) {
+    const sev = template.info.severity?.toLowerCase();
+    if (!severity.has(sev)) return false;
+  }
+
+  if (tags) {
+    const templateTags = template.info.tags || [];
+    if (!templateTags.some((t) => tags.has(t))) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Execute loaded community templates against a target.
+ * Uses the same execution engine as built-in templates.
+ *
+ * @param {string} baseUrl
+ * @param {object[]} templates - Parsed template objects
+ * @param {object} opts - { onPhase, concurrency }
+ * @returns {object[]} Findings
+ */
+export async function executeTemplates(baseUrl, templates, opts = {}) {
+  const progress = opts.onPhase || (() => {});
+  const findings = [];
+
+  for (let i = 0; i < templates.length; i++) {
+    const template = templates[i];
+
+    if (i % 50 === 0) {
+      progress(`Running community templates... ${i}/${templates.length}`);
+    }
+
+    try {
+      // Resolve {{BaseURL}} and {{Hostname}} in paths
+      const hostname = new URL(baseUrl).hostname;
+      const resolved = {
+        ...template,
+        http: template.http.map((block) => ({
+          ...block,
+          path: block.path
+            .replace(/\{\{BaseURL\}\}/g, "")
+            .replace(/\{\{Hostname\}\}/g, hostname)
+            .replace(/\{\{RootURL\}\}/g, ""),
+        })),
+      };
+
+      const templateFindings = await executeTemplate(baseUrl, resolved);
+      for (const f of templateFindings) {
+        findings.push({
+          severity: f.severity,
+          title: f.name,
+          description: f.description || "",
+          url: f.matchedUrl,
+          status: f.status,
+          category: f.tags?.[0] || "community-template",
+          source: "nuclei-community",
+          templateId: f.templateId,
+          classification: template.info.classification,
+        });
+      }
+    } catch {
+      // Skip templates that error during execution
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Get stats about a template directory.
+ */
+export async function getTemplateStats(dir) {
+  const templates = await loadTemplatesFromDir(dir);
+  const bySeverity = {};
+  const byTag = {};
+
+  for (const t of templates) {
+    const sev = t.info.severity || "unknown";
+    bySeverity[sev] = (bySeverity[sev] || 0) + 1;
+    for (const tag of t.info.tags) {
+      byTag[tag] = (byTag[tag] || 0) + 1;
+    }
+  }
+
+  return {
+    total: templates.length,
+    bySeverity,
+    topTags: Object.entries(byTag)
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, 20)
+      .map(([tag, count]) => ({ tag, count })),
+  };
+}

package/lib/owasp-wstg.js

@@ -0,0 +1,204 @@
+/**
+ * OWASP Web Security Testing Guide (WSTG) coverage mapping.
+ *
+ * Maps Penthera probes and finding categories to WSTG v4.2 test IDs.
+ * @see https://owasp.org/www-project-web-security-testing-guide/
+ */
+
+/** Penthera probe → WSTG tests exercised when the probe runs. */
+export const PROBE_WSTG = [
+  { id: "reachability", probe: "Reachability & fingerprint", wstg: ["WSTG-INFO-02", "WSTG-INFO-04"], profiles: ["quick", "standard", "deep"], modes: ["url"] },
+  { id: "endpoint-discovery", probe: "Endpoint discovery", wstg: ["WSTG-INFO-06", "WSTG-INFO-07"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "tls", probe: "TLS / certificate audit", wstg: ["WSTG-CRYP-01"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "security-headers", probe: "Security headers", wstg: ["WSTG-CONF-12", "WSTG-CONF-14"], profiles: ["quick", "standard", "deep"], modes: ["url"] },
+  { id: "openapi", probe: "OpenAPI / Swagger exposure", wstg: ["WSTG-INFO-09", "WSTG-CONF-02"], profiles: ["quick", "standard", "deep"], modes: ["url"] },
+  { id: "sensitive-files", probe: "Sensitive file templates", wstg: ["WSTG-CONF-02", "WSTG-CONF-04"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "cors", probe: "CORS validation", wstg: ["WSTG-CLNT-07"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "cookie", probe: "Cookie security", wstg: ["WSTG-SESS-02"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "auth-hardening", probe: "Auth endpoint hardening", wstg: ["WSTG-ATHN-03", "WSTG-ATHN-10"], profiles: ["quick", "standard", "deep"], modes: ["url"] },
+  { id: "client-auth", probe: "Client-side-only auth detection", wstg: ["WSTG-ATHZ-02", "WSTG-CLNT-01"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "jwt", probe: "JWT probes", wstg: ["WSTG-ATHN-04", "WSTG-SESS-10"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "idor", probe: "IDOR / BOLA", wstg: ["WSTG-ATHZ-04", "WSTG-ATHZ-05"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "oauth", probe: "OAuth open redirect", wstg: ["WSTG-ATHN-11", "WSTG-CLNT-04"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "adaptive", probe: "Adaptive escalation probes", wstg: ["WSTG-ATHZ-02", "WSTG-ATHZ-04", "WSTG-CLNT-07"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "retirejs", probe: "Retire.js (JS CVEs)", wstg: ["WSTG-CONF-04", "WSTG-CLNT-02"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "param-discovery", probe: "Parameter discovery", wstg: ["WSTG-INFO-06"], profiles: ["standard", "deep"], modes: ["url"] },
+  { id: "recon", probe: "OSINT recon", wstg: ["WSTG-INFO-01", "WSTG-INFO-07"], profiles: ["deep"], modes: ["url"] },
+  { id: "sqli", probe: "SQL injection", wstg: ["WSTG-INPV-05"], profiles: ["deep"], modes: ["url"] },
+  { id: "ssti", probe: "SSTI", wstg: ["WSTG-INPV-18"], profiles: ["deep"], modes: ["url"] },
+  { id: "ssrf", probe: "SSRF", wstg: ["WSTG-INPV-19"], profiles: ["deep"], modes: ["url"] },
+  { id: "xss", probe: "Reflected XSS", wstg: ["WSTG-INPV-01", "WSTG-CLNT-01"], profiles: ["deep"], modes: ["url"] },
+  { id: "cmdi", probe: "Command injection", wstg: ["WSTG-INPV-12"], profiles: ["deep"], modes: ["url"] },
+  { id: "open-redirect", probe: "Open redirect (injection suite)", wstg: ["WSTG-CLNT-04"], profiles: ["deep"], modes: ["url"] },
+  { id: "api-fuzzing", probe: "API fuzzing", wstg: ["WSTG-INPV-11", "WSTG-BUSL-05"], profiles: ["deep"], modes: ["url"] },
+  { id: "secret-scanning", probe: "Secret scanning", wstg: ["WSTG-CONF-02", "WSTG-CONF-05"], profiles: ["quick", "standard", "deep"], modes: ["repo"] },
+  { id: "trust-boundary", probe: "Route / trust-boundary analysis", wstg: ["WSTG-ATHZ-02", "WSTG-CONF-02"], profiles: ["quick", "standard", "deep"], modes: ["repo"] },
+  { id: "risky-patterns", probe: "Risky code patterns", wstg: ["WSTG-INPV-01", "WSTG-INPV-12"], profiles: ["standard", "deep"], modes: ["repo"] },
+];
+
+/** Finding category/source → WSTG tags for individual findings. */
+export const FINDING_WSTG = {
+  tls: ["WSTG-CRYP-01"],
+  exposure: ["WSTG-CONF-02", "WSTG-CONF-04"],
+  cors: ["WSTG-CLNT-07"],
+  cookie: ["WSTG-SESS-02"],
+  auth: ["WSTG-ATHN-03", "WSTG-ATHN-04"],
+  "auth-bypass": ["WSTG-ATHZ-02", "WSTG-ATHN-04"],
+  secrets: ["WSTG-CONF-02", "WSTG-CONF-05"],
+  sqli: ["WSTG-INPV-05"],
+  ssti: ["WSTG-INPV-18"],
+  ssrf: ["WSTG-INPV-19"],
+  xss: ["WSTG-INPV-01", "WSTG-CLNT-01"],
+  cmdi: ["WSTG-INPV-12"],
+  "open-redirect": ["WSTG-CLNT-04", "WSTG-ATHN-11"],
+  fuzzing: ["WSTG-INPV-11"],
+  recon: ["WSTG-INFO-01"],
+  cve: ["WSTG-CONF-04"],
+  "rate-limiting": ["WSTG-ATHN-10"],
+  "code-pattern": ["WSTG-INPV-01", "WSTG-INPV-12"],
+  config: ["WSTG-CONF-02"],
+};
+
+const SOURCE_WSTG = {
+  "header-audit": ["WSTG-CONF-12"],
+  "openapi-scan": ["WSTG-INFO-09", "WSTG-CONF-02"],
+  "auth-probe": ["WSTG-ATHN-03", "WSTG-ATHN-10"],
+  "client-auth-probe": ["WSTG-ATHZ-02", "WSTG-CLNT-01"],
+  "jwt-probe": ["WSTG-ATHN-04", "WSTG-SESS-10"],
+  "idor-probe": ["WSTG-ATHZ-04", "WSTG-ATHZ-05"],
+  "oauth-probe": ["WSTG-ATHN-11", "WSTG-CLNT-04"],
+  "adaptive-probe": ["WSTG-ATHZ-02", "WSTG-ATHZ-04"],
+  "secret-scan": ["WSTG-CONF-02", "WSTG-CONF-05"],
+  "trust-boundary": ["WSTG-ATHZ-02"],
+  "static-analysis": ["WSTG-INPV-01"],
+};
+
+const WSTG_NAMES = {
+  "WSTG-INFO-01": "Conduct Search Engine Discovery",
+  "WSTG-INFO-02": "Fingerprint Web Server",
+  "WSTG-INFO-04": "Enumerate Applications on Webserver",
+  "WSTG-INFO-06": "Identify Application Entry Points",
+  "WSTG-INFO-07": "Map Execution Paths Through Application",
+  "WSTG-INFO-09": "Fingerprint Web Application",
+  "WSTG-CONF-02": "Test Application Platform Configuration",
+  "WSTG-CONF-04": "Review Old Backup and Unreferenced Files",
+  "WSTG-CONF-05": "Enumerate Infrastructure and Application Admin Interfaces",
+  "WSTG-CONF-12": "Test for Content Security Policy",
+  "WSTG-CONF-13": "Test for Path Confusion",
+  "WSTG-CONF-14": "Test Other HTTP Security Header Misconfigurations",
+  "WSTG-CRYP-01": "Testing for Weak Transport Layer Security",
+  "WSTG-CRYP-02": "Testing for Padding Oracle",
+  "WSTG-ATHN-03": "Testing for Weak Lock Out Mechanism",
+  "WSTG-ATHN-04": "Testing for Bypassing Authentication Schema",
+  "WSTG-ATHN-10": "Testing for Weaker Authentication in Alternative Channel",
+  "WSTG-ATHN-11": "Testing Multi-Factor Authentication",
+  "WSTG-ATHZ-02": "Testing for Bypassing Authorization Schema",
+  "WSTG-ATHZ-04": "Testing for Insecure Direct Object References",
+  "WSTG-ATHZ-05": "Testing for OAuth Weaknesses",
+  "WSTG-SESS-02": "Testing for Cookies Attributes",
+  "WSTG-SESS-10": "Testing JSON Web Tokens",
+  "WSTG-INPV-01": "Testing for Reflected Cross Site Scripting",
+  "WSTG-INPV-05": "Testing for SQL Injection",
+  "WSTG-INPV-11": "Testing for Code Injection",
+  "WSTG-INPV-12": "Testing for Command Injection",
+  "WSTG-INPV-18": "Testing for Server-Side Template Injection",
+  "WSTG-INPV-19": "Testing for Server-Side Request Forgery",
+  "WSTG-CLNT-01": "Testing for DOM-Based Cross Site Scripting",
+  "WSTG-CLNT-02": "Testing for JavaScript Execution",
+  "WSTG-CLNT-04": "Testing for Client-Side URL Redirect",
+  "WSTG-CLNT-07": "Testing Cross Origin Resource Sharing",
+  "WSTG-BUSL-05": "Test Number of Times a Function Can Be Used Limits",
+};
+
+function unique(arr) {
+  return [...new Set(arr)];
+}
+
+/** Resolve WSTG tags for a single finding. */
+export function resolveWstgTags(finding) {
+  const tags = [];
+  if (finding?.category && FINDING_WSTG[finding.category]) {
+    tags.push(...FINDING_WSTG[finding.category]);
+  }
+  if (finding?.source && SOURCE_WSTG[finding.source]) {
+    tags.push(...SOURCE_WSTG[finding.source]);
+  }
+  const blob = `${finding?.title || ""} ${finding?.description || ""}`.toLowerCase();
+  if (/security header|content-security-policy|x-frame-options/i.test(blob)) {
+    tags.push("WSTG-CONF-12", "WSTG-CONF-14");
+  }
+  if (/openapi|swagger|\/docs|redoc/i.test(blob)) tags.push("WSTG-INFO-09");
+  if (/idor|bola|direct object/i.test(blob)) tags.push("WSTG-ATHZ-04");
+  if (/oauth|redirect_uri/i.test(blob)) tags.push("WSTG-ATHZ-05", "WSTG-CLNT-04");
+  return unique(tags);
+}
+
+/** WSTG tests exercised for a given scan profile and modes. */
+export function getProbesForScan(result, profile = "standard") {
+  // When the scan recorded which probes actually executed, trust that, the
+  // coverage report must never claim a probe ran when it didn't (e.g. injection
+  // probes that early-returned because no endpoints were discovered, or probes
+  // skipped by profile). Fall back to the profile/mode catalog only when no
+  // execution record is present (older callers, unit tests).
+  const executed = Array.isArray(result?.executedProbes) ? new Set(result.executedProbes) : null;
+  if (executed) {
+    return PROBE_WSTG.filter((p) => executed.has(p.id));
+  }
+  const modes = result?.modes || (result?.mode ? [result.mode] : ["url"]);
+  return PROBE_WSTG.filter((p) => {
+    if (!p.profiles.includes(profile)) return false;
+    return p.modes.some((m) => modes.includes(m));
+  });
+}
+
+/** Build coverage summary for reports. */
+export function buildWstgCoverage(result, profile = "standard") {
+  const probes = getProbesForScan(result, profile);
+  const exercised = unique(probes.flatMap((p) => p.wstg));
+  const triggered = unique(
+    (result?.findings || []).flatMap((f) => resolveWstgTags(f)),
+  );
+
+  return {
+    profile,
+    probesRun: probes.length,
+    wstgExercised: exercised.sort(),
+    wstgTriggered: triggered.sort(),
+    wstgNames: WSTG_NAMES,
+  };
+}
+
+/** Markdown section for reports. */
+export function formatWstgMarkdown(coverage) {
+  const lines = [];
+  lines.push("## OWASP WSTG coverage");
+  lines.push("");
+  lines.push(
+    `This scan exercised **${coverage.probesRun}** Penthera probes mapped to ` +
+    `**${coverage.wstgExercised.length}** OWASP Web Security Testing Guide (WSTG v4.2) test areas.`,
+  );
+  lines.push("");
+  lines.push("| WSTG ID | Test name | Status |");
+  lines.push("|---------|-----------|--------|");
+
+  for (const id of coverage.wstgExercised) {
+    const name = coverage.wstgNames[id] || "See OWASP WSTG";
+    const status = coverage.wstgTriggered.includes(id) ? "Finding detected" : "Probed, no finding";
+    lines.push(`| \`${id}\` | ${name} | ${status} |`);
+  }
+
+  lines.push("");
+  lines.push(
+    "> Full mapping: [docs/owasp-wstg-coverage.md](https://github.com/danoszz/penthera/blob/main/docs/owasp-wstg-coverage.md)",
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** Enrich findings with wstg tags (returns new array). */
+export function enrichFindingsWithWstg(findings) {
+  return (findings || []).map((f) => ({
+    ...f,
+    wstg: resolveWstgTags(f),
+  }));
+}