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

package/dist/discoveries/script-discovery.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { TargetDiscovery } from '../discovery.js';
+/**
+ * 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 declare function buildScriptEnv(parent?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+interface ScriptTargetInput {
+    file: string;
+    startLine?: number;
+    endLine?: number;
+    message?: string;
+    snippet?: string;
+}
+/**
+ * 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 declare function isInsideRoot(rootAbs: string, candidateAbs: string, pathApi?: {
+    relative: (a: string, b: string) => string;
+    isAbsolute: (p: string) => boolean;
+}): boolean;
+/**
+ * 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 declare function parseScriptOutput(raw: string, format: 'lines' | 'json-array' | 'json-object'): ScriptTargetInput[];
+interface RunScriptResult {
+    stdout: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+}
+/**
+ * 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 declare function runScript(opts: {
+    command: string;
+    args: string[];
+    cwd: string;
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunScriptResult>;
+export declare const scriptDiscovery: TargetDiscovery;
+export {};
+//# sourceMappingURL=script-discovery.d.ts.map

package/dist/discoveries/script-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-discovery.d.ts","sourceRoot":"","sources":["../../src/discoveries/script-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAsC,MAAM,iBAAiB,CAAC;AAoB3F;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,UAAU,CA8DzF;AAED,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAAC,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;CAC/D,GACzB,OAAO,CAGT;AA4GD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,aAAa,GAC7C,iBAAiB,EAAE,CAsIrB;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsF3B;AAgCD,eAAO,MAAM,eAAe,EAAE,eAyM7B,CAAC"}