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

package/dist/discoveries/script-discovery.js

@@ -0,0 +1,593 @@
+/**
+ * Script-based target discovery.
+ *
+ * Runs a user-provided script (`node` or `bash`) in the target repository
+ * and parses its stdout to produce discovery targets. Useful when target
+ * discovery is too custom for Semgrep / SARIF / OpenAnt — e.g. parsing an
+ * OpenAPI spec, querying a build manifest, walking a database schema, etc.
+ *
+ * ─── Trust model ─────────────────────────────────────────────────────────────
+ *
+ * Scripts run with the full privileges of the aghast process. They are not
+ * sandboxed. Treat any script referenced by a check definition as trusted
+ * code — only enable script-discovery checks whose script you (or your team)
+ * have read and audited.
+ *
+ * Defensive measures applied here:
+ * - Script path must resolve INSIDE the configured check folder or repo
+ *   (no `..` escape, no absolute paths to /etc/shadow, etc.).
+ * - Symlink-aware: both the script path and `cwd` are realpath'd and
+ *   re-checked against the repo root, so a symlink inside the check folder
+ *   pointing outside the repo cannot be used to execute external code.
+ * - Spawned with `shell: false` and array args — no shell interpolation, no
+ *   command injection from check-definition fields.
+ * - Spawned with a curated environment: only a small allow-list of neutral
+ *   env vars (PATH, HOME, locale, temp dirs, Windows essentials) is forwarded.
+ *   As defence-in-depth, any var matching a known-secret pattern (`*_KEY`,
+ *   `*_TOKEN`, `*_SECRET`, `*_PASSWORD`, or `ANTHROPIC_*` / `OPENAI_*` /
+ *   `GITHUB_*` / `AGHAST_*` / `AWS_*` / `GCP_*` / `AZURE_*` prefixes) is
+ *   also explicitly dropped. Allow-list matching is case-insensitive so
+ *   the Windows-style `Path` / `SystemRoot` casing works the same as POSIX
+ *   `PATH`.
+ * - cwd, when supplied, must resolve (and realpath) inside the repo root.
+ * - Hard timeout (default 30s, configurable per check).
+ * - Stdout is bounded (8 MiB) to prevent memory exhaustion from runaway scripts.
+ * - Both the line-format and JSON-format output paths cap the number of
+ *   parsed targets (MAX_LINE_TARGETS / MAX_JSON_TARGETS) to bound memory
+ *   even if a script floods within the stdout cap.
+ * - Output is parsed as data (lines / JSON) — never `eval`-ed.
+ * - File paths returned by the script are validated to be relative & inside
+ *   the repo (no `..` escape, no absolute paths) before they are forwarded
+ *   to the AI prompt or snippet extractor.
+ * - On `bash` scripts, Windows is unsupported (no system bash) and a clear
+ *   error is raised rather than silently falling back.
+ */
+import { spawn } from 'node:child_process';
+import { readFile, realpath } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, normalize } from 'node:path';
+import { logDebug, logProgress, logWarn } from '../logging.js';
+import { ERROR_CODES, formatError } from '../error-codes.js';
+import { DEFAULT_GENERIC_PROMPT } from '../defaults.js';
+const TAG = 'script-discovery';
+/** Default timeout: 30s. Overridable per check via `checkTarget.timeoutMs`. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Cap on total stdout we will buffer (8 MiB). */
+const MAX_STDOUT_BYTES = 8 * 1024 * 1024;
+/** Cap on total stderr we will buffer (1 MiB) — only used for diagnostics. */
+const MAX_STDERR_BYTES = 1 * 1024 * 1024;
+/** Maximum number of lines we will keep when parsing `lines` format. */
+const MAX_LINE_TARGETS = 100_000;
+/** Maximum number of items we will keep when parsing `json-array` / `json-object` format. */
+const MAX_JSON_TARGETS = 100_000;
+/**
+ * Build a curated environment for the spawned discovery script.
+ *
+ * Discovery scripts need to walk the repo, possibly run small helper tools,
+ * but they never need API credentials. We start from a minimal allow-list of
+ * "neutral" env vars (PATH/locale/temp dirs) and then ALSO drop any var whose
+ * name matches a known-secret pattern even if it slipped through. Both layers
+ * are defence-in-depth.
+ *
+ * Exported for testing.
+ */
+export function buildScriptEnv(parent = process.env) {
+    // Allow-list: variables a normal CLI tool needs to function.
+    // Case-insensitive: on Windows `process.env` enumerates keys with their
+    // original casing (e.g. `Path`, `SystemRoot`, `ProgramFiles`), so a strict
+    // case-sensitive `Set.has` would drop those vars and break script
+    // discovery on Windows. We normalize to upper-case for membership checks.
+    const ALLOW_LIST_UPPER = new Set([
+        'PATH',
+        'HOME',
+        'USER',
+        'USERNAME',
+        'LANG',
+        'LC_ALL',
+        'LC_CTYPE',
+        'LC_MESSAGES',
+        'LC_NUMERIC',
+        'LC_TIME',
+        'TZ',
+        'TMPDIR',
+        'TMP',
+        'TEMP',
+        // Windows essentials (uppercased — case-insensitive match below)
+        'SYSTEMROOT',
+        'SYSTEMDRIVE',
+        'COMSPEC',
+        'PATHEXT',
+        'WINDIR',
+        'APPDATA',
+        'LOCALAPPDATA',
+        'PROGRAMDATA',
+        'PROGRAMFILES',
+        'PROGRAMFILES(X86)',
+        'PUBLIC',
+        'USERPROFILE',
+    ].map((s) => s.toUpperCase()));
+    // Block-list patterns: never forward, even if they accidentally appear in
+    // the allow-list. The `i` flag makes them case-insensitive too.
+    const BLOCK_PATTERNS = [
+        /(?:^|_)KEY$/i,
+        /(?:^|_)TOKEN$/i,
+        /(?:^|_)SECRET$/i,
+        /(?:^|_)PASSWORD$/i,
+        /(?:^|_)PASSWD$/i,
+        /^ANTHROPIC_/i,
+        /^OPENAI_/i,
+        /^GITHUB_/i,
+        /^AGHAST_/i, // aghast-internal config should not leak to discovery scripts
+        /^AWS_/i,
+        /^GCP_/i,
+        /^AZURE_/i,
+        /^NPM_TOKEN/i,
+    ];
+    const out = {};
+    for (const [k, v] of Object.entries(parent)) {
+        if (v === undefined)
+            continue;
+        if (!ALLOW_LIST_UPPER.has(k.toUpperCase()))
+            continue;
+        if (BLOCK_PATTERNS.some((re) => re.test(k)))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * True when `candidateAbs` lives inside `rootAbs`. Both must be absolute.
+ *
+ * Two ways to be outside, and both matter:
+ *   - a `..` prefix, the ordinary case;
+ *   - an absolute result, which is what `relative()` returns on Windows when
+ *     the two paths are on different drives (`C:\repo` vs `D:\checks`).
+ *
+ * Exported so the rule can be unit-tested against Windows-style paths on any
+ * platform. It exists as a single function because it previously did not: two
+ * call sites implemented the rule separately, one omitted the absolute-path
+ * case, and cross-drive layouts were rejected as a result.
+ *
+ * Pass a `pathApi` of `path.win32` or `path.posix` to test either flavour.
+ */
+export function isInsideRoot(rootAbs, candidateAbs, pathApi = { relative, isAbsolute }) {
+    const rel = pathApi.relative(rootAbs, candidateAbs);
+    return !rel.startsWith('..') && !pathApi.isAbsolute(rel);
+}
+/**
+ * Verify that `candidateAbs` (an already-resolved absolute path) lives inside
+ * `rootAbs` (also absolute). Throws via `formatError(E2004, ...)` if the
+ * candidate escapes the root. Returns void.
+ *
+ * Used both for the textual `resolve` check and for the post-`realpath`
+ * symlink-aware re-check.
+ */
+function assertInsideRoot(rootAbs, candidateAbs, label) {
+    if (!isInsideRoot(rootAbs, candidateAbs)) {
+        throw new Error(formatError(ERROR_CODES.E2004, `${label} "${candidateAbs}" resolves outside of "${rootAbs}" — refusing to run`));
+    }
+}
+/**
+ * Symlink-aware path validation. Resolves the realpath of `target` and verifies
+ * the realpath is still inside `rootAbs`. If the target does not yet exist
+ * (e.g. cwd that the script will create), falls back to the textual path.
+ */
+async function assertRealpathInsideRoot(rootAbs, target, label) {
+    let realTarget;
+    try {
+        realTarget = await realpath(target);
+    }
+    catch {
+        // Path may not exist yet — textual check (already performed elsewhere) suffices.
+        return;
+    }
+    // realpath of root may itself differ if the repo is reached via a symlink;
+    // resolve both ends to be consistent.
+    let realRoot;
+    try {
+        realRoot = await realpath(rootAbs);
+    }
+    catch {
+        realRoot = rootAbs;
+    }
+    assertInsideRoot(realRoot, realTarget, `${label} (after symlink resolution)`);
+}
+/**
+ * Resolve a path that should live inside `root`. Throws if the resolved
+ * absolute path escapes the root directory (path traversal protection).
+ *
+ * Both `..` segments and absolute-path inputs are handled by re-resolving
+ * against `root` and then verifying that `relative(root, resolved)` does
+ * not start with `..`.
+ *
+ * NOTE: This is a textual check only — it does NOT follow symlinks. Callers
+ * that care about symlink escape (e.g. when about to spawn the file as code)
+ * should additionally call `assertRealpathInsideRoot`.
+ */
+function resolveInside(root, candidate, label) {
+    if (typeof candidate !== 'string' || candidate.length === 0) {
+        throw new Error(formatError(ERROR_CODES.E2004, `${label} must be a non-empty string`));
+    }
+    // Reject absolute paths up-front: scripts in check definitions should be
+    // expressed relative to the check folder / repo, never absolute.
+    if (isAbsolute(candidate)) {
+        throw new Error(formatError(ERROR_CODES.E2004, `${label} must be a relative path, got absolute: "${candidate}"`));
+    }
+    const rootAbs = resolve(root);
+    const resolved = resolve(rootAbs, candidate);
+    assertInsideRoot(rootAbs, resolved, label);
+    return resolved;
+}
+/**
+ * Validate a file path emitted by a script: must be relative, must not
+ * traverse outside the repo via `..`. Returns the normalized path.
+ */
+function validateScriptFilePath(file, idx) {
+    if (typeof file !== 'string' || file.length === 0) {
+        throw new Error(formatError(ERROR_CODES.E7105, `Script target[${idx}].file must be a non-empty string`));
+    }
+    if (isAbsolute(file)) {
+        throw new Error(formatError(ERROR_CODES.E7105, `Script target[${idx}].file must be relative (got absolute: "${file}")`));
+    }
+    // normalize collapses redundant segments; if the result starts with `..`
+    // the path escapes the repo root.
+    const norm = normalize(file).replace(/\\/g, '/');
+    if (norm === '..' || norm.startsWith('../') || norm.startsWith('..\\')) {
+        throw new Error(formatError(ERROR_CODES.E7105, `Script target[${idx}].file "${file}" escapes the repository root via ".."`));
+    }
+    return norm;
+}
+/**
+ * Parse stdout into a list of discovery target inputs.
+ * - `lines`: one file path per non-empty, non-comment line.
+ * - `json-array`: a JSON array of strings (file paths) or objects.
+ * - `json-object`: an object with a `targets` array of strings or objects.
+ *
+ * Both `lines` and JSON formats cap parsed targets at MAX_LINE_TARGETS /
+ * MAX_JSON_TARGETS (100k each); the rest are dropped with a warning log.
+ *
+ * Output is treated as DATA: never eval'd, never interpolated into commands.
+ */
+export function parseScriptOutput(raw, format) {
+    if (format === 'lines') {
+        // NOTE: the `lines` format treats blank lines and lines starting with `#`
+        // as comments and skips them. Documented intentionally — file paths
+        // beginning with `#` are unusual and unsupported.
+        const out = [];
+        let truncated = false;
+        for (const line of raw.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            if (trimmed.startsWith('#'))
+                continue;
+            out.push({ file: trimmed });
+            if (out.length >= MAX_LINE_TARGETS) {
+                truncated = true;
+                break;
+            }
+        }
+        if (truncated) {
+            logWarn(TAG, `Script output truncated at MAX_LINE_TARGETS=${MAX_LINE_TARGETS}; remaining lines ignored`);
+        }
+        return out;
+    }
+    // JSON formats
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(formatError(ERROR_CODES.E7105, `Script output is not valid JSON for outputFormat=${format}: ${err instanceof Error ? err.message : String(err)}`), { cause: err });
+    }
+    let arr;
+    if (format === 'json-array') {
+        if (!Array.isArray(parsed)) {
+            throw new Error(formatError(ERROR_CODES.E7105, `Script outputFormat=json-array expects a JSON array at the root`));
+        }
+        arr = parsed;
+    }
+    else {
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error(formatError(ERROR_CODES.E7105, `Script outputFormat=json-object expects a JSON object with a "targets" array`));
+        }
+        const targets = parsed.targets;
+        if (!Array.isArray(targets)) {
+            throw new Error(formatError(ERROR_CODES.E7105, `Script outputFormat=json-object expects a "targets" array; got ${typeof targets}`));
+        }
+        arr = targets;
+    }
+    const out = [];
+    const items = arr;
+    // Cap JSON-parsed item count to bound memory even if the script flooded
+    // structured output within the stdout cap.
+    const limit = Math.min(items.length, MAX_JSON_TARGETS);
+    if (items.length > MAX_JSON_TARGETS) {
+        logWarn(TAG, `Script JSON output truncated at MAX_JSON_TARGETS=${MAX_JSON_TARGETS} (script returned ${items.length} items)`);
+    }
+    for (let i = 0; i < limit; i++) {
+        const item = items[i];
+        if (typeof item === 'string') {
+            out.push({ file: item });
+            continue;
+        }
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            throw new Error(formatError(ERROR_CODES.E7105, `Script target[${i}] must be a string or object, got ${Array.isArray(item) ? 'array' : typeof item}`));
+        }
+        const obj = item;
+        if (typeof obj.file !== 'string' || obj.file.length === 0) {
+            throw new Error(formatError(ERROR_CODES.E7105, `Script target[${i}].file must be a non-empty string`));
+        }
+        const t = { file: obj.file };
+        if (obj.startLine !== undefined) {
+            if (typeof obj.startLine !== 'number' || !Number.isFinite(obj.startLine) || obj.startLine < 0) {
+                throw new Error(formatError(ERROR_CODES.E7105, `Script target[${i}].startLine must be a non-negative number`));
+            }
+            t.startLine = Math.floor(obj.startLine);
+        }
+        if (obj.endLine !== undefined) {
+            if (typeof obj.endLine !== 'number' || !Number.isFinite(obj.endLine) || obj.endLine < 0) {
+                throw new Error(formatError(ERROR_CODES.E7105, `Script target[${i}].endLine must be a non-negative number`));
+            }
+            t.endLine = Math.floor(obj.endLine);
+        }
+        if (obj.message !== undefined) {
+            if (typeof obj.message !== 'string') {
+                throw new Error(formatError(ERROR_CODES.E7105, `Script target[${i}].message must be a string`));
+            }
+            t.message = obj.message;
+        }
+        if (obj.snippet !== undefined) {
+            if (typeof obj.snippet !== 'string') {
+                throw new Error(formatError(ERROR_CODES.E7105, `Script target[${i}].snippet must be a string`));
+            }
+            t.snippet = obj.snippet;
+        }
+        out.push(t);
+    }
+    return out;
+}
+/**
+ * Execute the script as a child process and capture stdout.
+ * - Uses `spawn` with `shell: false`: never invoke a shell, never interpolate.
+ * - Passes a curated env (no API keys / tokens) — see `buildScriptEnv`.
+ * - Bounds stdout/stderr buffers and kills the process on timeout.
+ */
+export function runScript(opts) {
+    return new Promise((resolvePromise, reject) => {
+        let stdoutLen = 0;
+        let stderrLen = 0;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let timedOut = false;
+        let stdoutTruncated = false;
+        const child = spawn(opts.command, opts.args, {
+            cwd: opts.cwd,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            env: opts.env ?? buildScriptEnv(),
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            // Kill the whole process; on POSIX SIGKILL is unmaskable. On Windows
+            // Node's kill() invokes TerminateProcess regardless of the signal.
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // already exited
+            }
+        }, opts.timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            if (stdoutTruncated)
+                return;
+            if (stdoutLen + chunk.length > MAX_STDOUT_BYTES) {
+                stdoutTruncated = true;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // ignore
+                }
+                return;
+            }
+            stdoutChunks.push(chunk);
+            stdoutLen += chunk.length;
+        });
+        child.stderr.on('data', (chunk) => {
+            if (stderrLen + chunk.length > MAX_STDERR_BYTES)
+                return;
+            stderrChunks.push(chunk);
+            stderrLen += chunk.length;
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                reject(new Error(formatError(ERROR_CODES.E7101, `Script discovery timed out after ${opts.timeoutMs}ms`)));
+                return;
+            }
+            if (stdoutTruncated) {
+                reject(new Error(formatError(ERROR_CODES.E7103, `Script discovery stdout exceeded ${MAX_STDOUT_BYTES} bytes — aborted`)));
+                return;
+            }
+            resolvePromise({
+                stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+                exitCode: code,
+                signal,
+            });
+        });
+    });
+}
+/**
+ * Resolve the runtime command + leading args for a given scriptType.
+ * Returns `[command, ...leadingArgs]`. The script path is appended later.
+ */
+function commandForScriptType(scriptType) {
+    if (scriptType === 'node') {
+        // Use the same Node binary that's running aghast — avoids surprises from
+        // PATH lookups picking up an unexpected node.
+        return [process.execPath, []];
+    }
+    if (scriptType === 'bash') {
+        if (process.platform === 'win32') {
+            throw new Error(formatError(ERROR_CODES.E7106, `scriptType="bash" is not supported on Windows; use scriptType="node" instead`));
+        }
+        // Use bare `bash` so PATH lookup works on systems where bash lives at
+        // /usr/bin/bash, /usr/local/bin/bash, NixOS store paths, etc. spawn() with
+        // shell:false still resolves bare command names through PATH.
+        return ['bash', []];
+    }
+    // Should be unreachable due to upstream validation.
+    throw new Error(formatError(ERROR_CODES.E7106, `Unknown scriptType: "${scriptType}"`));
+}
+export const scriptDiscovery = {
+    name: 'script',
+    defaultGenericPrompt: DEFAULT_GENERIC_PROMPT,
+    needsInstructions: true,
+    // Opted out deliberately, same reasoning as the glob discovery.
+    // `supportsDiffFilter` became a required field on TargetDiscovery after this
+    // discovery was written (#227). A discovery script can emit either whole-file
+    // targets or explicit line ranges, so filter behaviour would vary per script
+    // with nothing to validate it against. Opting out preserves the behaviour
+    // this discovery was built and tested with: the script decides the target
+    // set, and aghast analyses all of it.
+    supportsDiffFilter: false,
+    async discover(check, repoPath, _options) {
+        const checkTarget = check.checkTarget;
+        if (!checkTarget.script) {
+            throw new Error(formatError(ERROR_CODES.E2004, `Check "${check.id}" uses script discovery but has no "script" in its check definition`));
+        }
+        if (!checkTarget.scriptType) {
+            throw new Error(formatError(ERROR_CODES.E2004, `Check "${check.id}" uses script discovery but has no "scriptType" in its check definition`));
+        }
+        if (!checkTarget.outputFormat) {
+            throw new Error(formatError(ERROR_CODES.E2004, `Check "${check.id}" uses script discovery but has no "outputFormat" in its check definition`));
+        }
+        // Script path: resolve relative to check folder if available, else repo root.
+        // Then re-validate that the absolute resolution is inside the repo (so
+        // a check folder symlinked outside the repo can't be used to escape).
+        const checkBase = check.checkDir ?? repoPath;
+        const repoRoot = resolve(repoPath);
+        let scriptAbs;
+        try {
+            scriptAbs = resolveInside(checkBase, checkTarget.script, 'checkTarget.script');
+        }
+        catch (err) {
+            // Re-throw with check id for context
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`[${check.id}] ${msg}`, { cause: err });
+        }
+        // Defence-in-depth: also enforce script lives inside the repo root, so that
+        // even if checkDir points outside the repo we don't run arbitrary scripts.
+        // Skip this check when the check folder itself lives outside the repo
+        // (the common case during local dev where checks-config/ is a sibling of
+        // the target repo) — in that case resolveInside(checkBase, ...) above
+        // already constrained the script to the check folder.
+        const checkBaseAbs = resolve(checkBase);
+        const checkBaseInsideRepo = isInsideRoot(repoRoot, checkBaseAbs);
+        if (checkBaseInsideRepo) {
+            // re-raise propagates the original E2004-formatted message
+            assertInsideRoot(repoRoot, scriptAbs, `[${check.id}] checkTarget.script`);
+        }
+        // Validate script file exists & is readable.
+        try {
+            await readFile(scriptAbs, { flag: 'r' });
+        }
+        catch (err) {
+            throw new Error(formatError(ERROR_CODES.E7104, `[${check.id}] script "${checkTarget.script}" not found or unreadable at "${scriptAbs}": ${err instanceof Error ? err.message : String(err)}`), { cause: err });
+        }
+        // Symlink-aware re-check: if the script (or any parent component) is a
+        // symlink whose realpath escapes the constraining root, refuse to run.
+        // We use the check folder as the constraining root when checkBase is
+        // outside the repo (local-dev case); otherwise we use the repo root.
+        const symlinkConstrainingRoot = checkBaseInsideRepo ? repoRoot : checkBaseAbs;
+        await assertRealpathInsideRoot(symlinkConstrainingRoot, scriptAbs, `[${check.id}] checkTarget.script`);
+        // Resolve cwd: must be inside repo. Defaults to repo root.
+        let scriptCwd = repoRoot;
+        if (checkTarget.cwd !== undefined) {
+            try {
+                scriptCwd = resolveInside(repoRoot, checkTarget.cwd, 'checkTarget.cwd');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`[${check.id}] ${msg}`, { cause: err });
+            }
+            // Symlink-aware cwd check.
+            await assertRealpathInsideRoot(repoRoot, scriptCwd, `[${check.id}] checkTarget.cwd`);
+        }
+        const timeoutMs = typeof checkTarget.timeoutMs === 'number' && checkTarget.timeoutMs > 0
+            ? Math.floor(checkTarget.timeoutMs)
+            : DEFAULT_TIMEOUT_MS;
+        const [command, leadingArgs] = commandForScriptType(checkTarget.scriptType);
+        // No shell interpolation: array args, shell:false in spawn.
+        const args = [...leadingArgs, scriptAbs];
+        logProgress(TAG, `Running script discovery for check ${check.id}: ${checkTarget.scriptType} ${checkTarget.script}`);
+        logDebug(TAG, `cmd=${command} args=${JSON.stringify(args)} cwd=${scriptCwd} timeout=${timeoutMs}ms`);
+        let result;
+        try {
+            result = await runScript({ command, args, cwd: scriptCwd, timeoutMs });
+        }
+        catch (err) {
+            // Already-formatted E7xxx errors from runScript pass through cause.
+            throw new Error(formatError(ERROR_CODES.E7104, `[${check.id}] script discovery failed: ${err instanceof Error ? err.message : String(err)}`), { cause: err });
+        }
+        if (result.exitCode !== 0) {
+            const stderrPreview = result.stderr.length > 500 ? result.stderr.slice(0, 500) + '…' : result.stderr;
+            throw new Error(formatError(ERROR_CODES.E7102, `[${check.id}] script exited with code=${result.exitCode} signal=${result.signal ?? 'none'}; stderr: ${stderrPreview}`));
+        }
+        // Surface non-empty stderr even on success (warnings, deprecations).
+        if (result.stderr.trim().length > 0) {
+            const preview = result.stderr.length > 500 ? result.stderr.slice(0, 500) + '…' : result.stderr;
+            logDebug(TAG, `[${check.id}] script stderr (exit 0): ${preview}`);
+        }
+        if (result.stdout.trim().length === 0) {
+            logDebug(TAG, `[${check.id}] script produced empty output — 0 targets`);
+            return [];
+        }
+        const parsedTargets = parseScriptOutput(result.stdout, checkTarget.outputFormat);
+        // Apply maxTargets in two places: here (early — bounds memory) and again in
+        // scan-runner (canonical limit applied uniformly across discoveries).
+        let limited = parsedTargets;
+        if (typeof checkTarget.maxTargets === 'number' &&
+            checkTarget.maxTargets > 0 &&
+            limited.length > checkTarget.maxTargets) {
+            limited = limited.slice(0, checkTarget.maxTargets);
+        }
+        logDebug(TAG, `[${check.id}] script produced ${parsedTargets.length} targets (using ${limited.length})`);
+        // Convert parsed inputs to DiscoveredTarget objects.
+        return limited.map((t, idx) => {
+            // Reject absolute / `..`-traversing file paths before they reach the
+            // AI prompt or the snippet extractor.
+            const safeFile = validateScriptFilePath(t.file, idx);
+            // Normalize line numbers: DiscoveredTarget is documented as 1-based,
+            // so coerce undefined or 0 → 1.
+            const rawStart = typeof t.startLine === 'number' ? t.startLine : 1;
+            const startLine = rawStart < 1 ? 1 : rawStart;
+            const rawEnd = typeof t.endLine === 'number' ? t.endLine : startLine;
+            const endLine = rawEnd < 1 ? startLine : rawEnd;
+            const enrichment = `\n\nTARGET LOCATION (from script discovery):
+
+- File: ${safeFile}
+- Lines: ${startLine}-${endLine}${t.message ? `\n- Message: ${t.message}` : ''}
+`;
+            const out = {
+                file: safeFile,
+                startLine,
+                endLine,
+                label: `[script-target ${idx + 1}/${limited.length}]`,
+                promptEnrichment: enrichment,
+            };
+            if (t.message !== undefined)
+                out.message = t.message;
+            if (t.snippet !== undefined)
+                out.snippet = t.snippet;
+            return out;
+        });
+    },
+};
+//# sourceMappingURL=script-discovery.js.map

package/dist/discoveries/script-discovery.js.map

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

package/dist/docs-url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonical documentation location, surfaced in CLI --help output so users who
+ * install aghast via npm can discover the docs for configuration, check types
+ * and examples. Single source of truth — do not duplicate these literals.
+ */
+export declare const DOCS_BASE = "https://github.com/owasp-aghast/aghast/tree/main/docs";
+/**
+ * Build a help footer that links to a specific documentation page (e.g.
+ * `scanning.md`), or to the docs index when no page is given. The page names
+ * are asserted to exist on disk by tests/docs-links.test.ts, so a renamed or
+ * removed page fails CI rather than shipping a dead link.
+ */
+export declare function docsFooter(page?: string): string;
+//# sourceMappingURL=docs-url.d.ts.map

package/dist/docs-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-url.d.ts","sourceRoot":"","sources":["../src/docs-url.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,SAAS,0DAA0D,CAAC;AAEjF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhD"}

package/dist/docs-url.js

@@ -0,0 +1,17 @@
+/**
+ * Canonical documentation location, surfaced in CLI --help output so users who
+ * install aghast via npm can discover the docs for configuration, check types
+ * and examples. Single source of truth — do not duplicate these literals.
+ */
+export const DOCS_BASE = 'https://github.com/owasp-aghast/aghast/tree/main/docs';
+/**
+ * Build a help footer that links to a specific documentation page (e.g.
+ * `scanning.md`), or to the docs index when no page is given. The page names
+ * are asserted to exist on disk by tests/docs-links.test.ts, so a renamed or
+ * removed page fails CI rather than shipping a dead link.
+ */
+export function docsFooter(page) {
+    const url = page ? `${DOCS_BASE}/${page}` : DOCS_BASE;
+    return `Documentation:\n  ${url}`;
+}
+//# sourceMappingURL=docs-url.js.map

package/dist/docs-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-url.js","sourceRoot":"","sources":["../src/docs-url.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,uDAAuD,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,OAAO,qBAAqB,GAAG,EAAE,CAAC;AACpC,CAAC"}