codictator 0.0.0 → 0.1.3

package/dist/kernel/shell-deny.js

@@ -0,0 +1,171 @@
+// SPEC §4.7.2: the deny classes over a ShellAnalysis. Destruction outside
+// the repo, remote code, privilege, credential exfiltration and history
+// destruction each yield a violation; the bypass class is owned by §4.14.3
+// and lands with integrity. Per-command checks own shell-deny-cmd.ts;
+// structural rules (pipes, embedded scripts) live here. Matching is
+// conservative by design: a false positive is remediated in the rule with
+// a passing fixture, never waived.
+import { isSecretReadPath } from "./secret-paths.js";
+import { commandName } from "./shell-cmd.js";
+import { dispatchToolCheck, flag, readsSecret } from "./shell-deny-cmd.js";
+import { analyseShell } from "./shell-scan.js";
+const ALWAYS_BLOCK = new Set([
+    "mkfs",
+    "diskpart",
+    "shred",
+    "vssadmin",
+    "bcdedit",
+    "takeown",
+]);
+const SHELL_NAMES = new Set([
+    "sh",
+    "bash",
+    "dash",
+    "zsh",
+    "ksh",
+    "python",
+    "python3",
+    "perl",
+    "ruby",
+    "php",
+    "node",
+    "powershell",
+    "pwsh",
+]);
+const NETWORK_TOOLS = new Set([
+    "curl",
+    "wget",
+    "ssh",
+    "scp",
+    "sftp",
+    "ftp",
+    "nc",
+    "ncat",
+    "telnet",
+    "iwr",
+    "invoke-webrequest",
+]);
+const DOWNLOADS = new Set([
+    "curl",
+    "wget",
+    "iwr",
+    "invoke-webrequest",
+    "aria2c",
+]);
+const URL_PATTERN = /^(?:https?|ftp):\/\//i;
+function hasUrl(command) {
+    return command.argv.some((word) => URL_PATTERN.test(word));
+}
+function embeddedAnalysis(command) {
+    const found = [];
+    for (const script of command.embedded) {
+        const parsed = analyseShell(script);
+        if (parsed.ok) {
+            found.push(parsed.value);
+        }
+    }
+    return found;
+}
+function embeddedHasDownload(command) {
+    for (const analysis of embeddedAnalysis(command)) {
+        for (const pipeline of analysis.pipelines) {
+            for (const inner of pipeline.commands) {
+                const name = commandName(inner);
+                if (DOWNLOADS.has(name) && hasUrl(inner)) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+function checkCommand(command, out) {
+    const name = commandName(command);
+    if (command.elevated) {
+        flag(out, "privilege", command.raw, "privilege escalation with sudo or su");
+    }
+    if (ALWAYS_BLOCK.has(name)) {
+        flag(out, name === "takeown" ? "privilege" : "destruction", command.raw, `destructive tool ${name}`);
+        return;
+    }
+    if (name === "cipher" &&
+        command.argv.some((word) => word.toLowerCase() === "/w")) {
+        flag(out, "destruction", command.raw, "cipher /w destroys free space");
+        return;
+    }
+    dispatchToolCheck(command, out);
+    if (readsSecret(command)) {
+        flag(out, "secret-read", command.raw, "shell command reads secret material");
+    }
+    const shellLike = SHELL_NAMES.has(name) ||
+        name === "eval" ||
+        name === "iex" ||
+        name === "invoke-expression";
+    if (shellLike && embeddedHasDownload(command)) {
+        flag(out, "remote-code", command.raw, "shell executes downloaded content");
+    }
+    if ((name === "iex" || name === "invoke-expression") &&
+        embeddedHasDownload(command)) {
+        flag(out, "remote-code", command.raw, "expression of downloaded content");
+    }
+}
+function checkPipeline(pipeline, found) {
+    for (let index = 0; index < pipeline.commands.length - 1; index += 1) {
+        const current = pipeline.commands[index];
+        const next = pipeline.commands[index + 1];
+        if (current === undefined || next === undefined) {
+            continue;
+        }
+        pipeStep(pipeline, index, current, next, found);
+    }
+}
+function pipeStep(pipeline, index, current, next, found) {
+    const currentName = commandName(current);
+    const nextName = commandName(next);
+    if (DOWNLOADS.has(currentName) &&
+        hasUrl(current) &&
+        SHELL_NAMES.has(nextName)) {
+        flag(found, "remote-code", `${current.raw} | ${next.raw}`, "download piped into a shell");
+    }
+    if (SHELL_NAMES.has(nextName) && !pipedDownload(pipeline, index)) {
+        flag(found, "remote-code", `${current.raw} | ${next.raw}`, "pipe into a shell executes its input");
+    }
+    if (readsSecret(current) && NETWORK_TOOLS.has(nextName)) {
+        flag(found, "exfiltration", `${current.raw} | ${next.raw}`, "secret material piped to a network tool");
+    }
+}
+function pipedDownload(pipeline, index) {
+    return pipeline.commands
+        .slice(0, index + 1)
+        .some((entry) => DOWNLOADS.has(commandName(entry)) && hasUrl(entry));
+}
+// SPEC §4.7.2 deny classes: destruction, remote code, privilege, credential
+// exfiltration and history destruction. A download piped into a shell, a
+// secret read piped to a network tool, and a shell executing downloaded
+// content all block; the analyser stays conservative by design.
+export function matchDangerousShell(analysis) {
+    const found = [];
+    const visit = (current) => {
+        for (const pipeline of current.pipelines) {
+            for (const command of pipeline.commands) {
+                checkCommand(command, found);
+                for (const script of command.embedded) {
+                    const parsed = analyseShell(script);
+                    if (!parsed.ok) {
+                        flag(found, "unparseable", command.raw, "embedded shell is unparseable");
+                        continue;
+                    }
+                    visit(parsed.value);
+                }
+            }
+            checkPipeline(pipeline, found);
+        }
+        for (const input of current.inputs) {
+            if (isSecretReadPath(input)) {
+                flag(found, "secret-read", `< ${input}`, "shell reads secret material");
+            }
+        }
+    };
+    visit(analysis);
+    return found;
+}

package/dist/kernel/shell-scan.d.ts

@@ -0,0 +1,3 @@
+import { type Result } from "./result.ts";
+import { type ShellAnalysis } from "./shell.ts";
+export declare function analyseShell(command: string): Result<ShellAnalysis>;

package/dist/kernel/shell-scan.js

@@ -0,0 +1,226 @@
+// SPEC §4.7.2: the shell parser driver. The main loop dispatches each
+// position to the word scanners (shell-word.ts) or a boundary; finished
+// word lists become commands through the elaborator (shell-cmd.ts).
+// Pipelines split on ;, &&, ||, |, & and newlines; $(…), backticks,
+// groupings and heredocs descend inline.
+import { makeError } from "./errors.js";
+import { err, ok } from "./result.js";
+import { ParseFailure, } from "./shell.js";
+import { buildShellCommand } from "./shell-cmd.js";
+import { readShellBalanced, readShellHeredoc, readShellOperator, readShellQuoted, readShellWord, skipShellComment, } from "./shell-word.js";
+function unparseable() {
+    return err(makeError("CDX-E306", "shell command is unparseable (unbalanced quote or unfinished construct)", "Rewrite the command with balanced quotes and no heredoc without a terminator, then retry."));
+}
+function newCollector() {
+    return { pipelines: [], writeTargets: [], inputs: [] };
+}
+class ShellParser {
+    index = 0;
+    current = [];
+    commandStart = 0;
+    pipeline = [];
+    heredocBodies = [];
+    text;
+    collect;
+    constructor(text, collect) {
+        this.text = text;
+        this.collect = collect;
+    }
+    parse() {
+        this.commandStart = 0;
+        while (this.index < this.text.length) {
+            this.parseStep();
+        }
+        this.endCommand();
+        this.endPipeline();
+    }
+    parseStep() {
+        const char = this.text[this.index];
+        if (char === " " || char === "\t") {
+            this.index += 1;
+            return;
+        }
+        if (char === "#") {
+            this.index = skipShellComment(this.text, this.index);
+            return;
+        }
+        if (char !== undefined && this.parseQuotedStart(char)) {
+            return;
+        }
+        if (char !== undefined && this.parseBoundaryStart(char)) {
+            return;
+        }
+        if (char !== undefined && this.parseGroupStart(char)) {
+            return;
+        }
+        this.parseWordOrOperator();
+    }
+    parseSubstitutionStart(char) {
+        const next = this.text[this.index + 1];
+        if (next !== "(" || (char !== "$" && char !== "<" && char !== ">")) {
+            return false;
+        }
+        const inner = readShellBalanced(this.text, this.index + 2, ")");
+        ShellParser.descendText(inner.value, this.collect);
+        this.current.push(inner.value);
+        this.index = inner.next;
+        return true;
+    }
+    parseQuotedStart(char) {
+        if (char === "'" || char === '"' || char === "`") {
+            const read = readShellQuoted(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            this.current.push(read.value);
+            this.index = read.next;
+            return true;
+        }
+        return this.parseSubstitutionStart(char);
+    }
+    endBoundary(pipelineToo, skip) {
+        this.endCommand();
+        if (pipelineToo) {
+            this.endPipeline();
+        }
+        this.index += skip;
+        this.commandStart = this.index;
+    }
+    parseBoundaryStart(char) {
+        if (char === "\n") {
+            this.endBoundary(true, 1);
+            return true;
+        }
+        if (char === "&" && this.text[this.index + 1] === "&") {
+            this.endBoundary(true, 2);
+            return true;
+        }
+        if (char === "|" && this.text[this.index + 1] === "|") {
+            this.endBoundary(true, 2);
+            return true;
+        }
+        if (char === "|" && this.text[this.index + 1] === "&") {
+            this.endBoundary(false, 2);
+            return true;
+        }
+        if (char === "|") {
+            this.endBoundary(false, 1);
+            return true;
+        }
+        if (char === ";" || char === "&") {
+            const skip = char === ";" && this.text[this.index + 1] === ";" ? 2 : 1;
+            this.endBoundary(true, skip);
+            return true;
+        }
+        return false;
+    }
+    parseGroupStart(char) {
+        if (char === "(" || char === "{") {
+            const close = char === "(" ? ")" : "}";
+            const inner = readShellBalanced(this.text, this.index + 1, close);
+            if (char === "(" && this.current.length === 0) {
+                this.endPipeline();
+            }
+            ShellParser.descendText(inner.value, this.collect);
+            this.index = inner.next;
+            this.commandStart = this.index;
+            return true;
+        }
+        if (char === ")" || char === "}") {
+            throw new ParseFailure();
+        }
+        return false;
+    }
+    parseWordOrOperator() {
+        const last = this.current.length > 0
+            ? this.current[this.current.length - 1]
+            : undefined;
+        const operator = readShellOperator(this.text, this.index, last);
+        if (operator === undefined) {
+            const word = readShellWord(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            this.current.push(word.value);
+            this.index = word.next;
+            return;
+        }
+        if (operator.dropFd) {
+            this.current.pop();
+        }
+        this.index = operator.next;
+        this.handleRedirection(operator.operator);
+    }
+    handleRedirection(operator) {
+        while (this.index < this.text.length &&
+            (this.text[this.index] === " " || this.text[this.index] === "\t")) {
+            this.index += 1;
+        }
+        if (this.index >= this.text.length) {
+            throw new ParseFailure();
+        }
+        const char = this.text[this.index];
+        let target;
+        if (char === "'" || char === '"') {
+            const read = readShellQuoted(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            target = read.value;
+            this.index = read.next;
+        }
+        else {
+            const word = readShellWord(this.text, this.index, (inner) => ShellParser.descendText(inner, this.collect));
+            target = word.value;
+            this.index = word.next;
+        }
+        if (target === "") {
+            throw new ParseFailure();
+        }
+        if (operator === "<<" || operator === "<<-") {
+            const body = readShellHeredoc(this.text, this.index, target, operator === "<<-");
+            this.heredocBodies.push(body.value);
+            this.index = body.next;
+        }
+        else if (operator === "<") {
+            this.collect.inputs.push(target);
+        }
+        else if (operator !== "<<<") {
+            this.collect.writeTargets.push(target);
+        }
+    }
+    endCommand() {
+        const words = this.current;
+        this.current = [];
+        const bodies = this.heredocBodies;
+        this.heredocBodies = [];
+        if (words.length === 0) {
+            return;
+        }
+        const raw = this.text.slice(this.commandStart, this.index).trim();
+        this.commandStart = this.index;
+        buildShellCommand(this.pipeline, words, raw, false, bodies, (inner) => ShellParser.descendText(inner, this.collect));
+    }
+    endPipeline() {
+        if (this.pipeline.length > 0) {
+            this.collect.pipelines.push({ commands: this.pipeline });
+            this.pipeline = [];
+        }
+    }
+    static descendText(inner, collect) {
+        const nested = new ShellParser(inner, collect);
+        nested.parse();
+    }
+}
+// SPEC §4.7.2: tokenise without executing; unbalanced quotes, heredocs
+// without a terminator and other unfinished constructs fail CDX-E306.
+export function analyseShell(command) {
+    const collect = newCollector();
+    try {
+        const parser = new ShellParser(command.replace(/\r\n?/g, "\n"), collect);
+        parser.parse();
+    }
+    catch (error) {
+        if (error instanceof ParseFailure) {
+            return unparseable();
+        }
+        throw error;
+    }
+    const pipelines = collect.pipelines.filter((pipeline) => pipeline.commands.length > 0);
+    return ok({
+        pipelines,
+        writeTargets: [...collect.writeTargets],
+        inputs: [...collect.inputs],
+    });
+}

package/dist/kernel/shell-word.d.ts

@@ -0,0 +1,15 @@
+export interface WordRead {
+    readonly value: string;
+    readonly next: number;
+}
+export declare function skipShellComment(text: string, index: number): number;
+export declare function readShellQuoted(text: string, index: number, descend: (inner: string) => void): WordRead;
+export declare function readShellBalanced(text: string, index: number, close: string): WordRead;
+export declare function readShellWord(text: string, index: number, descend: (inner: string) => void): WordRead;
+export interface OperatorRead {
+    readonly operator: string;
+    readonly next: number;
+    readonly dropFd: boolean;
+}
+export declare function readShellOperator(text: string, index: number, lastWord: string | undefined): OperatorRead | undefined;
+export declare function readShellHeredoc(text: string, index: number, delimiter: string, stripTabs: boolean): WordRead;

package/dist/kernel/shell-word.js

@@ -0,0 +1,216 @@
+// SPEC §4.7.2: word-level lexing for the shell analyser. Pure scanners
+// over (text, index): quotes with $(…) and backtick descent, balanced
+// groups, bare words, redirection operators and heredoc bodies. The parser
+// feeds nested command text back through a descend callback, so this file
+// never imports the parser.
+import { ParseFailure } from "./shell.js";
+export function skipShellComment(text, index) {
+    let at = index;
+    while (at < text.length && text[at] !== "\n") {
+        at += 1;
+    }
+    return at;
+}
+function descendQuoted(text, index, descend) {
+    let at = index + 1;
+    const start = at;
+    while (at < text.length) {
+        const innerChar = text[at];
+        if (innerChar === "\\") {
+            at += 2;
+            continue;
+        }
+        if (innerChar === "`") {
+            break;
+        }
+        at += 1;
+    }
+    if (at >= text.length) {
+        throw new ParseFailure();
+    }
+    const inner = text.slice(start, at);
+    descend(inner);
+    return { value: inner, next: at + 1 };
+}
+// SPEC §4.7.2: single quotes are literal; double quotes keep $() and
+// backtick descent; an unclosed quote fails CDX-E306 upstream.
+export function readShellQuoted(text, index, descend) {
+    const quote = text[index];
+    if (quote === "`") {
+        const inner = readShellBalanced(text, index + 1, "`");
+        descend(inner.value);
+        return inner;
+    }
+    const out = [];
+    let at = index + 1;
+    while (at < text.length) {
+        const char = text[at];
+        if (char === quote) {
+            return { value: out.join(""), next: at + 1 };
+        }
+        if (char === "\\" && quote === '"') {
+            const next = text[at + 1];
+            if (next === "\n") {
+                at += 2;
+                continue;
+            }
+            if (next !== undefined) {
+                out.push(next);
+                at += 2;
+                continue;
+            }
+            throw new ParseFailure();
+        }
+        if (quote === '"' && char === "$" && text[at + 1] === "(") {
+            const inner = readShellBalanced(text, at + 2, ")");
+            descend(inner.value);
+            out.push(inner.value);
+            at = inner.next;
+            continue;
+        }
+        if (quote === '"' && char === "`") {
+            const inner = descendQuoted(text, at, descend);
+            out.push(inner.value);
+            at = inner.next;
+            continue;
+        }
+        out.push(char ?? "");
+        at += 1;
+    }
+    throw new ParseFailure();
+}
+// SPEC §4.7.2: quote-aware extent scan for $(…), `…`, (…) and {…}. Only
+// the extent is found here; descent happens at the call site.
+export function readShellBalanced(text, index, close) {
+    let depth = 1;
+    let at = index;
+    const start = at;
+    let quote;
+    while (at < text.length) {
+        const char = text[at];
+        if (quote !== undefined) {
+            if (char === "\\") {
+                at += 2;
+                continue;
+            }
+            if (char === quote) {
+                quote = undefined;
+            }
+            at += 1;
+            continue;
+        }
+        if (char === close) {
+            depth -= 1;
+            if (depth === 0) {
+                return { value: text.slice(start, at), next: at + 1 };
+            }
+            at += 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`") {
+            quote = char;
+            at += 1;
+            continue;
+        }
+        if (char === "$" && text[at + 1] === "(" && close === ")") {
+            depth += 1;
+            at += 2;
+            continue;
+        }
+        if (char === "(" && close === ")") {
+            depth += 1;
+            at += 1;
+            continue;
+        }
+        at += 1;
+    }
+    throw new ParseFailure();
+}
+const WORD_STOPS = new Set([
+    " ",
+    "\t",
+    "\n",
+    ";",
+    "&",
+    "|",
+    "(",
+    ")",
+    "{",
+    "}",
+    "<",
+    ">",
+    "'",
+    '"',
+    "`",
+    "#",
+]);
+export function readShellWord(text, index, descend) {
+    const out = [];
+    let at = index;
+    while (at < text.length) {
+        const char = text[at];
+        if (char === undefined || WORD_STOPS.has(char)) {
+            break;
+        }
+        if (char === "\\") {
+            const next = text[at + 1];
+            if (next === "\n") {
+                at += 2;
+                continue;
+            }
+            if (next !== undefined) {
+                out.push(next);
+                at += 2;
+                continue;
+            }
+            throw new ParseFailure();
+        }
+        if (char === "$" && text[at + 1] === "(") {
+            const inner = readShellBalanced(text, at + 2, ")");
+            descend(inner.value);
+            out.push(inner.value);
+            at = inner.next;
+            continue;
+        }
+        out.push(char);
+        at += 1;
+    }
+    return { value: out.join(""), next: at };
+}
+const REDIRECT_WORDS = new Set(["<<-", "<<<", "<<", ">>", ">|", "&>", ">&"]);
+export function readShellOperator(text, index, lastWord) {
+    const rest = text.slice(index);
+    for (const operator of REDIRECT_WORDS) {
+        if (rest.startsWith(operator)) {
+            return { operator, next: index + operator.length, dropFd: false };
+        }
+    }
+    const char = text[index];
+    if (char === ">" || char === "<") {
+        const dropFd = char === ">" && lastWord !== undefined && /^\d+$/.test(lastWord);
+        return { operator: char, next: index + 1, dropFd };
+    }
+    return undefined;
+}
+// SPEC §4.7.2: a heredoc without a terminator is unparseable (CDX-E306).
+export function readShellHeredoc(text, index, delimiter, stripTabs) {
+    let at = index;
+    if (text[at] === "\n") {
+        at += 1;
+    }
+    const body = [];
+    while (at < text.length) {
+        const end = text.indexOf("\n", at);
+        const line = end < 0 ? text.slice(at) : text.slice(at, end);
+        const compared = stripTabs ? line.replace(/^\t+/, "") : line;
+        if (compared === delimiter) {
+            return { value: body.join("\n"), next: end < 0 ? text.length : end + 1 };
+        }
+        body.push(line);
+        if (end < 0) {
+            throw new ParseFailure();
+        }
+        at = end + 1;
+    }
+    throw new ParseFailure();
+}

package/dist/kernel/shell.d.ts

@@ -0,0 +1,22 @@
+export interface SimpleCommand {
+    readonly name: string;
+    readonly argv: ReadonlyArray<string>;
+    readonly raw: string;
+    readonly elevated: boolean;
+    readonly embedded: ReadonlyArray<string>;
+}
+export interface ShellPipeline {
+    readonly commands: ReadonlyArray<SimpleCommand>;
+}
+export interface ShellAnalysis {
+    readonly pipelines: ReadonlyArray<ShellPipeline>;
+    readonly writeTargets: ReadonlyArray<string>;
+    readonly inputs: ReadonlyArray<string>;
+}
+export interface Collector {
+    readonly pipelines: Array<ShellPipeline>;
+    readonly writeTargets: Array<string>;
+    readonly inputs: Array<string>;
+}
+export declare class ParseFailure extends Error {
+}

package/dist/kernel/shell.js

@@ -0,0 +1,2 @@
+export class ParseFailure extends Error {
+}

package/dist/kernel/stdin.d.ts

@@ -0,0 +1,2 @@
+import { type Result } from "./result.ts";
+export declare function readStdinText(maxBytes: number, deadlineMs: number): Promise<Result<string>>;