penthera 1.1.0 → 1.2.0

package/docs/compliance-nis2.md

@@ -0,0 +1,166 @@
+# Compliance: NIS2 and the cyberwetgeving
+
+Back to the [README](../README.md).
+
+The EU NIS2 directive and its national transpositions (the Cyberbeveiligingswet
+in the Netherlands, the NIS2-wet in Belgium) put a duty of care, the *zorgplicht*,
+on in-scope organisations. That duty is the set of risk-management measures in
+Article 21(2) of the directive. Most of them are organisational. Some are
+technical and testable, and that is the part Penthera helps with.
+
+Penthera does not make you compliant and does not certify anything. What it gives
+you is automated, repeatable technical evidence for the measures a scanner can
+honestly verify: the kind of artefact you can attach to a risk file, show an
+auditor, or run in CI so a regression shows up before it ships.
+
+| Art. 21(2) measure | What Penthera does | Coverage |
+|--------------------|--------------------|----------|
+| **(a)** Risk analysis & information-security policy | Findings, severity, and baseline history feed your risk analysis | Evidence |
+| **(b)** Incident handling | `--incident` drafts the 24h / 72h / 1-month reports against your authority's required content | Partial |
+| **(c)** Business continuity, backup, crisis management | Organisational; outside a scanner's reach | Out of scope |
+| **(d)** Supply-chain security | Known-CVE checks on JS dependencies, leaked credentials, a CycloneDX SBOM (`--sbom`), and passive supplier rating (`--suppliers`) | Partial |
+| **(e)** Security in acquisition, development & maintenance; **vulnerability handling** | The core: black- + white-box scanning mapped to OWASP WSTG, SARIF → GitHub, baseline regression, scan-and-fix loop | **Strong** |
+| **(f)** Assessing the effectiveness of measures | Baseline diff, re-scan-to-verify, and `--history` tracking of time-to-fix, ageing, and drift | Partial |
+| **(g)** Cyber hygiene & training | Remediation playbook + secure-defaults guidance (guidance, not a training programme) | Partial |
+| **(h)** Cryptography & encryption | TLS protocol/cipher/certificate audit, HSTS, cookie `Secure` (transport layer only) | Partial |
+| **(i)** HR security, **access control**, asset management | Access control tested: JWT, IDOR/BOLA, OAuth redirect, client-side-auth, trust-boundary mapping | Partial |
+| **(j)** Multi-factor authentication & secure communications | MFA probe (on the roadmap) | Planned |
+
+**Coverage key:** *Strong* = automated technical testing · *Partial* = part of the
+measure · *Evidence* = output feeds the measure, no direct test · *Planned* = on the
+roadmap · *Out of scope* = organisational or physical.
+
+In practice, Penthera today gives you solid automated evidence for the
+secure-development and vulnerability-handling duty (e), which is the technical
+heart of the zorgplicht, plus meaningful coverage of supply chain (d),
+cryptography in transit (h), access control (i), and effectiveness testing (f).
+That is not the whole duty of care, but it is a real, defensible start you can run
+today and re-run on every deploy.
+
+> **Not legal advice, not a certification, not a guarantee of compliance.**
+> Penthera automates the technical-testing part of the duty of care. The
+> directive's organisational duties (governance, risk-management policy,
+> incident-notification processes, supply-chain contracts, staff training) need
+> human process and, where it matters, review by a qualified advisor. For an
+> authoritative reading, consult your national authority (the NCSC in the
+> Netherlands, the CCB and its CyFun framework in Belgium) or a specialised jurist.
+
+Generate this mapping for your own scan with `--framework nis2`. It adds a
+per-run coverage table (which measures *this* scan actually exercised, driven by
+the probes that ran) to the terminal, Markdown, and JSON reports:
+
+```bash
+penthera https://myapp.com --framework nis2 -o reports/scan.json
+```
+
+### Readiness report (clone → report in two commands)
+
+Go further than the mapping: combine the scan with a short offline
+self-assessment (the organisational measures a scanner can't test, like policies,
+backups, training, and MFA) into a full NIS2 readiness report. Every Article 21
+measure is marked `met / partial / gap / n-a`, with proportionality notes, your
+incident-reporting deadlines, and provenance on every piece of evidence.
+
+```bash
+# 1. Create your self-assessment (offline, one-time). Fill in yes | partial | no | na.
+penthera --assessment-init assessment.json
+
+# 2. Scan + self-assessment → readiness report (writes reports/scan-readiness.md)
+penthera https://myapp.com --repo . --readiness --assessment assessment.json -o reports/scan.json
+```
+
+The readiness report is **evidence and self-assessment tooling, not a
+certification**. It is provenance-linked (`source, method, collected_at,
+confidence`) and reproducible, and it lists exactly what only you can attest to.
+Jurisdiction specifics live in [`lib/jurisdictions/nl.json`](../lib/jurisdictions/nl.json) (NL today; BE and
+others are just added config).
+
+### Answer a customer's security questionnaire
+
+The questionnaire blocking your deal, drafted from evidence you already have:
+
+```bash
+# one question per line, pasted from the customer's form
+penthera https://myapp.com --readiness --assessment assessment.json --questionnaire questions.txt
+```
+
+Each question is mapped to the Article 21 measure it belongs to and answered
+from the scan and your self-assessment, with the backing evidence cited.
+Anything Penthera can't map is marked `NEEDS HUMAN INPUT` instead of guessed.
+Review every answer before you send it.
+
+### Policy pack
+
+Generate the proportionate written policies NIS2 expects, pre-filled from your
+readiness gaps and the NL incident deadlines:
+
+```bash
+penthera --policy-pack ./policies --org "Your Company" --readiness --assessment assessment.json
+```
+
+Writes editable Markdown starting points: information security, access control,
+incident response, backup/continuity, acceptable use, supplier security, and
+vulnerability management. **Templates, not legal advice.** Keep them short and
+used. A two-page policy that genuinely exists is what "proportionate" means.
+
+### Incident-report helper
+
+NIS2 has hard reporting deadlines (24h early warning, 72h notification, 1-month
+final report). If something happens, get the timeline and draft reports:
+
+```bash
+penthera --incident-init incident.json   # fill in what happened (set aware_at)
+penthera --incident incident.json        # writes incident-reports.md
+```
+
+It computes your three deadlines from when you became aware, flags anything
+overdue, and drafts the early-warning, notification, and final report against
+the required content, with `NEEDS INPUT` where you still have to fill in facts.
+**These are drafts to help you meet the deadlines, not a substitute for your
+authority's official form.**
+
+### Software bill of materials (SBOM)
+
+Emit a standard CycloneDX SBOM of your dependencies. It's what enterprises
+increasingly require of suppliers, and direct evidence for supply-chain security
+(measure d):
+
+```bash
+penthera --repo . --sbom sbom.cdx.json
+```
+
+Parses `package-lock.json` / `package.json` / `requirements.txt` offline (no
+network), with resolved versions and package URLs (purls).
+
+### Remediation tracking (the audit loop)
+
+Closing findings matters more than finding them. Track them over time:
+time-to-fix, ageing of open items, and what changed since the last scan (evidence
+for measure f, effectiveness):
+
+```bash
+penthera https://myapp.com --history reports/history.json -o reports/scan.json
+```
+
+Each run folds the current findings into a small history keyed by a **stable
+fingerprint** (so a re-worded or re-counted finding isn't mistaken for a new
+one), then reports open vs resolved, median time-to-fix, and ageing buckets.
+Re-run on a cadence to watch the trend.
+
+### Supplier rating (passive)
+
+Assess your suppliers' public security posture for supply-chain risk (measure d):
+
+```bash
+printf 'supplier1.com\nsupplier2.com\n' > suppliers.txt
+penthera --suppliers suppliers.txt
+```
+
+**Strictly passive and public-data-only.** One homepage GET (security headers),
+a TLS handshake (certificate), and public DNS lookups (SPF/DMARC/MX) per domain.
+No endpoint discovery, no auth probes, no intrusive testing. You get a
+red/amber/green rating per supplier. It's a screening aid for your own vendor
+risk assessment, **not** an authorised penetration test of the supplier.
+
+Because the mapping targets the NIS2 directive itself, it applies across the
+national transpositions; jurisdiction-specific profiles (NL, BE) are on the roadmap.

package/docs/examples/github-actions-scan.yml

@@ -0,0 +1,55 @@
+# Example: scan your staging URL with Penthera on a schedule.
+#
+# Copy this file into YOUR app's repo as `.github/workflows/penthera.yml` and add
+# a `PENTEST_STAGING_URL` repository secret. Only point it at a URL you own or are
+# authorized to test. Findings appear under Security > Code scanning.
+#
+# Pin the Penthera version (and, ideally, the actions below to commit SHAs) so a
+# scheduled run never picks up code you have not reviewed.
+
+name: Penthera security scan
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  penthera:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Scan staging URL
+        env:
+          PENTEST_URL: ${{ secrets.PENTEST_STAGING_URL }}
+        run: |
+          mkdir -p reports
+          set +e
+          npx --yes penthera@1.2.0 "$PENTEST_URL" \
+            --profile standard \
+            -o reports/scan.json \
+            --sarif reports/scan.sarif
+          code=$?
+          set -e
+          # Exit 1 = critical or high findings (reported via SARIF); only 2 (scan error) fails the job.
+          if [ "$code" -eq 2 ]; then exit 2; fi
+
+      - uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: reports/scan.sarif
+
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: penthera-reports
+          path: reports/

package/docs/index.md

@@ -1,6 +1,6 @@
 # Penthera documentation
 
-Lightweight security scanner for developers, scan live URLs, local repos, or macOS machines from the CLI.
+Security scanner for developers: scan live URLs, local repos, or macOS machines from your AI agent or the CLI.
 
 ## Getting started
 
@@ -33,8 +33,9 @@ Lightweight security scanner for developers, scan live URLs, local repos, or mac
 | Topic | Link |
 |-------|------|
 | OWASP WSTG mapping | [owasp-wstg-coverage.md](./owasp-wstg-coverage.md) |
-| GitHub Actions CI | `.github/workflows/ci.yml` (mock scan + SARIF) |
-| Staging scans | `.github/workflows/scan.yml`, set `PENTEST_STAGING_URL` secret |
+| NIS2 compliance guide | [compliance-nis2.md](./compliance-nis2.md) |
+| Scan your app in GitHub Actions | [examples/github-actions-scan.yml](./examples/github-actions-scan.yml), set `PENTEST_STAGING_URL` |
+| Penthera's own CI | `.github/workflows/ci.yml` (full tests + mock scan), `codeql.yml`, `scorecard.yml` |
 | Docker | `docker build -t penthera . && docker run penthera https://localhost:3000` |
 
 ## Agent skill

package/lib/compliance/readiness.js

@@ -53,7 +53,11 @@ function combine(scanS, attestS) {
   const known = [];
   if (scanS === "met" || scanS === "partial") known.push(scanS);
   if (["met", "partial", "gap"].includes(attestS)) known.push(attestS);
-  if (known.length === 0) return attestS === "na" ? "n/a" : "gap";
+  // Nothing measured and nothing attested is not a failure, it is an unknown.
+  // Reporting it as a gap told an entity that had simply not filled in the
+  // self-assessment that it had failed ten measures, which is both wrong and
+  // the opposite of proportionate.
+  if (known.length === 0) return attestS === "na" ? "n/a" : "not-assessed";
   if (known.includes("gap")) return "gap";
   if (known.includes("partial")) return "partial";
   return "met";
@@ -113,7 +117,7 @@ export function buildReadiness(scanResult, opts = {}) {
     };
   });
 
-  const summary = { met: 0, partial: 0, gap: 0, "n/a": 0 };
+  const summary = { met: 0, partial: 0, gap: 0, "not-assessed": 0, "n/a": 0 };
   for (const m of measures) summary[m.status] = (summary[m.status] || 0) + 1;
   const assessed = measures.filter((m) => m.basis.attestation !== "none" || m.basis.scan !== "none").length;
 
@@ -132,7 +136,13 @@ export function buildReadiness(scanResult, opts = {}) {
   };
 }
 
-const STATUS_LABEL = { met: "Met", partial: "Partial", gap: "Gap", "n/a": "N/A" };
+const STATUS_LABEL = {
+  met: "Met",
+  partial: "Partial",
+  gap: "Gap",
+  "not-assessed": "Not assessed",
+  "n/a": "N/A",
+};
 
 /** Render a readiness report as Markdown. */
 export function formatReadinessMarkdown(readiness) {
@@ -147,7 +157,9 @@ export function formatReadinessMarkdown(readiness) {
   L.push("");
 
   const s = readiness.summary;
-  L.push(`**Summary:** ${s.met} met · ${s.partial} partial · ${s.gap} gap · ${s["n/a"]} n/a, across ${readiness.totalMeasures} Article 21 measures.`);
+  L.push(`**Summary:** ${s.met} met · ${s.partial} partial · ${s.gap} gap · ${s["not-assessed"]} not assessed · ${s["n/a"]} n/a, across ${readiness.totalMeasures} Article 21 measures.`);
+  L.push("");
+  L.push("*Not assessed* means neither the scan nor your self-assessment covered that measure yet. It is an unknown, not a failure. Run the self-assessment to turn those into real answers.");
   L.push("");
   L.push("Status combines what Penthera measured (technical) with your self-assessment (organisational). *Proportionality applies: for a small entity, a short policy or process that genuinely exists counts.*");
   L.push("");

package/lib/injections.js

@@ -38,6 +38,50 @@ async function safeFetch(url, opts = {}) {
   }
 }
 
+// ── Timing-based detection helpers ───────────────────────────────────────
+
+const TIMING_DELAY_MS = 2500; // payload asks the backend to sleep ~3s
+const TIMING_FLOOR_MS = 3000;
+
+function median(nums) {
+  if (!nums.length) return 0;
+  const s = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : Math.round((s[mid - 1] + s[mid]) / 2);
+}
+
+/**
+ * Confirm a suspected time-based injection.
+ *
+ * A single slow response proves nothing: a GC pause, a cold serverless start,
+ * or ordinary network jitter all look identical to an injected sleep. So a
+ * candidate is re-sent a few times and only reported when the MEDIAN delay
+ * holds, which jitter does not survive.
+ *
+ * @param {function(): Promise<{elapsed:number}>} send - re-issues the request
+ * @param {number} baselineMs
+ * @param {number} samples
+ * @returns {Promise<{confirmed: boolean, medianMs: number, samples: number[]}>}
+ */
+export async function confirmTimingDelay(send, baselineMs, samples = 3) {
+  const timings = [];
+  for (let i = 0; i < samples; i++) {
+    const res = await send();
+    if (!res || !res.ok) return { confirmed: false, medianMs: 0, samples: timings };
+    timings.push(res.elapsed);
+    // Bail early if a repeat comes back fast; a real sleep is consistent.
+    if (res.elapsed < baselineMs + TIMING_DELAY_MS) {
+      return { confirmed: false, medianMs: median(timings), samples: timings };
+    }
+  }
+  const m = median(timings);
+  return {
+    confirmed: m > baselineMs + TIMING_DELAY_MS && m > TIMING_FLOOR_MS,
+    medianMs: m,
+    samples: timings,
+  };
+}
+
 // ── SQL Injection Detection ──────────────────────────────────────────────
 
 const SQLI_ERROR_PATTERNS = [
@@ -128,33 +172,41 @@ export async function probeSqli(baseUrl, path, opts = {}) {
   ];
 
   for (const { payload, db } of timingPayloads) {
-    let res;
-    if (method === "GET") {
-      const sep = path.includes("?") ? "&" : "?";
-      res = await safeFetch(`${baseUrl}${path}${sep}id=${encodeURIComponent(payload)}`, {
-        method,
-        timeout: 8_000,
-      });
-    } else {
-      res = await safeFetch(`${baseUrl}${path}`, {
+    const send = () => {
+      if (method === "GET") {
+        const sep = path.includes("?") ? "&" : "?";
+        return safeFetch(`${baseUrl}${path}${sep}id=${encodeURIComponent(payload)}`, {
+          method,
+          timeout: 8_000,
+        });
+      }
+      return safeFetch(`${baseUrl}${path}`, {
         method,
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ id: payload }),
         timeout: 8_000,
       });
-    }
+    };
 
-    // If response took significantly longer than baseline, possible blind SQLi
-    if (res.elapsed > baseline.elapsed + 2500 && res.elapsed > 3000) {
-      findings.push({
-        severity: "high",
-        title: `Possible blind SQL injection (time-based, ${db})`,
-        description: `Payload: ${payload}, response took ${res.elapsed}ms vs baseline ${baseline.elapsed}ms`,
-        url: `${baseUrl}${path}`,
-        status: res.status,
-        category: "sqli",
-        source: "injection-probe",
-      });
+    const res = await send();
+    if (!res.ok) continue;
+
+    // A slow first response is only a candidate. Re-sample before reporting, so
+    // jitter and cold starts don't get published as a high-severity finding.
+    if (res.elapsed > baseline.elapsed + TIMING_DELAY_MS && res.elapsed > TIMING_FLOOR_MS) {
+      const check = await confirmTimingDelay(send, baseline.elapsed);
+      if (check.confirmed) {
+        findings.push({
+          severity: "high",
+          confidence: "likely", // inferred from timing, not proven output
+          title: `Possible blind SQL injection (time-based, ${db})`,
+          description: `Payload: ${payload}. Delay held across ${check.samples.length} repeats (median ${check.medianMs}ms vs baseline ${baseline.elapsed}ms).`,
+          url: `${baseUrl}${path}`,
+          status: res.status,
+          category: "sqli",
+          source: "injection-probe",
+        });
+      }
     }
   }
 
@@ -380,12 +432,13 @@ export async function probeCmdi(baseUrl, path, opts = {}) {
   });
 
   for (const { payload, timing, pattern } of CMDI_PAYLOADS) {
-    const res = await safeFetch(`${baseUrl}${path}`, {
+    const send = () => safeFetch(`${baseUrl}${path}`, {
       method,
       headers: { "Content-Type": "application/json" },
       body: method === "POST" ? JSON.stringify({ input: payload, cmd: payload, command: payload }) : undefined,
       timeout: timing ? 8_000 : INJECT_TIMEOUT,
     });
+    const res = await send();
 
     if (!res.ok) continue;
 
@@ -402,17 +455,22 @@ export async function probeCmdi(baseUrl, path, opts = {}) {
       return findings;
     }
 
-    if (timing && res.elapsed > baseline.elapsed + 2500 && res.elapsed > 3000) {
-      findings.push({
-        severity: "high",
-        title: "Possible OS command injection (time-based)",
-        description: `Payload "${payload}", ${res.elapsed}ms vs baseline ${baseline.elapsed}ms`,
-        url: `${baseUrl}${path}`,
-        status: res.status,
-        category: "cmdi",
-        source: "injection-probe",
-      });
-      return findings;
+    // Same rule as blind SQLi: one slow response is a candidate, not a finding.
+    if (timing && res.elapsed > baseline.elapsed + TIMING_DELAY_MS && res.elapsed > TIMING_FLOOR_MS) {
+      const check = await confirmTimingDelay(send, baseline.elapsed);
+      if (check.confirmed) {
+        findings.push({
+          severity: "high",
+          confidence: "likely", // inferred from timing, not proven output
+          title: "Possible OS command injection (time-based)",
+          description: `Payload "${payload}". Delay held across ${check.samples.length} repeats (median ${check.medianMs}ms vs baseline ${baseline.elapsed}ms).`,
+          url: `${baseUrl}${path}`,
+          status: res.status,
+          category: "cmdi",
+          source: "injection-probe",
+        });
+        return findings;
+      }
     }
   }
 
@@ -421,7 +479,17 @@ export async function probeCmdi(baseUrl, path, opts = {}) {
 
 // ── Context-Aware XSS (Dalfox-style) ────────────────────────────────────
 
-const CANARY = "pnth3r4xss";
+/**
+ * Per-probe reflection canary.
+ *
+ * A fixed string is trivially WAF-fingerprintable and can collide with content
+ * left behind by an earlier scan, so each run gets a fresh one. It stays
+ * alphanumeric and lowercase so no context (attribute, JS string, URL) mangles
+ * or encodes it on the way through.
+ */
+export function makeCanary() {
+  return "pnth" + Math.random().toString(36).slice(2, 10) + "xss";
+}
 
 /**
  * Reflected content is only executable as XSS when the browser renders the
@@ -445,6 +513,7 @@ export function isHtmlResponse(res) {
  */
 export async function probeXss(baseUrl, path, opts = {}) {
   const findings = [];
+  const CANARY = makeCanary();
   const inputParams = ["q", "search", "query", "name", "input", "text", "value", "msg", "error", "redirect", "url", "id"];
 
   for (const param of inputParams) {

package/lib/machine.js

@@ -35,6 +35,27 @@ function run(cmd, opts = {}) {
   }
 }
 
+/**
+ * Verify a binary's code signature. Returns true only when codesign exits 0.
+ *
+ * Uses execFileSync so the path is an argv entry: these paths are read from
+ * plists that any local process can write, and interpolating one into a shell
+ * string would hand a malicious persistence entry command execution inside the
+ * scanner. Anything other than a clean exit counts as unsigned.
+ */
+function verifySignature(program) {
+  try {
+    execFileSync("codesign", ["-v", "--", program], {
+      encoding: "utf-8",
+      timeout: 15_000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function runFile(file, args = [], opts = {}) {
   try {
     return execFileSync(file, args, {
@@ -140,12 +161,22 @@ function checkFileVault() {
 function checkXProtect() {
   const version = run("xprotect version 2>&1");
   const status = run("xprotect status 2>&1");
-  const upToDate = !status.includes("updates available");
+  // XProtect ships enabled on modern macOS, so its presence isn't interesting.
+  // Pending signature updates are: they mean known malware may go undetected.
+  const updatesPending = /updates available/i.test(status);
   return {
     name: "XProtect (Apple Malware Detection)",
     status: version || "unknown",
     detail: status,
-    finding: null, // XProtect is always on in modern macOS
+    finding: updatesPending
+      ? {
+          severity: "low",
+          title: "XProtect signature updates pending",
+          description: "macOS reports XProtect updates are available. Until they install, recently known malware may not be detected.",
+          category: "machine",
+          source: "machine-audit",
+        }
+      : null,
   };
 }
 
@@ -192,11 +223,14 @@ function checkPersistence() {
 
       const isKnown = KNOWN_PREFIXES.some((p) => label.toLowerCase().startsWith(p));
 
-      // Check code signature of the binary
+      // Check code signature of the binary.
+      // `program` comes from an attacker-writable plist, so it is passed as an
+      // argv entry, never interpolated into a shell string. Verification uses
+      // codesign's exit status rather than string-matching its output, so an
+      // unexpected message can't be read as "signed" (fail closed, not open).
       let signed = null;
       if (program !== "unknown" && existsSync(program)) {
-        const sigOut = run(`codesign -v "${program}" 2>&1`);
-        signed = sigOut === "" || sigOut.includes("valid on disk"); // empty = valid
+        signed = verifySignature(program);
       }
 
       items.push({

package/lib/nuclei-loader.js

@@ -2,12 +2,19 @@
  * Nuclei Community Template Loader
  *
  * Parses and executes community-authored Nuclei YAML templates.
- * Supports the most common Nuclei template features:
+ *
+ * This is a useful subset of Nuclei, not a reimplementation of it. Supported:
  *   - 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
+ *   - Matchers: status, word, regex, negative-word, negative-regex
+ *   - Extractors: regex, json
+ *   - Placeholders: {{BaseURL}}, {{Hostname}}, {{RootURL}}
+ *
+ * Not supported, and reported rather than silently ignored (see
+ * collectUnsupported): dsl matchers, kval extractors, dynamic helpers such as
+ * {{rand_int}}, payload/attack modes, workflows, and multi-request chaining.
+ * Only the first path or raw entry of a request block is executed. A template
+ * relying on any of these will not match, so the loader says so instead of
+ * letting it look like a clean result.
  *
  * Requires the `yaml` npm package (zero-dependency YAML parser).
  *
@@ -121,6 +128,9 @@ function parseTemplateFile(filePath, parse) {
       },
       variables: doc.variables || {},
       http: http.map(normalizeHttpBlock),
+      // Features this loader can't execute. Non-empty means the template will
+      // not match even if the target is vulnerable.
+      unsupported: collectUnsupported(doc),
       _source: filePath,
     };
   } catch {
@@ -128,6 +138,47 @@ function parseTemplateFile(filePath, parse) {
   }
 }
 
+/**
+ * Report the Nuclei features a template needs that this loader does not
+ * implement. A template using any of them silently fails to match, which reads
+ * like "no vulnerability found", so callers surface this instead.
+ *
+ * @returns {string[]} human-readable reasons, empty when fully supported
+ */
+export function collectUnsupported(template) {
+  const reasons = new Set();
+  const blocks = template?.http || template?.requests || [];
+
+  if (Array.isArray(blocks) && blocks.length > 1) {
+    reasons.add("multi-request chaining (only the first request runs)");
+  }
+
+  for (const block of Array.isArray(blocks) ? blocks : []) {
+    if (Array.isArray(block?.path) && block.path.length > 1) {
+      reasons.add("multiple paths (only the first is requested)");
+    }
+    if (Array.isArray(block?.raw) && block.raw.length > 1) {
+      reasons.add("multiple raw requests (only the first is sent)");
+    }
+    if (block?.payloads || block?.attack) reasons.add("payload/attack modes");
+    for (const m of block?.matchers || []) {
+      if (m?.type === "dsl") reasons.add("dsl matchers");
+      if (m?.part && !["body", "header", "all", "response"].includes(m.part)) {
+        reasons.add(`matcher part "${m.part}"`);
+      }
+    }
+    for (const e of block?.extractors || []) {
+      if (e?.type === "kval") reasons.add("kval extractors");
+    }
+  }
+
+  const asText = JSON.stringify(blocks || "");
+  if (/\{\{\s*rand_/.test(asText)) reasons.add("dynamic helpers ({{rand_*}})");
+  if (template?.workflows) reasons.add("workflows");
+
+  return [...reasons];
+}
+
 /**
  * Normalize an HTTP request block to our internal format.
  */