@owasp-aghast/aghast 0.8.4 → 0.9.0-rc.1

package/dist/issue-file-writer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Individual issue file writer (Spec E.3.2).
+ *
+ * Generates one file per `SecurityIssue` in `security_issues_<project>/<check-id>/`,
+ * named `issue_<NNN>_<filename>.<ext>`. Three output formats are supported:
+ * `markdown` (default), `json`, and `html`.
+ *
+ * HTML output escapes user-controlled fields (descriptions, code snippets,
+ * file paths, recommendations, data flow steps) to prevent XSS via injected
+ * markup in AI responses or source code snippets.
+ */
+import type { ScanResults } from './types.js';
+export type IndividualIssueFormat = 'markdown' | 'json' | 'html';
+export interface WriteIndividualIssueFilesResult {
+    /** Absolute path of the root output directory (`security_issues_<project>/`). */
+    rootDir: string;
+    /** Absolute paths of every issue file written. */
+    files: string[];
+}
+export declare function writeIndividualIssueFiles(results: ScanResults, outputDir: string, format?: IndividualIssueFormat): Promise<WriteIndividualIssueFilesResult>;
+//# sourceMappingURL=issue-file-writer.d.ts.map

package/dist/issue-file-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-file-writer.d.ts","sourceRoot":"","sources":["../src/issue-file-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,YAAY,CAAC;AAS3E,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AA2LjE,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAqED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,qBAAkC,GACzC,OAAO,CAAC,+BAA+B,CAAC,CAsC1C"}

package/dist/issue-file-writer.js

@@ -0,0 +1,307 @@
+/**
+ * Individual issue file writer (Spec E.3.2).
+ *
+ * Generates one file per `SecurityIssue` in `security_issues_<project>/<check-id>/`,
+ * named `issue_<NNN>_<filename>.<ext>`. Three output formats are supported:
+ * `markdown` (default), `json`, and `html`.
+ *
+ * HTML output escapes user-controlled fields (descriptions, code snippets,
+ * file paths, recommendations, data flow steps) to prevent XSS via injected
+ * markup in AI responses or source code snippets.
+ */
+import { mkdir, writeFile, readdir, unlink } from 'node:fs/promises';
+import { basename, resolve, sep } from 'node:path';
+// Reuse the shared escaper from the HTML report formatter rather than keeping a
+// second copy — it also handles null/undefined, which a local `string`-only
+// version did not.
+import { escapeHtml } from './formatters/html-formatter.js';
+import { logDebug } from './logging.js';
+const TAG = 'issue-files';
+const FORMAT_EXTENSIONS = {
+    markdown: 'md',
+    json: 'json',
+    html: 'html',
+};
+/**
+ * Windows reserved device names (case-insensitive, base name with or without
+ * extension). Files with these names cannot be created on Windows even from
+ * cross-platform code, so we prefix them with an underscore to make them safe.
+ */
+const WINDOWS_RESERVED_NAMES = new Set([
+    'CON', 'PRN', 'AUX', 'NUL',
+    'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+    'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+]);
+/**
+ * Replace characters that are unsafe in filenames across Windows / macOS / Linux
+ * with underscores. Strips leading dots so we never produce dotfiles by accident.
+ * Also escapes Windows reserved device names (CON, PRN, NUL, etc.) by prefixing
+ * with an underscore so the writer doesn't fail on Windows.
+ */
+function safeFilename(name) {
+    if (!name)
+        return 'unknown';
+    // Use only the basename — issues may carry full paths like "src/foo/bar.ts"
+    const base = basename(name.replace(/[\\/]+/g, '/'));
+    // Replace anything that's not alphanumeric, dash, dot, underscore.
+    let cleaned = base.replace(/[^A-Za-z0-9._-]+/g, '_');
+    // Avoid leading dots (would create hidden files on POSIX).
+    cleaned = cleaned.replace(/^\.+/, '');
+    // Collapse runs of underscores for readability.
+    cleaned = cleaned.replace(/_+/g, '_');
+    if (cleaned.length === 0)
+        return 'unknown';
+    // Escape Windows reserved device names (CON, PRN, NUL, COM1-9, LPT1-9).
+    // Match either the bare name or "name.ext" (case-insensitive).
+    const stem = cleaned.split('.')[0].toUpperCase();
+    if (WINDOWS_RESERVED_NAMES.has(stem)) {
+        cleaned = `_${cleaned}`;
+    }
+    return cleaned;
+}
+/**
+ * Derive a project name for the output directory. Prefers the basename of
+ * the repository path (when it appears to be a filesystem path), otherwise
+ * falls back to the last path segment of a remote URL.
+ */
+function deriveProjectName(results) {
+    const repoPath = results.repository?.path;
+    if (repoPath) {
+        // Use basename — repoPath may be absolute on Windows or POSIX.
+        const normalised = repoPath.replace(/[\\/]+$/, '');
+        const base = basename(normalised.split(sep).join('/'));
+        if (base)
+            return safeFilename(base);
+    }
+    const remote = results.repository?.remoteUrl;
+    if (remote) {
+        const stripped = remote.replace(/\.git$/i, '').replace(/[\\/]+$/, '');
+        const tail = stripped.split('/').pop();
+        if (tail)
+            return safeFilename(tail);
+    }
+    return 'project';
+}
+/** Pad an integer to 3 digits with leading zeros (e.g. 1 -> "001"). */
+function pad3(n) {
+    return String(n).padStart(3, '0');
+}
+function formatLineRange(issue) {
+    if (issue.startLine === issue.endLine)
+        return String(issue.startLine);
+    return `${issue.startLine}-${issue.endLine}`;
+}
+function renderMarkdown(issue) {
+    const lines = [];
+    lines.push(`# ${issue.checkName} (${issue.checkId})`);
+    lines.push('');
+    lines.push(`- **File**: \`${issue.file}\``);
+    lines.push(`- **Lines**: ${formatLineRange(issue)}`);
+    if (issue.severity)
+        lines.push(`- **Severity**: ${issue.severity}`);
+    if (issue.confidence)
+        lines.push(`- **Confidence**: ${issue.confidence}`);
+    lines.push('');
+    lines.push('## Description');
+    lines.push('');
+    lines.push(issue.description);
+    if (issue.codeSnippet) {
+        lines.push('');
+        lines.push('## Code Snippet');
+        lines.push('');
+        // CommonMark allows variable-length fences: pick a length one longer than
+        // the longest run of backticks in the snippet so embedded fences don't
+        // break out of the code block.
+        const longest = (issue.codeSnippet.match(/`+/g) ?? []).reduce((m, s) => Math.max(m, s.length), 0);
+        const fence = '`'.repeat(Math.max(3, longest + 1));
+        lines.push(fence);
+        lines.push(issue.codeSnippet);
+        lines.push(fence);
+    }
+    if (issue.recommendation) {
+        lines.push('');
+        lines.push('## Recommendation');
+        lines.push('');
+        lines.push(issue.recommendation);
+    }
+    if (issue.dataFlow && issue.dataFlow.length > 0) {
+        lines.push('');
+        lines.push('## Data Flow Trace');
+        lines.push('');
+        issue.dataFlow.forEach((step, idx) => {
+            lines.push(`${idx + 1}. \`${step.file}:${step.lineNumber}\` — ${step.label}`);
+        });
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function renderJson(issue) {
+    // Pretty-printed for human review, includes all SecurityIssue fields.
+    return JSON.stringify(issue, null, 2) + '\n';
+}
+function renderHtml(issue) {
+    const parts = [];
+    parts.push('<!doctype html>');
+    parts.push('<html lang="en">');
+    parts.push('<head>');
+    parts.push('<meta charset="utf-8">');
+    parts.push(`<title>${escapeHtml(issue.checkName)} — ${escapeHtml(issue.file)}</title>`);
+    parts.push('<style>');
+    parts.push('body{font-family:sans-serif;max-width:900px;margin:2em auto;padding:0 1em;}');
+    parts.push('pre{background:#f4f4f4;padding:1em;overflow:auto;}');
+    parts.push('dt{font-weight:bold;}dd{margin:0 0 .5em 1em;}');
+    parts.push('</style>');
+    parts.push('</head>');
+    parts.push('<body>');
+    parts.push(`<h1>${escapeHtml(issue.checkName)} <small>(${escapeHtml(issue.checkId)})</small></h1>`);
+    parts.push('<dl>');
+    parts.push(`<dt>File</dt><dd><code>${escapeHtml(issue.file)}</code></dd>`);
+    parts.push(`<dt>Lines</dt><dd>${escapeHtml(formatLineRange(issue))}</dd>`);
+    if (issue.severity)
+        parts.push(`<dt>Severity</dt><dd>${escapeHtml(issue.severity)}</dd>`);
+    if (issue.confidence)
+        parts.push(`<dt>Confidence</dt><dd>${escapeHtml(issue.confidence)}</dd>`);
+    parts.push('</dl>');
+    parts.push('<h2>Description</h2>');
+    parts.push(`<p>${escapeHtml(issue.description)}</p>`);
+    if (issue.codeSnippet) {
+        parts.push('<h2>Code Snippet</h2>');
+        parts.push(`<pre><code>${escapeHtml(issue.codeSnippet)}</code></pre>`);
+    }
+    if (issue.recommendation) {
+        parts.push('<h2>Recommendation</h2>');
+        parts.push(`<p>${escapeHtml(issue.recommendation)}</p>`);
+    }
+    if (issue.dataFlow && issue.dataFlow.length > 0) {
+        parts.push('<h2>Data Flow Trace</h2>');
+        parts.push('<ol>');
+        for (const step of issue.dataFlow) {
+            parts.push(`<li><code>${escapeHtml(step.file)}:${escapeHtml(String(step.lineNumber))}</code> — ${escapeHtml(step.label)}</li>`);
+        }
+        parts.push('</ol>');
+    }
+    parts.push('</body>');
+    parts.push('</html>');
+    parts.push('');
+    return parts.join('\n');
+}
+function renderIssue(issue, format) {
+    switch (format) {
+        case 'markdown':
+            return renderMarkdown(issue);
+        case 'json':
+            return renderJson(issue);
+        case 'html':
+            return renderHtml(issue);
+        default:
+            // Fail fast: rather than silently writing the literal string "undefined"
+            // to disk, throw if a programmatic caller passes an unknown format.
+            throw new Error(`Unsupported individual issue format: ${String(format)}`);
+    }
+}
+/**
+ * Write one file per issue in `outputDir/security_issues_<project>/<check-id>/`.
+ *
+ * - File names follow `issue_<NNN>_<filename>.<ext>` with NNN zero-padded to 3.
+ * - Numbering is per check (each check directory restarts at 001).
+ * - When two issues would produce the same filename (e.g. multiple issues in
+ *   the same source file), the index disambiguates them — they remain unique
+ *   on disk because NNN is different.
+ *
+ * @param results Scan results containing the issues to externalize.
+ * @param outputDir Parent directory under which `security_issues_<project>/` is created.
+ * @param format Output format (`markdown` | `json` | `html`).
+ * @returns Root directory and the list of files written.
+ */
+/**
+ * Matches only the files this module generates: `issue_<NNN>_<slug>.<ext>` with
+ * one of the three known extensions.
+ *
+ * Deliberately strict. The output directory is a normal directory a user may
+ * keep other things in — notes, a README, a previous run they copied aside — and
+ * a loose glob would delete them. Anything not matching this exact shape is
+ * left alone, and directories are never removed.
+ */
+const GENERATED_ISSUE_FILE = /^issue_\d{3,}_.*\.(?:md|json|html)$/;
+/**
+ * Remove issue files left by a previous run.
+ *
+ * Without this, a run that produces fewer findings than the last one leaves the
+ * surplus behind: the writer numbers from 1 each time, so old `issue_004_*`
+ * files survive and read as current findings. Stale results in a security
+ * report are worse than no results.
+ *
+ * Best-effort by design — a directory that cannot be read is skipped rather
+ * than failing the scan, since the report itself has already been written.
+ */
+async function clearStaleIssueFiles(rootDir) {
+    let removed = 0;
+    let entries;
+    try {
+        entries = await readdir(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return 0; // First run: nothing to clear.
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const checkDir = resolve(rootDir, entry.name);
+        let files;
+        try {
+            files = await readdir(checkDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.isFile() || !GENERATED_ISSUE_FILE.test(file.name))
+                continue;
+            try {
+                await unlink(resolve(checkDir, file.name));
+                removed++;
+            }
+            catch {
+                // Locked or already gone — the write below will overwrite what it can.
+            }
+        }
+    }
+    return removed;
+}
+export async function writeIndividualIssueFiles(results, outputDir, format = 'markdown') {
+    const projectName = deriveProjectName(results);
+    const rootDir = resolve(outputDir, `security_issues_${projectName}`);
+    await mkdir(rootDir, { recursive: true });
+    // Clear before writing, so a run with fewer findings than the last one does
+    // not leave the surplus behind looking current.
+    const removed = await clearStaleIssueFiles(rootDir);
+    if (removed > 0) {
+        logDebug(TAG, `Removed ${removed} issue file(s) from a previous run in ${rootDir}`);
+    }
+    // Group issues by checkId, preserving order (the order issues were collected).
+    const grouped = new Map();
+    for (const issue of results.issues) {
+        const list = grouped.get(issue.checkId);
+        if (list)
+            list.push(issue);
+        else
+            grouped.set(issue.checkId, [issue]);
+    }
+    const ext = FORMAT_EXTENSIONS[format];
+    const files = [];
+    for (const [checkId, issues] of grouped) {
+        const checkDir = resolve(rootDir, safeFilename(checkId));
+        await mkdir(checkDir, { recursive: true });
+        let n = 1;
+        for (const issue of issues) {
+            const fileSlug = safeFilename(issue.file);
+            const fileName = `issue_${pad3(n)}_${fileSlug}.${ext}`;
+            const fullPath = resolve(checkDir, fileName);
+            await writeFile(fullPath, renderIssue(issue, format), 'utf-8');
+            files.push(fullPath);
+            n++;
+        }
+    }
+    return { rootDir, files };
+}
+//# sourceMappingURL=issue-file-writer.js.map

package/dist/issue-file-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-file-writer.js","sourceRoot":"","sources":["../src/issue-file-writer.ts"],"names":[],"mappings":"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"}

package/dist/judge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * LLM judge stage: re-evaluates aggregated SecurityIssues after all checks have run.
+ * Annotates each issue with a verdict (true_positive / false_positive / uncertain),
+ * confidence, and rationale. Runs as a separate pipeline stage in runMultiScanWithCost.
+ */
+import { type AgentProvider, type SecurityIssue, type JudgeVerdict } from './types.js';
+import { type RetryOptions, type CircuitBreaker } from './retry.js';
+import { type ScanCostTracker } from './cost-tracker.js';
+export interface JudgeOptions {
+    provider: AgentProvider;
+    providerName: string;
+    model: string;
+    concurrency?: number;
+    dropFalsePositives?: boolean;
+    minConfidence?: number;
+    /**
+     * Retry settings for the judge's own AI calls. The scan runner passes the
+     * same resolved options it uses for check analysis, so opting into retry
+     * covers judging too. Omitted means the caller did not opt in, and
+     * `DEFAULT_RETRY` (one attempt) applies.
+     */
+    retry?: RetryOptions;
+    /** Circuit breaker shared with the scan, when retry is enabled. */
+    breaker?: CircuitBreaker;
+}
+/** Map from check ID to the check's markdown instructions (used in judge prompt). */
+export type CheckInstructionsMap = Map<string, string>;
+/**
+ * Parse a raw judge response into a JudgeVerdict.
+ * Returns undefined if the response is not parseable or lacks required fields.
+ */
+export declare function parseJudgeResponse(raw: string): Pick<JudgeVerdict, 'verdict' | 'confidence' | 'rationale'> | undefined;
+/**
+ * Run the judge stage over all collected issues.
+ * Mutates each issue in place by attaching a `judge` field.
+ * Returns the issues array (same reference, mutated).
+ */
+export declare function runJudge(issues: SecurityIssue[], checksById: Map<string, {
+    check: {
+        judge?: boolean;
+    };
+    instructions: string | undefined;
+}>, repositoryPath: string, options: JudgeOptions, costTracker: ScanCostTracker): Promise<SecurityIssue[]>;
+/**
+ * Recompute per-check statuses and summary counts after the judge stage.
+ *
+ * Recomputation order (per issue 290 design):
+ * 1. Apply minConfidence demotion (already done in runJudge per-issue)
+ * 2. Drop false positives if dropFalsePositives is set
+ * 3. Escalate checks whose remaining issues are all uncertain → FLAG
+ * 4. Set flagSource on issues
+ * 5. Recompute summary counts
+ *
+ * Returns the filtered issues array and updated check summaries.
+ */
+export declare function applyJudgeResults(allIssues: SecurityIssue[], allCheckSummaries: import('./types.js').CheckExecutionSummary[], options: Pick<JudgeOptions, 'dropFalsePositives'>): {
+    filteredIssues: SecurityIssue[];
+    judgedIssues: number;
+    falsePositives: number;
+    uncertainJudgements: number;
+};
+//# sourceMappingURL=judge.d.ts.map

package/dist/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../src/judge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,aAAa,EAAsB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,EAAmE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAErI,OAAO,EAAE,KAAK,eAAe,EAAgC,MAAM,mBAAmB,CAAC;AAqBvF,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,qFAAqF;AACrF,MAAM,MAAM,oBAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC,GAAG,SAAS,CA+BtH;AA6CD;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,aAAa,EAAE,EACvB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,EACzF,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,eAAe,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC,CAuI1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EAAE,EAC1B,iBAAiB,EAAE,OAAO,YAAY,EAAE,qBAAqB,EAAE,EAC/D,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,oBAAoB,CAAC,GAChD;IACD,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CAmEA"}