dravix-agent 0.1.0

package/dist/engines/pragma.js

@@ -0,0 +1,83 @@
+/**
+ * Suppression helpers shared across deterministic sink engines.
+ *
+ * In-line pragma: any line that ends with one of the recognised comment
+ * forms causes the sink engines to skip findings on that line:
+ *
+ *   # aegis-allow          (Python / shell / Ruby)
+ *   // aegis-allow         (JS / TS / Go / Rust / Java)
+ *   block-comment with the marker  (JS / TS / Java) — slash-star then slash
+ *
+ * An optional rule id can be added: "# aegis-allow:eval-tainted" only
+ * skips that one rule on the line. Without an id, ALL rules skip.
+ *
+ * Path auto-skip: files that BY DEFINITION contain the very patterns we
+ * scan for — test fixtures, the engine source itself, the Vul-RAG KB —
+ * return true from `isTestOrFixturePath`. The orchestrator's
+ * deterministic sink engines bail early on those paths; the LLM critic
+ * still runs (so a real bug planted in a test file is still caught,
+ * but the literal pattern matches don't fire).
+ */
+import { basename } from "node:path";
+const PRAGMA_RE = /(?:#|\/\/|\/\*)\s*aegis-allow(?::([\w.-]+))?/;
+/** Returns true if the given source LINE has an aegis-allow comment.
+ * When a rule id is named in the pragma, the suppression only applies
+ * if it matches `ruleId`. */
+export function isLineSuppressed(line, ruleId) {
+    const m = PRAGMA_RE.exec(line);
+    if (!m)
+        return false;
+    const targeted = m[1];
+    if (!targeted)
+        return true;
+    return targeted === ruleId || targeted === "*";
+}
+/** Path-based auto-skip for deterministic sink rules. Test files and
+ * the sink-engine source files themselves are NOT scanned by the
+ * regex-based engines (they would self-detect). The LLM critic still
+ * scans them, so a genuine bug planted in such a file IS still caught.
+ *
+ * Recognised path shapes:
+ *   - any path containing /tests/, /test/, /__tests__/, /fixtures/
+ *   - filename ending in .test.<ext> or .spec.<ext>
+ *   - test_<name>.py or <name>_test.{py,go,rb}
+ *   - conftest.py
+ *   - any *-sinks.{ts,js,py} / secret-scan.{ts,js,py} (engine source)
+ *   - vulnkb.json / vulnkb.jsonl (KB data)
+ *   - *fixture* in the basename
+ */
+export function isTestOrFixturePath(filePath) {
+    const p = filePath.replace(/\\/g, "/").toLowerCase();
+    const base = basename(p);
+    if (p.includes("/tests/") ||
+        p.includes("/test/") ||
+        p.includes("/__tests__/") ||
+        p.includes("/fixtures/") ||
+        p.includes("/__fixtures__/")) {
+        return true;
+    }
+    // Engine source files at aegis-v2/src/engines/** + helper scripts —
+    // ours by definition. The LLM critic still scans them.
+    if (p.includes("/src/engines/") ||
+        p.includes("/dist/engines/") ||
+        p.includes("/scripts/"))
+        return true;
+    if (/\.test\.[a-z0-9]+$/.test(base))
+        return true;
+    if (/\.spec\.[a-z0-9]+$/.test(base))
+        return true;
+    // Alphanumeric-before-_test so __test.py / __t.py fixture paths used
+    // by unit tests calling the engine directly don't auto-skip.
+    if (/^test_[a-z0-9].*\.py$/.test(base) || /[a-z0-9]_test\.(?:py|go|rb)$/.test(base))
+        return true;
+    if (base === "conftest.py")
+        return true;
+    if (/[-_](?:sinks|scan|signature|rules)\.(?:ts|js|py)$/.test(base))
+        return true;
+    if (base === "vulnkb.json" || base === "vulnkb.jsonl")
+        return true;
+    if (/[-_]fixture/.test(base))
+        return true;
+    return false;
+}
+//# sourceMappingURL=pragma.js.map

package/dist/engines/pragma.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pragma.js","sourceRoot":"","sources":["../../src/engines/pragma.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,MAAM,SAAS,GAAG,8CAA8C,CAAC;AAEjE;;6BAE6B;AAC7B,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAc;IAC3D,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,GAAG,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IACrD,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzB,IACE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QACrB,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACpB,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC;QACzB,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;QACxB,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAC5B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,oEAAoE;IACpE,uDAAuD;IACvD,IACE,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;QAC3B,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAC5B,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;QAEvB,OAAO,IAAI,CAAC;IACd,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,qEAAqE;IACrE,6DAA6D;IAC7D,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,8BAA8B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjG,IAAI,IAAI,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,mDAAmD,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAChF,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IACnE,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/engines/property-test.d.ts

@@ -0,0 +1,3 @@
+import type { Engine } from "./types.js";
+export declare const propertyTestEngine: Engine;
+//# sourceMappingURL=property-test.d.ts.map

package/dist/engines/property-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-test.d.ts","sourceRoot":"","sources":["../../src/engines/property-test.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,YAAY,CAAC;AAkH1E,eAAO,MAAM,kBAAkB,EAAE,MAAiC,CAAC"}

package/dist/engines/property-test.js

@@ -0,0 +1,134 @@
+/**
+ * Property-based testing engine — wraps src/index/property-test.ts as an
+ * Aegis Engine. Stage 2 (runs after stage 1 like the LLM critic): when a
+ * Python file has at least one high-risk candidate AND the orchestrator
+ * decides to invoke this engine, we generate + run Hypothesis properties
+ * and surface counterexamples as proven-bug Findings.
+ *
+ * Routing (lives in this engine for now; the orchestrator just calls run):
+ *   - Languages: Python only (Hypothesis is Python-specific; fast-check
+ *     for JS/TS is a Phase 3 expansion).
+ *   - Skip when no high-risk function name pattern matches AND no
+ *     arithmetic operator appears in the file (`findPropertyCandidates`
+ *     already returns [] in that case → engine returns no findings, cheap).
+ *
+ * Findings carry source="critic" because the LLM authored the test, but
+ * confidence is **0.95** — much higher than a normal critic finding,
+ * because Hypothesis has produced a **concrete failing input**, not a
+ * speculative judgement. The orchestrator's risk gate treats this as
+ * effectively a definitive block.
+ */
+import { existsSync } from "node:fs";
+import { FindingSchema, makeFindingId } from "../findings.js";
+import { runPropertyTests, _findClaudeCli } from "../index/property-test.js";
+import { findWsl } from "../index/pysa.js";
+import { getLogger } from "../util/logger.js";
+const log = getLogger("aegis.engine.property");
+class PropertyTestEngine {
+    name = "property-test";
+    languages = ["python"];
+    availabilityCache = null;
+    static AVAILABILITY_TTL_MS = 60_000;
+    async available() {
+        const now = Date.now();
+        if (this.availabilityCache &&
+            now - this.availabilityCache.checkedAt < PropertyTestEngine.AVAILABILITY_TTL_MS) {
+            return this.availabilityCache.value;
+        }
+        // Need: WSL (Win) OR python on PATH (POSIX) + claude CLI. We probe
+        // both quickly.
+        let wslOk = false;
+        if (process.platform === "win32") {
+            wslOk = findWsl() !== null;
+        }
+        else {
+            // Linux/macOS path — not implemented yet; engine reports
+            // unavailable cleanly.
+            wslOk = false;
+        }
+        const claudeOk = (await _findClaudeCli()) !== null;
+        const ok = wslOk && claudeOk;
+        this.availabilityCache = { value: ok, checkedAt: now };
+        if (!ok) {
+            log.debug("property-test unavailable", { wslOk, claudeOk });
+        }
+        return ok;
+    }
+    async run(input) {
+        const t0 = Date.now();
+        let results;
+        try {
+            results = await runPropertyTests(input.content);
+        }
+        catch (err) {
+            log.warn("property test run failed", { err: String(err) });
+            return {
+                engine: this.name,
+                findings: [],
+                unavailable: false,
+                durationMs: Date.now() - t0,
+                reason: String(err).slice(0, 200),
+            };
+        }
+        const findings = [];
+        for (const r of results) {
+            if (!r.bugFound)
+                continue;
+            const ruleId = "property.counterexample." + r.candidate.name;
+            const finding = {
+                id: makeFindingId({
+                    engine: "llm-critic", // critic-authored test → emit under critic engine slot
+                    file: input.filePath,
+                    line: r.candidate.line,
+                    rule_id: ruleId,
+                }),
+                // We use the existing "llm-critic" engine slot in EngineEnum to
+                // avoid a schema migration. A future schema bump will add
+                // "property-test" as its own slot. The rule_id prefix
+                // ``property.counterexample.`` makes the distinction obvious in
+                // reports.
+                engine: "llm-critic",
+                file: input.filePath,
+                line: r.candidate.line,
+                rule_id: ruleId,
+                severity: "high",
+                // Hypothesis produced a concrete failing input — this is PROVEN
+                // wrong code, not a speculative judgement. We rate confidence
+                // very high.
+                confidence: 0.95,
+                source: "critic",
+                message: "Property-based test found a counterexample for `" +
+                    r.candidate.name +
+                    "`: " +
+                    (r.invariant ?? "invariant violated") +
+                    " — " +
+                    (r.counterexample ?? "").split("\n")[0].slice(0, 200),
+                evidence: {
+                    snippet: "Function `" +
+                        r.candidate.name +
+                        "` (line " +
+                        String(r.candidate.line) +
+                        ")\nInvariant: " +
+                        (r.invariant ?? "(none stated)") +
+                        "\n\nCounterexample (from Hypothesis):\n" +
+                        (r.counterexample ?? "(not captured)").slice(0, 1500),
+                },
+                remediation: "Run the Hypothesis test locally to reproduce: paste the function + the property into a test file and run `pytest --hypothesis-seed=42`. The counterexample above is the smallest shrunken input that violates the invariant.",
+            };
+            const parsed = FindingSchema.safeParse(finding);
+            if (parsed.success)
+                findings.push(parsed.data);
+        }
+        return {
+            engine: this.name,
+            findings,
+            unavailable: false,
+            durationMs: Date.now() - t0,
+        };
+    }
+}
+export const propertyTestEngine = new PropertyTestEngine();
+// Defensive: ensure the existsSync import isn't flagged as unused by tsc
+// (we may use it in a future availability check; keep the symbol live).
+void existsSync;
+//# sourceMappingURL=property-test.js.map

package/dist/engines/property-test.js.map

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

package/dist/engines/pyright.d.ts

@@ -0,0 +1,10 @@
+import { Engine, EngineRunInput, EngineRunResult } from "./types.js";
+import { Lang } from "../lang.js";
+export declare class PyrightEngine implements Engine {
+    readonly name = "pyright";
+    readonly languages: readonly Lang[];
+    private _availability;
+    available(): Promise<boolean>;
+    run(input: EngineRunInput): Promise<EngineRunResult>;
+}
+//# sourceMappingURL=pyright.d.ts.map

package/dist/engines/pyright.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pyright.d.ts","sourceRoot":"","sources":["../../src/engines/pyright.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AA4ClC,qBAAa,aAAc,YAAW,MAAM;IAC1C,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,SAAS,kBAAa;IAE/B,OAAO,CAAC,aAAa,CAAwB;IAEvC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAM7B,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;CA6F3D"}

package/dist/engines/pyright.js

@@ -0,0 +1,143 @@
+/**
+ * Pyright adapter — subprocess to `pyright --outputjson`.
+ *
+ * Python type errors (unresolved imports, wrong arity, type mismatches, undefined
+ * names) catch ~30% of LLM-generated Python bugs without any semantic analysis.
+ */
+import { writeFile, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { makeFindingId } from "../findings.js";
+import { run, which } from "../util/subprocess.js";
+import { getLogger } from "../util/logger.js";
+const log = getLogger("aegis.engine.pyright");
+const SUPPORTED = ["python"];
+function sevMap(s) {
+    switch (s) {
+        case "error":
+            return "high";
+        case "warning":
+            return "medium";
+        default:
+            return "info";
+    }
+}
+function confidenceFor(s) {
+    return s === "error" ? 0.85 : s === "warning" ? 0.7 : 0.4;
+}
+async function findPyright() {
+    const override = process.env.AEGIS_PYRIGHT_BIN;
+    if (override)
+        return override;
+    return (await which("pyright")) ?? (await which("pyright.cmd"));
+}
+export class PyrightEngine {
+    name = "pyright";
+    languages = SUPPORTED;
+    _availability = null;
+    async available() {
+        if (this._availability !== null)
+            return this._availability;
+        this._availability = (await findPyright()) !== null;
+        return this._availability;
+    }
+    async run(input) {
+        const t0 = Date.now();
+        const bin = await findPyright();
+        if (!bin) {
+            return {
+                engine: this.name,
+                findings: [],
+                unavailable: true,
+                durationMs: Date.now() - t0,
+                reason: "pyright_not_installed",
+            };
+        }
+        // Pyright expects a file on disk. Stage it.
+        const scratch = (await mkdir(join(tmpdir(), `aegis-pyright-${process.pid}-${Date.now()}`), { recursive: true }));
+        const scratchPath = join(scratch, basename(input.filePath));
+        try {
+            await writeFile(scratchPath, input.content, "utf8");
+            const r = await run(bin, {
+                args: ["--outputjson", scratchPath],
+                timeoutMs: Math.min(input.timeoutMs, 15_000),
+            });
+            if (r.timedOut) {
+                return {
+                    engine: this.name,
+                    findings: [],
+                    unavailable: true,
+                    durationMs: Date.now() - t0,
+                    reason: "timeout",
+                };
+            }
+            if (!r.stdout.trim()) {
+                return {
+                    engine: this.name,
+                    findings: [],
+                    unavailable: false,
+                    durationMs: Date.now() - t0,
+                };
+            }
+            let data;
+            try {
+                data = JSON.parse(r.stdout);
+            }
+            catch (err) {
+                log.warn("non-JSON output", { err: String(err) });
+                return {
+                    engine: this.name,
+                    findings: [],
+                    unavailable: true,
+                    durationMs: Date.now() - t0,
+                    reason: "non_json_output",
+                };
+            }
+            const findings = [];
+            for (const diag of data.generalDiagnostics ?? []) {
+                const sev = diag.severity ?? "information";
+                if (sev === "information")
+                    continue;
+                const line = (diag.range?.start?.line ?? 0) + 1;
+                const col = (diag.range?.start?.character ?? 0) + 1;
+                const rule = diag.rule ?? "pyright";
+                findings.push({
+                    id: makeFindingId({
+                        engine: this.name,
+                        file: input.filePath,
+                        line,
+                        rule_id: rule,
+                    }),
+                    engine: "pyright",
+                    file: input.filePath,
+                    line,
+                    col,
+                    rule_id: rule,
+                    severity: sevMap(sev),
+                    message: (diag.message ?? "type error").slice(0, 1900),
+                    confidence: confidenceFor(sev),
+                    source: "type",
+                });
+            }
+            return {
+                engine: this.name,
+                findings,
+                unavailable: false,
+                durationMs: Date.now() - t0,
+            };
+        }
+        finally {
+            try {
+                await rm(scratch, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+function basename(p) {
+    const m = p.replace(/\\/g, "/").split("/");
+    return m[m.length - 1] || "file.py";
+}
+//# sourceMappingURL=pyright.js.map

package/dist/engines/pyright.js.map

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

package/dist/engines/pysa.d.ts

@@ -0,0 +1,3 @@
+import type { Engine } from "./types.js";
+export declare const pysaEngine: Engine;
+//# sourceMappingURL=pysa.d.ts.map

package/dist/engines/pysa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pysa.d.ts","sourceRoot":"","sources":["../../src/engines/pysa.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,YAAY,CAAC;AAiF1E,eAAO,MAAM,UAAU,EAAE,MAAyB,CAAC"}

package/dist/engines/pysa.js

@@ -0,0 +1,83 @@
+/**
+ * Pysa engine adapter — reads pre-computed Pysa taint findings from cache.
+ *
+ * The actual ``pyre analyze`` invocation (slow, 30s-10min) lives in
+ * ``src/index/pysa.ts`` and is driven by ``aegis index --pysa``. This
+ * module is the realtime fast path: read the project's ``findings.jsonl``,
+ * filter to the file under review, return ``Finding[]``.
+ *
+ * Like ``JoernEngine``, this is a "batch + cache" engine — never run
+ * pyre per-edit (would blow the latency budget by 100x).
+ */
+import { existsSync } from "node:fs";
+import { pysaFindingsPath, pysaInfoPath, probePyre, readPysaFindings, } from "../index/pysa.js";
+import { getLogger } from "../util/logger.js";
+const log = getLogger("aegis.engine.pysa");
+class PysaEngine {
+    name = "pysa";
+    // Pysa is Python-only. We narrow the language list so the orchestrator
+    // skips this engine instantly for TS/JS/Go files instead of running it
+    // and returning an empty result.
+    languages = ["python"];
+    availabilityCache = null;
+    static AVAILABILITY_TTL_MS = 60_000;
+    async available() {
+        const now = Date.now();
+        if (this.availabilityCache &&
+            now - this.availabilityCache.checkedAt < PysaEngine.AVAILABILITY_TTL_MS) {
+            return this.availabilityCache.value;
+        }
+        const probe = await probePyre();
+        const ok = probe !== null;
+        this.availabilityCache = { value: ok, checkedAt: now };
+        if (!ok)
+            log.debug("pysa unavailable — pyre not reachable (no WSL or not installed)");
+        return ok;
+    }
+    async run(input) {
+        const t0 = Date.now();
+        if (!input.projectRoot) {
+            return {
+                engine: this.name,
+                findings: [],
+                unavailable: false,
+                durationMs: Date.now() - t0,
+                reason: "no_project_root",
+            };
+        }
+        const findingsPath = pysaFindingsPath(input.projectRoot);
+        const infoPath = pysaInfoPath(input.projectRoot);
+        if (!existsSync(findingsPath) || !existsSync(infoPath)) {
+            return {
+                engine: this.name,
+                findings: [],
+                unavailable: false,
+                durationMs: Date.now() - t0,
+                reason: "no_taint_cache — run `aegis index --pysa` to build",
+            };
+        }
+        const all = readPysaFindings(input.projectRoot);
+        const relPath = toRelPosix(input.filePath, input.projectRoot);
+        const baseName = relPath.split("/").pop() ?? relPath;
+        // Same multi-match heuristic as JoernEngine: full rel path, basename,
+        // or any path ending with /basename. Tolerant of path-normalization
+        // drift between Pysa (Linux/WSL) and Aegis (Windows).
+        const fileFindings = all.filter((f) => f.file === relPath || f.file === baseName || f.file.endsWith("/" + baseName));
+        return {
+            engine: this.name,
+            findings: fileFindings,
+            unavailable: false,
+            durationMs: Date.now() - t0,
+        };
+    }
+}
+function toRelPosix(filePath, projectRoot) {
+    const fp = filePath.replace(/\\/g, "/");
+    const root = projectRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (fp.toLowerCase().startsWith(root.toLowerCase() + "/")) {
+        return fp.slice(root.length + 1);
+    }
+    return fp;
+}
+export const pysaEngine = new PysaEngine();
+//# sourceMappingURL=pysa.js.map

package/dist/engines/pysa.js.map

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

package/dist/engines/python-sinks.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Deterministic Python dangerous-sinks scanner — no external binary.
+ *
+ * Catches the textbook patterns every Python security linter flags:
+ *   - ``os.system(<non-literal>)``                          CWE-78
+ *   - ``subprocess.*(<non-literal>, shell=True)``           CWE-78
+ *   - ``subprocess.*(f"...")``                               CWE-78
+ *   - ``eval(<non-literal>)`` / ``exec(<non-literal>)``     CWE-95
+ *   - ``compile(<non-literal>, ...)``                       CWE-95
+ *   - ``pickle.{loads,load}(...)``                          CWE-502
+ *   - ``yaml.load(<arg>)`` without ``Loader=``              CWE-502
+ *   - ``__import__(<non-literal>)``                         CWE-94
+ *   - ``send_file(<tainted>)`` / ``os.path.join + var``     CWE-22
+ *   - ``urlopen(<non-literal>)``                            CWE-918
+ *   - ``hashlib.{md5,sha1}(...)`` / ``hashlib.new("md5"|"sha1")``  CWE-327
+ *
+ * Why this exists: when Semgrep / Pyright / Joern / Pysa are not
+ * installed-or-indexed for a project, stage-1 has nothing that catches
+ * these patterns. The Vul-RAG router fires the critic ONLY above a
+ * similarity threshold which routinely misses textbook command-injection
+ * snippets (verified 2026-05-26 — ``os.system(f"ping {host}")`` returned
+ * top-1 similarity below 0.55). Without a deterministic sink scanner,
+ * the gate silently allows CWE-78 writes.
+ *
+ * Precision strategy: each pattern emits severity HIGH but
+ * **confidence 0.75** — high enough to trigger stage-2 critic routing
+ * via ``stage1_findings``, low enough that the critic's verdict can
+ * still drive the final decision. The critic refines (drops literal-arg
+ * FPs, escalates true taint to critical) — see V2-08 design.
+ *
+ * Lang scope: Python only. The patterns are syntactically Python-specific.
+ */
+import { Engine, EngineRunInput, EngineRunResult } from "./types.js";
+import { Lang } from "../lang.js";
+interface SinkRule {
+    id: string;
+    cwe: string;
+    /** Severity to emit BEFORE critic refinement. */
+    severity: "high" | "critical";
+    /** Short human description for the message. */
+    what: string;
+    /** Regex that captures the call site. Must use the `g` flag.
+     * Group 1 = the FIRST positional arg (text only, may be approximate
+     * for multi-arg calls). Group 2 (optional) = the rest of the args. */
+    pattern: RegExp;
+    /** Decide if the matched call is dangerous given the first arg + full
+     * file content (for context-aware heuristics like "is this Flask?"). */
+    isDangerous: (firstArg: string, allArgs: string, fullContent?: string) => boolean;
+    /** Optional file-level gate — if present and returns false, the rule
+     * is SKIPPED entirely. Cheaper than per-match checks for rules that
+     * only make sense in specific frameworks. */
+    fileGate?: (fullContent: string) => boolean;
+    remediation: string;
+}
+/** A snippet "looks tainted" if it is NOT a pure string literal. We treat
+ * f-strings as tainted because their substituted parts are interpolation —
+ * which is the entire point of an injection bug. */
+declare function looksTainted(arg: string): boolean;
+/** Detect ``shell=True`` anywhere in the call args. */
+declare function hasShellTrue(args: string): boolean;
+/** Detect ``Loader=`` keyword in yaml.load arg list. */
+declare function hasYamlLoader(args: string): boolean;
+/** Approximate first positional argument from a parenthesized call body.
+ * Naive: split on the first top-level comma. Good enough for the patterns
+ * here; we explicitly do NOT attempt to handle nested calls precisely
+ * because the critic refines. */
+declare function firstPositionalArg(body: string): string;
+export declare class PythonSinksEngine implements Engine {
+    readonly name: "python-sinks";
+    readonly languages: ReadonlyArray<Lang>;
+    available(): Promise<boolean>;
+    run(input: EngineRunInput): Promise<EngineRunResult>;
+}
+export declare const _testing: {
+    RULES: readonly SinkRule[];
+    looksTainted: typeof looksTainted;
+    firstPositionalArg: typeof firstPositionalArg;
+    hasShellTrue: typeof hasShellTrue;
+    hasYamlLoader: typeof hasYamlLoader;
+};
+export {};
+//# sourceMappingURL=python-sinks.d.ts.map

package/dist/engines/python-sinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-sinks.d.ts","sourceRoot":"","sources":["../../src/engines/python-sinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGlC,UAAU,QAAQ;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC;IAC9B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb;;0EAEsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB;4EACwE;IACxE,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAClF;;iDAE6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;oDAEoD;AACpD,iBAAS,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAgB1C;AAED,uDAAuD;AACvD,iBAAS,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3C;AAED,wDAAwD;AACxD,iBAAS,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED;;;iCAGiC;AACjC,iBAAS,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBhD;AAoXD,qBAAa,iBAAkB,YAAW,MAAM;IAC9C,QAAQ,CAAC,IAAI,EAAG,cAAc,CAAU;IACxC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,IAAI,CAAC,CAAc;IAE/C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;CA2D3D;AAGD,eAAO,MAAM,QAAQ;;;;;;CAA2E,CAAC"}