feat: add config-driven run scoping and report filtering (#326)

* feat(steerability): add config-driven profile with code_path avoid enforcement * fix(steerability): write SDK deny rules once per workflow to avoid parallel-agent race * fix(steerability): reference guidance by pointer in report DROP rules * fix(steerability): tighten code_path avoid enforcement * chore(steerability): use shared ALL_VULN_CLASSES const and tighten RunScope type * fix(steerability): validate run scope before resume short-circuit * fix(steerability): emit only documented Read/Edit deny rules for code_path * fix(steerability): assemble report from analysis deliverables when exploit is disabled * feat(steerability): preflight check that code_path rules match at least one repo entry * fix(steerability): tag missing code_path entries with avoid/focus kind * revert(steerability): assemble report from analysis deliverables when exploit is disabled * feat(steerability): render per-class findings from queue JSON when exploit is disabled * refactor(steerability): trim findings renderer to common mappable rows * feat(steerability): allow report agent to rewrite category-label finding titles * docs(steerability): document new config fields in README and CLAUDE.md * docs(steerability): comment out optional config sections in examples
2026-09-25 11:11:09 +02:00 · 2026-05-01 23:56:15 +05:30
parent 6c8135d031
commit 95998d1a44
32 changed files with 1162 additions and 181 deletions
@@ -0,0 +1,251 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Deterministic queue-JSON to findings-MD renderer.
+ *
+ * Used when exploit=false: the exploit agents didn't run, so there is no
+ * `*_exploitation_evidence.md` to concatenate into the report. This module
+ * reads each `*_exploitation_queue.json` (already SDK-validated against the
+ * schemas in ../ai/queue-schemas.ts) and writes a `*_findings.md` per class
+ * in the canonical body shape that report-executive.txt's cleanup expects.
+ *
+ * No LLM in the loop — every field maps directly from a JSON key.
+ */
+
+import { fs, path } from 'zx';
+import type {
+  AuthFinding,
+  AuthzFinding,
+  InjectionFinding,
+  SsrfFinding,
+  XssFinding,
+} from '../ai/queue-schemas.js';
+import { deliverablesDir } from '../paths.js';
+import type { ActivityLogger } from '../types/activity-logger.js';
+import type { VulnClass } from '../types/config.js';
+
+const DISCLAIMER = [
+  '> Exploitation phase was not run for this assessment. Each entry documents a',
+  '> vulnerability identified through static analysis; live exploitation steps and',
+  '> proof of impact are not included.',
+].join('\n');
+
+interface ClassConfig<T> {
+  readonly heading: string;
+  readonly noneFoundLabel: string;
+  readonly queueFile: string;
+  readonly findingsFile: string;
+  readonly renderEntry: (entry: T) => string;
+}
+
+interface QueueDocument<T> {
+  vulnerabilities?: T[];
+}
+
+// === Common Render Helpers ===
+
+function summaryRow(label: string, value: string | undefined | null | boolean): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'string' && value.trim() === '') return null;
+  return `- **${label}:** ${value}`;
+}
+
+function formatLocation(endpoint: string | undefined, codeLocation: string | undefined): string {
+  if (endpoint && codeLocation) return `${endpoint} (${codeLocation})`;
+  return endpoint ?? codeLocation ?? '';
+}
+
+function buildEntry(
+  id: string,
+  title: string,
+  summaryRows: ReadonlyArray<string | null>,
+  notes: string | undefined,
+): string {
+  const lines: string[] = [];
+  lines.push(`### ${id}: ${title}`);
+  lines.push('');
+  lines.push('**Summary:**');
+  for (const row of summaryRows) {
+    if (row !== null) lines.push(row);
+  }
+  lines.push('');
+  if (notes && notes.trim() !== '') {
+    lines.push(`**Notes:** ${notes.trim()}`);
+  }
+  return lines.join('\n').trimEnd();
+}
+
+// === Per-Class Renderers ===
+
+function renderAuthEntry(e: AuthFinding): string {
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', formatLocation(e.source_endpoint, e.vulnerable_code_location)),
+      summaryRow('Overview', e.missing_defense),
+      summaryRow('Impact', e.exploitation_hypothesis),
+    ],
+    e.notes,
+  );
+}
+
+function renderSsrfEntry(e: SsrfFinding): string {
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', formatLocation(e.source_endpoint, e.vulnerable_code_location)),
+      summaryRow('Overview', e.missing_defense),
+      summaryRow('Impact', e.exploitation_hypothesis),
+    ],
+    e.notes,
+  );
+}
+
+function renderAuthzEntry(e: AuthzFinding): string {
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', formatLocation(e.endpoint, e.vulnerable_code_location)),
+      summaryRow('Overview', e.guard_evidence),
+      summaryRow('Impact', e.side_effect),
+    ],
+    e.notes,
+  );
+}
+
+function renderInjectionEntry(e: InjectionFinding): string {
+  const location = e.path && e.sink_call ? `${e.sink_call} (path: ${e.path})` : (e.sink_call ?? e.path);
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', location),
+      summaryRow('Overview', e.mismatch_reason),
+    ],
+    e.notes,
+  );
+}
+
+function renderXssEntry(e: XssFinding): string {
+  const location = e.path && e.sink_function ? `${e.sink_function} (path: ${e.path})` : (e.sink_function ?? e.path);
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', location),
+      summaryRow('Overview', e.mismatch_reason),
+    ],
+    e.notes,
+  );
+}
+
+// === Class Registry ===
+
+const CLASSES: Record<VulnClass, ClassConfig<unknown>> = {
+  auth: {
+    heading: 'Authentication',
+    noneFoundLabel: 'authentication',
+    queueFile: 'auth_exploitation_queue.json',
+    findingsFile: 'auth_findings.md',
+    renderEntry: (e) => renderAuthEntry(e as AuthFinding),
+  },
+  authz: {
+    heading: 'Authorization',
+    noneFoundLabel: 'authorization',
+    queueFile: 'authz_exploitation_queue.json',
+    findingsFile: 'authz_findings.md',
+    renderEntry: (e) => renderAuthzEntry(e as AuthzFinding),
+  },
+  injection: {
+    heading: 'Injection',
+    noneFoundLabel: 'injection',
+    queueFile: 'injection_exploitation_queue.json',
+    findingsFile: 'injection_findings.md',
+    renderEntry: (e) => renderInjectionEntry(e as InjectionFinding),
+  },
+  xss: {
+    heading: 'XSS',
+    noneFoundLabel: 'XSS',
+    queueFile: 'xss_exploitation_queue.json',
+    findingsFile: 'xss_findings.md',
+    renderEntry: (e) => renderXssEntry(e as XssFinding),
+  },
+  ssrf: {
+    heading: 'SSRF',
+    noneFoundLabel: 'SSRF',
+    queueFile: 'ssrf_exploitation_queue.json',
+    findingsFile: 'ssrf_findings.md',
+    renderEntry: (e) => renderSsrfEntry(e as SsrfFinding),
+  },
+};
+
+// === Class File Assembly ===
+
+function renderClassFile(config: ClassConfig<unknown>, entries: readonly unknown[]): string {
+  const sections: string[] = [];
+  sections.push(`# ${config.heading} Findings`);
+  sections.push('');
+  sections.push(DISCLAIMER);
+  sections.push('');
+  sections.push('## Identified Vulnerabilities');
+  sections.push('');
+  if (entries.length === 0) {
+    sections.push(`No ${config.noneFoundLabel} vulnerabilities were identified.`);
+    sections.push('');
+  } else {
+    for (const entry of entries) {
+      sections.push(config.renderEntry(entry));
+      sections.push('');
+    }
+  }
+  return `${sections.join('\n').trimEnd()}\n`;
+}
+
+// === Public Entry Point ===
+
+/**
+ * Render `*_findings.md` per class from each `*_exploitation_queue.json`.
+ *
+ * Idempotent: skips classes whose findings file already exists, or whose queue
+ * is missing (class out of scope this run). Per-class failures are logged and
+ * other classes still proceed.
+ */
+export async function renderFindingsFromQueues(
+  sourceDir: string,
+  deliverablesSubdir: string | undefined,
+  logger: ActivityLogger,
+): Promise<void> {
+  const dir = deliverablesDir(sourceDir, deliverablesSubdir);
+
+  for (const config of Object.values(CLASSES)) {
+    const queuePath = path.join(dir, config.queueFile);
+    const findingsPath = path.join(dir, config.findingsFile);
+
+    if (await fs.pathExists(findingsPath)) {
+      logger.info(`${config.heading}: ${config.findingsFile} already exists, skipping`);
+      continue;
+    }
+    if (!(await fs.pathExists(queuePath))) {
+      logger.info(`${config.heading}: no queue file (class out of scope), skipping`);
+      continue;
+    }
+
+    try {
+      const doc = (await fs.readJson(queuePath)) as QueueDocument<unknown>;
+      const entries = doc.vulnerabilities ?? [];
+      const markdown = renderClassFile(config, entries);
+      await fs.writeFile(findingsPath, markdown);
+      logger.info(`${config.heading}: rendered ${entries.length} finding(s) to ${config.findingsFile}`);
+    } catch (error) {
+      const err = error as Error;
+      logger.warn(`${config.heading}: failed to render findings from ${config.queueFile}: ${err.message}`);
+    }
+  }
+}
@@ -14,8 +14,9 @@
 * Checks run sequentially, cheapest first:
 * 1. Repository path exists and contains .git
 * 2. Config file parses and validates (if provided)
- * 3. Credentials validate via Claude Agent SDK query (API key, OAuth, Bedrock, or Vertex AI)
- * 4. Target URL is reachable from the container (DNS + HTTP)
+ * 3. code_path rules match real entries in the repo (filesystem only)
+ * 4. Credentials validate via Claude Agent SDK query (API key, OAuth, Bedrock, or Vertex AI)
+ * 5. Target URL is reachable from the container (DNS + HTTP)
 */

 import { lookup } from 'node:dns/promises';
@@ -24,9 +25,11 @@ import http from 'node:http';
 import https from 'node:https';
 import type { SDKAssistantMessageError } from '@anthropic-ai/claude-agent-sdk';
 import { query } from '@anthropic-ai/claude-agent-sdk';
+import { glob } from 'zx';
 import { resolveModel } from '../ai/models.js';
 import { parseConfig } from '../config-parser.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
+import type { Config, Rule } from '../types/config.js';
 import { ErrorCode } from '../types/errors.js';
 import { err, ok, type Result } from '../types/result.js';
 import { isRetryableError, PentestError } from './error-handling.js';
@@ -104,13 +107,13 @@ async function validateRepo(repoPath: string, logger: ActivityLogger, skipGitChe

 // === Config Validation ===

-async function validateConfig(configPath: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
+async function validateConfig(configPath: string, logger: ActivityLogger): Promise<Result<Config, PentestError>> {
  logger.info('Validating configuration file...', { configPath });

  try {
-    await parseConfig(configPath);
+    const config = await parseConfig(configPath);
    logger.info('Configuration file OK');
-    return ok(undefined);
+    return ok(config);
  } catch (error) {
    if (error instanceof PentestError) {
      return err(error);
@@ -128,6 +131,73 @@ async function validateConfig(configPath: string, logger: ActivityLogger): Promi
  }
 }

+// === code_path Existence Validation ===
+
+const CODE_PATH_IGNORE = ['.git/**', '.shannon/**'];
+
+async function patternMatchesAny(repoPath: string, pattern: string): Promise<boolean> {
+  const stream = glob.globbyStream(pattern, {
+    cwd: repoPath,
+    dot: true,
+    onlyFiles: false,
+    followSymbolicLinks: false,
+    ignore: CODE_PATH_IGNORE,
+  });
+  for await (const _ of stream) {
+    return true;
+  }
+  return false;
+}
+
+type RuleKind = 'avoid' | 'focus';
+interface MissingCodePath {
+  kind: RuleKind;
+  value: string;
+  description: string;
+}
+
+async function validateCodePathsExist(
+  config: Config,
+  repoPath: string,
+  logger: ActivityLogger,
+): Promise<Result<void, PentestError>> {
+  const tagged: Array<{ kind: RuleKind; rule: Rule }> = [
+    ...(config.rules?.avoid ?? []).map((rule) => ({ kind: 'avoid' as const, rule })),
+    ...(config.rules?.focus ?? []).map((rule) => ({ kind: 'focus' as const, rule })),
+  ].filter(({ rule }) => rule.type === 'code_path');
+
+  if (tagged.length === 0) {
+    return ok(undefined);
+  }
+
+  logger.info(`Validating ${tagged.length} code_path rule(s) against repo...`);
+
+  // ≥1 match is the only property enforced — malformed globs simply match nothing.
+  const missing: MissingCodePath[] = [];
+  for (const { kind, rule } of tagged) {
+    if (!(await patternMatchesAny(repoPath, rule.value))) {
+      missing.push({ kind, value: rule.value, description: rule.description });
+    }
+  }
+
+  if (missing.length > 0) {
+    const lines = missing.map((m) => `[${m.kind}] '${m.value}' — ${m.description}`);
+    return err(
+      new PentestError(
+        `code_path rules don't match any file or directory in the repo:\n  - ${lines.join('\n  - ')}\n` +
+          `Fix the patterns or remove the rules.`,
+        'config',
+        false,
+        { missing },
+        ErrorCode.CONFIG_VALIDATION_FAILED,
+      ),
+    );
+  }
+
+  logger.info('All code_path rules matched');
+  return ok(undefined);
+}
+
 // === Credential Validation ===

 /** Map SDK error type to a human-readable preflight PentestError. */
@@ -463,8 +533,9 @@ async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Pro
 *
 * 1. Repository path exists and contains .git
 * 2. Config file parses and validates (if configPath provided)
- * 3. Credentials validate (API key, OAuth, Bedrock, or Vertex AI)
- * 4. Target URL is reachable from the container
+ * 3. code_path rules match at least one entry in the repo (skipped without config)
+ * 4. Credentials validate (API key, OAuth, Bedrock, or Vertex AI)
+ * 5. Target URL is reachable from the container
 *
 * Returns on first failure.
 */
@@ -484,20 +555,31 @@ export async function runPreflightChecks(
  }

  // 2. Config check (free — filesystem + CPU)
+  let parsedConfig: Config | null = null;
  if (configPath) {
    const configResult = await validateConfig(configPath, logger);
    if (!configResult.ok) {
      return configResult;
    }
+    parsedConfig = configResult.value;
  }

-  // 3. Credential check (cheap — 1 SDK round-trip, skipped when providerConfig present)
+  // 3. code_path rules must match real entries in the repo (filesystem only).
+  // Runs after both repo and config are valid, before any network round-trip.
+  if (parsedConfig) {
+    const codePathResult = await validateCodePathsExist(parsedConfig, repoPath, logger);
+    if (!codePathResult.ok) {
+      return codePathResult;
+    }
+  }
+
+  // 4. Credential check (cheap — 1 SDK round-trip, skipped when providerConfig present)
  const credResult = await validateCredentials(logger, apiKey, providerConfig);
  if (!credResult.ok) {
    return credResult;
  }

-  // 4. Target URL reachability check (cheap — 1 HTTP round-trip)
+  // 5. Target URL reachability check (cheap — 1 HTTP round-trip)
  const urlResult = await validateTargetUrl(targetUrl, logger);
  if (!urlResult.ok) {
    return urlResult;
@@ -8,9 +8,113 @@ import { fs, path } from 'zx';
 import { PROMPTS_DIR } from '../paths.js';
 import { PLAYWRIGHT_SESSION_MAPPING } from '../session-manager.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
-import type { Authentication, DistributedConfig } from '../types/config.js';
+import type { Authentication, DistributedConfig, ReportConfig, Rule, VulnClass } from '../types/config.js';
+import { isGlobPattern } from '../utils/glob.js';
 import { handlePromptError, PentestError } from './error-handling.js';

+function renderCodePathRules(rules: Rule[]): string {
+  const filtered = rules.filter((r) => r.type === 'code_path');
+  if (filtered.length === 0) return 'None';
+  return filtered
+    .map((r) => {
+      const kind = isGlobPattern(r.value) ? '[GLOB]' : '[FILE]';
+      return `- ${r.value} ${kind} — ${r.description}`;
+    })
+    .join('\n');
+}
+
+interface VulnSummarySpec {
+  readonly heading: string;
+  readonly evidenceSection: string;
+  readonly noneFoundLabel: string;
+}
+
+const VULN_SUMMARY_SPECS: Record<VulnClass, VulnSummarySpec> = {
+  auth: {
+    heading: 'Authentication Vulnerabilities',
+    evidenceSection: 'Authentication Exploitation Evidence',
+    noneFoundLabel: 'authentication',
+  },
+  authz: {
+    heading: 'Authorization Vulnerabilities',
+    evidenceSection: 'Authorization Exploitation Evidence',
+    noneFoundLabel: 'authorization',
+  },
+  xss: {
+    heading: 'Cross-Site Scripting (XSS) Vulnerabilities',
+    evidenceSection: 'XSS Exploitation Evidence',
+    noneFoundLabel: 'XSS',
+  },
+  injection: {
+    heading: 'SQL/Command Injection Vulnerabilities',
+    evidenceSection: 'Injection Exploitation Evidence',
+    noneFoundLabel: 'SQL or command injection',
+  },
+  ssrf: {
+    heading: 'Server-Side Request Forgery (SSRF) Vulnerabilities',
+    evidenceSection: 'SSRF Exploitation Evidence',
+    noneFoundLabel: 'SSRF',
+  },
+};
+
+function renderVulnSummarySubsections(selected: readonly VulnClass[]): string {
+  const classes = selected.length > 0 ? selected : (Object.keys(VULN_SUMMARY_SPECS) as VulnClass[]);
+  return classes
+    .map((cls) => {
+      const spec = VULN_SUMMARY_SPECS[cls];
+      return `**${spec.heading}:**\n{Check for "${spec.evidenceSection}" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No ${spec.noneFoundLabel} vulnerabilities were found."}`;
+    })
+    .join('\n\n');
+}
+
+/**
+ * Renders the top-level <report_filters> block. Empty when no filters are set —
+ * each filter is included only when the operator configured it, so the agent
+ * never sees `none` placeholders or instructions for filters that don't apply.
+ */
+function renderReportFiltersBlock(report: ReportConfig | undefined): string {
+  if (!report) return '';
+  const guidance = report.guidance?.trim();
+  if (!report.min_severity && !report.min_confidence && !guidance) return '';
+
+  const lines: string[] = [
+    '<report_filters>',
+    'The filters below are user-supplied and binding for this assessment. Honor each strictly when assembling the final report.',
+    '',
+  ];
+  if (report.min_severity) {
+    lines.push(
+      `- Minimum severity: ${report.min_severity} — keep only findings rated this severity or higher (scale: low < medium < high < critical).`,
+    );
+  }
+  if (report.min_confidence) {
+    lines.push(
+      `- Minimum confidence: ${report.min_confidence} — keep only findings rated this confidence or higher (scale: low < medium < high).`,
+    );
+  }
+  if (guidance) {
+    lines.push('');
+    lines.push('User guidance — apply throughout the report as binding directives for finding selection:');
+    lines.push(guidance);
+  }
+  lines.push('</report_filters>');
+  return lines.join('\n');
+}
+
+/**
+ * Renders the per-finding DROP rules used inside the cleanup step. Severity and
+ * confidence inline as concrete thresholds; guidance is referenced by pointer
+ * so the actual text only lives in <report_filters>, avoiding double-statement.
+ */
+function renderReportFilterRules(report: ReportConfig | undefined): string {
+  const drops: string[] = [];
+  if (report?.min_severity) drops.push(`* severity is below ${report.min_severity}`);
+  if (report?.min_confidence) drops.push(`* confidence is below ${report.min_confidence}`);
+  if (report?.guidance?.trim()) drops.push('* topic matches an exclusion in the user guidance');
+  if (drops.length === 0) return '';
+  return ['   - DROP any `### [TYPE]-VULN-[NUMBER]` finding whose:', ...drops.map((d) => `     ${d}`)].join('\n');
+}
+
 interface PromptVariables {
  webUrl: string;
  repoPath: string;
@@ -175,36 +279,63 @@ async function interpolateVariables(
      .replace(/{{AUTH_CONTEXT}}/g, buildAuthContext(config))
      .replace(/{{DESCRIPTION}}/g, config?.description ? `Description: ${config.description}` : '');

-    if (config) {
-      // Handle rules section - if both are empty, use cleaner messaging
-      const hasAvoidRules = config.avoid && config.avoid.length > 0;
-      const hasFocusRules = config.focus && config.focus.length > 0;
+    const avoidUrlRules = config?.avoid?.filter((r) => r.type !== 'code_path') ?? [];
+    const focusUrlRules = config?.focus?.filter((r) => r.type !== 'code_path') ?? [];
+    if (avoidUrlRules.length === 0 && focusUrlRules.length === 0) {
+      result = result.replace(/<rules>[\s\S]*?<\/rules>\s*/g, '');
+    } else {
+      const avoidStr = avoidUrlRules.length > 0 ? avoidUrlRules.map((r) => `- ${r.description}`).join('\n') : 'None';
+      const focusStr = focusUrlRules.length > 0 ? focusUrlRules.map((r) => `- ${r.description}`).join('\n') : 'None';
+      result = result.replace(/{{RULES_AVOID}}/g, avoidStr).replace(/{{RULES_FOCUS}}/g, focusStr);
+    }

-      if (!hasAvoidRules && !hasFocusRules) {
-        // Replace the entire rules section with a clean message
-        const cleanRulesSection = '<rules>\nNo specific rules or focus areas provided for this test.\n</rules>';
-        result = result.replace(/<rules>[\s\S]*?<\/rules>/g, cleanRulesSection);
-      } else {
-        const avoidRules = hasAvoidRules ? config.avoid?.map((r) => `- ${r.description}`).join('\n') : 'None';
-        const focusRules = hasFocusRules ? config.focus?.map((r) => `- ${r.description}`).join('\n') : 'None';
+    const avoidCodeRules = (config?.avoid ?? []).filter((r) => r.type === 'code_path');
+    const focusCodeRules = (config?.focus ?? []).filter((r) => r.type === 'code_path');
+    if (avoidCodeRules.length === 0 && focusCodeRules.length === 0) {
+      result = result.replace(/<code_path_rules>[\s\S]*?<\/code_path_rules>\s*/g, '');
+    } else {
+      result = result
+        .replace(/{{CODE_RULES_AVOID}}/g, renderCodePathRules(config?.avoid ?? []))
+        .replace(/{{CODE_RULES_FOCUS}}/g, renderCodePathRules(config?.focus ?? []));
+    }

-        result = result.replace(/{{RULES_AVOID}}/g, avoidRules).replace(/{{RULES_FOCUS}}/g, focusRules);
-      }
+    const roe = config?.rules_of_engagement?.trim() ?? '';
+    if (roe) {
+      result = result.replace(/{{RULES_OF_ENGAGEMENT}}/g, roe);
+    } else {
+      result = result.replace(/<rules_of_engagement>[\s\S]*?<\/rules_of_engagement>\s*/g, '');
+    }

-      // Extract and inject login instructions from config
-      if (config.authentication?.login_flow) {
-        const loginInstructions = await buildLoginInstructions(config.authentication, logger, promptsBaseDir);
-        result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, loginInstructions);
-      } else {
-        result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, '');
-      }
+    if (config?.authentication?.login_flow) {
+      const loginInstructions = await buildLoginInstructions(config.authentication, logger, promptsBaseDir);
+      result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, loginInstructions);
    } else {
-      // Replace the entire rules section with a clean message when no config provided
-      const cleanRulesSection = '<rules>\nNo specific rules or focus areas provided for this test.\n</rules>';
-      result = result.replace(/<rules>[\s\S]*?<\/rules>/g, cleanRulesSection);
      result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, '');
    }

+    const vulnClasses = config?.vuln_classes ?? [];
+    result = result.replace(
+      /{{VULN_CLASSES_TESTED}}/g,
+      vulnClasses.length > 0 ? vulnClasses.join(', ') : 'injection, xss, auth, authz, ssrf',
+    );
+    result = result.replace(/{{VULN_SUMMARY_SUBSECTIONS}}/g, renderVulnSummarySubsections(vulnClasses));
+
+    const exploitEnabled = config?.exploit ?? true;
+    result = result
+      .replace(/{{EXPLOITATION}}/g, exploitEnabled ? 'enabled' : 'disabled')
+      .replace(/{{REPORT_VULN_HEADING}}/g, exploitEnabled ? 'Exploitation Evidence' : 'Findings')
+      .replace(
+        /{{REPORT_VULN_SUBHEADING}}/g,
+        exploitEnabled ? 'Successfully Exploited Vulnerabilities' : 'Identified Vulnerabilities',
+      );
+
+    result = result
+      .replace(/{{REPORT_FILTERS_BLOCK}}/g, renderReportFiltersBlock(config?.report))
+      .replace(/{{REPORT_FILTER_RULES}}/g, renderReportFilterRules(config?.report));
+
+    // Collapse runs of 3+ newlines (left behind by tag-strip and empty-fragment substitutions).
+    result = result.replace(/\n{3,}/g, '\n\n');
+
    // Validate that all placeholders have been replaced (excluding instructional text)
    const remainingPlaceholders = result.match(/\{\{[^}]+\}\}/g);
    if (remainingPlaceholders) {
@@ -12,60 +12,66 @@ import { PentestError } from './error-handling.js';

 interface DeliverableFile {
  name: string;
-  path: string;
+  /** Candidate filenames in priority order. First one that exists wins. */
+  paths: readonly string[];
  required: boolean;
 }

-// Pure function: Assemble final report from specialist deliverables
+// Pure function: Assemble final report from specialist deliverables.
+// Per class, prefer the exploit-agent's evidence file; fall back to renderer-produced findings.
+// Both never coexist for a workspace because scope (exploit flag) is locked.
 export async function assembleFinalReport(
  sourceDir: string,
  deliverablesSubdir: string | undefined,
  logger: ActivityLogger,
 ): Promise<string> {
-  const deliverableFiles: DeliverableFile[] = [
-    { name: 'Injection', path: 'injection_exploitation_evidence.md', required: false },
-    { name: 'XSS', path: 'xss_exploitation_evidence.md', required: false },
-    { name: 'Authentication', path: 'auth_exploitation_evidence.md', required: false },
-    { name: 'SSRF', path: 'ssrf_exploitation_evidence.md', required: false },
-    { name: 'Authorization', path: 'authz_exploitation_evidence.md', required: false },
+  const deliverableFiles: readonly DeliverableFile[] = [
+    { name: 'Injection', paths: ['injection_exploitation_evidence.md', 'injection_findings.md'], required: false },
+    { name: 'XSS', paths: ['xss_exploitation_evidence.md', 'xss_findings.md'], required: false },
+    { name: 'Authentication', paths: ['auth_exploitation_evidence.md', 'auth_findings.md'], required: false },
+    { name: 'SSRF', paths: ['ssrf_exploitation_evidence.md', 'ssrf_findings.md'], required: false },
+    { name: 'Authorization', paths: ['authz_exploitation_evidence.md', 'authz_findings.md'], required: false },
  ];

+  const dir = deliverablesDir(sourceDir, deliverablesSubdir);
  const sections: string[] = [];

  for (const file of deliverableFiles) {
-    const filePath = path.join(deliverablesDir(sourceDir, deliverablesSubdir), file.path);
-    try {
-      if (await fs.pathExists(filePath)) {
-        const content = await fs.readFile(filePath, 'utf8');
-        sections.push(content);
-        logger.info(`Added ${file.name} findings`);
-      } else if (file.required) {
+    let added = false;
+    for (const candidate of file.paths) {
+      const filePath = path.join(dir, candidate);
+      try {
+        if (await fs.pathExists(filePath)) {
+          const content = await fs.readFile(filePath, 'utf8');
+          sections.push(content);
+          logger.info(`Added ${file.name} section from ${candidate}`);
+          added = true;
+          break;
+        }
+      } catch (error) {
+        const err = error as Error;
+        logger.warn(`Could not read ${candidate}: ${err.message}`);
+      }
+    }
+    if (!added) {
+      if (file.required) {
        throw new PentestError(
-          `Required deliverable file not found: ${file.path}`,
+          `Required deliverable file not found: ${file.paths.join(' or ')}`,
          'filesystem',
          false,
-          { deliverableFile: file.path, sourceDir },
+          { deliverableFile: file.paths, sourceDir },
          ErrorCode.DELIVERABLE_NOT_FOUND,
        );
-      } else {
-        logger.info(`No ${file.name} deliverable found`);
      }
-    } catch (error) {
-      if (file.required) {
-        throw error;
-      }
-      const err = error as Error;
-      logger.warn(`Could not read ${file.path}: ${err.message}`);
+      logger.info(`No ${file.name} deliverable found`);
    }
  }

  const finalContent = sections.join('\n\n');
-  const outputDir = deliverablesDir(sourceDir, deliverablesSubdir);
-  const finalReportPath = path.join(outputDir, 'comprehensive_security_assessment_report.md');
+  const finalReportPath = path.join(dir, 'comprehensive_security_assessment_report.md');

  try {
-    // Ensure deliverables directory exists
-    await fs.ensureDir(outputDir);
+    await fs.ensureDir(dir);
    await fs.writeFile(finalReportPath, finalContent);
    logger.info(`Final report assembled at ${finalReportPath}`);
  } catch (error) {