rea-agents 1.6.0 → 2.0.0

package/dist/domain/electronStaticAnalysisIpc.js

@@ -0,0 +1,171 @@
+import * as t from "@babel/types";
+import { boundedExpression, electronStaticValue, handlerKind, } from "./electronStaticAnalysisValues.js";
+import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
+import { argumentNode, calleeName, propertyName, range, } from "./javascriptStaticAnalysisHelpers.js";
+/** Inspect Electron IPC operations and validation candidates. */
+export const inspectElectronIpcNode = (node, context) => {
+    if (t.isCallExpression(node)) {
+        inspectIpcCall(node, context);
+        inspectValidationCall(node, context);
+    }
+    if (t.isBinaryExpression(node))
+        inspectValidationComparison(node, context);
+};
+const inspectIpcCall = (node, context) => {
+    const name = calleeName(node.callee);
+    const descriptor = ipcDescriptor(name);
+    if (descriptor === undefined)
+        return;
+    const channelNode = argumentNode(node.arguments[0]);
+    const channelValue = electronStaticValue(context.source, channelNode);
+    const channel = channelValue.status === "literal" && typeof channelValue.value === "string"
+        ? channelValue.value
+        : null;
+    const channelExpression = channel === null
+        ? channelValue.status === "dynamic"
+            ? channelValue.expression
+            : boundedExpression(context.source, channelNode)
+        : null;
+    const hasHandler = descriptor.mode === "listen" || descriptor.mode === "handle";
+    const handlerNode = hasHandler ? argumentNode(node.arguments[1]) : undefined;
+    if (channel === null)
+        context.accumulator.unknownFindings += 1;
+    if (hasHandler && handlerNode === undefined)
+        context.accumulator.unknownFindings += 1;
+    const finding = {
+        ...descriptor,
+        channel,
+        channel_expression: channelExpression,
+        handler_kind: hasHandler ? handlerKind(handlerNode) : null,
+        handler_location: handlerNode === undefined ? null : range(handlerNode),
+        module_key: null,
+        location: range(node),
+    };
+    addLocatedFinding(context, {
+        collection: context.accumulator.ipc,
+        key: `electron-ipc\0${descriptor.side}\0${descriptor.operation}\0${channel ?? channelExpression ?? "[missing]"}`,
+        node,
+        value: finding,
+    });
+};
+const inspectValidationComparison = (node, context) => {
+    if (!["==", "===", "!=", "!==", "in"].includes(node.operator))
+        return;
+    const left = senderSubject(node.left);
+    const right = senderSubject(node.right);
+    if (left === undefined && right === undefined)
+        return;
+    const expected = left === undefined ? node.left : node.right;
+    addValidation(context, node, {
+        subject: left ?? right ?? "sender-frame",
+        mechanism: `comparison:${node.operator}`,
+        expected: electronStaticValue(context.source, expected),
+    });
+};
+const inspectValidationCall = (node, context) => {
+    if (!t.isMemberExpression(node.callee) &&
+        !t.isOptionalMemberExpression(node.callee))
+        return;
+    const method = propertyName(node.callee.property);
+    if (!["startsWith", "endsWith", "includes"].includes(method))
+        return;
+    const subject = t.isNode(node.callee.object)
+        ? senderSubject(node.callee.object)
+        : undefined;
+    if (subject === undefined)
+        return;
+    addValidation(context, node, {
+        subject,
+        mechanism: `call:${method}`,
+        expected: electronStaticValue(context.source, argumentNode(node.arguments[0])),
+    });
+};
+const addValidation = (context, node, input) => {
+    if (input.expected.status === "dynamic")
+        context.accumulator.unknownFindings += 1;
+    const finding = {
+        ...input,
+        enforcement: "unknown",
+        module_key: null,
+        location: range(node),
+    };
+    addLocatedFinding(context, {
+        collection: context.accumulator.senderValidations,
+        key: `electron-validation\0${input.subject}\0${input.mechanism}\0${input.expected.status === "literal" ? String(input.expected.value) : input.expected.expression}`,
+        node,
+        value: finding,
+    });
+};
+const ipcDescriptor = (name) => {
+    const renderer = suffixOperation(name, "ipcRenderer");
+    if (renderer !== undefined) {
+        switch (renderer) {
+            case "send":
+                return { side: "renderer", operation: "send", mode: "send" };
+            case "sendSync":
+                return { side: "renderer", operation: "send-sync", mode: "send" };
+            case "invoke":
+                return { side: "renderer", operation: "invoke", mode: "invoke" };
+            case "postMessage":
+                return {
+                    side: "renderer",
+                    operation: "post-message",
+                    mode: "send",
+                };
+            case "sendToHost":
+                return {
+                    side: "renderer",
+                    operation: "send-to-host",
+                    mode: "send",
+                };
+            case "on":
+                return { side: "renderer", operation: "on", mode: "listen" };
+            case "once":
+                return { side: "renderer", operation: "once", mode: "listen" };
+        }
+    }
+    const main = suffixOperation(name, "ipcMain");
+    switch (main) {
+        case "on":
+            return { side: "main", operation: "on", mode: "listen" };
+        case "once":
+            return { side: "main", operation: "once", mode: "listen" };
+        case "handle":
+            return { side: "main", operation: "handle", mode: "handle" };
+        case "handleOnce":
+            return { side: "main", operation: "handle-once", mode: "handle" };
+        default:
+            return undefined;
+    }
+};
+const suffixOperation = (name, object) => {
+    const marker = `${object}.`;
+    const index = name.lastIndexOf(marker);
+    if (index < 0)
+        return undefined;
+    const prefix = name.slice(0, index);
+    if (prefix !== "" && !prefix.endsWith("."))
+        return undefined;
+    const operation = name.slice(index + marker.length);
+    return operation.includes(".") ? undefined : operation;
+};
+const senderSubject = (node) => {
+    const name = t.isCallExpression(node)
+        ? calleeName(node.callee)
+        : calleeName(node);
+    if (/(?:^|\.)sender\.getURL$/u.test(name))
+        return "sender-url";
+    if (/(?:^|\.)senderFrame\.origin$/u.test(name))
+        return "sender-origin";
+    if (/(?:^|\.)senderFrame\.url$/u.test(name))
+        return "sender-url";
+    if (/(?:^|\.)senderFrame$/u.test(name))
+        return "sender-frame";
+    if (/(?:^|\.)sender\.id$/u.test(name))
+        return "sender-id";
+    if (/(?:^|\.)frameId$/u.test(name))
+        return "frame-id";
+    if (/(?:^|\.)processId$/u.test(name))
+        return "process-id";
+    return undefined;
+};

package/dist/domain/electronStaticAnalysisNative.js

@@ -0,0 +1,164 @@
+import * as t from "@babel/types";
+import { addLocatedFinding } from "./javascriptStaticAnalysisFindings.js";
+import { argumentNode, calleeName, compareCodePoints, propertyName, range, stringValue, } from "./javascriptStaticAnalysisHelpers.js";
+const MAX_NATIVE_MEMBERS = 64;
+/** Inspect JavaScript-side imports and re-exports of native .node addons. */
+export const inspectElectronNativeNode = (node, context) => {
+    if (t.isImportDeclaration(node))
+        inspectImport(node, context);
+    else if (t.isExportNamedDeclaration(node))
+        inspectNamedExport(node, context);
+    else if (t.isExportAllDeclaration(node))
+        inspectExportAll(node, context);
+    else if (t.isVariableDeclarator(node))
+        inspectRequireBinding(node, context);
+    else if (t.isAssignmentExpression(node))
+        inspectReExport(node, context);
+};
+const inspectImport = (node, context) => {
+    if (!isNativeSpecifier(node.source.value))
+        return;
+    const members = node.specifiers.map((specifier) => {
+        if (t.isImportDefaultSpecifier(specifier))
+            return "default";
+        if (t.isImportNamespaceSpecifier(specifier))
+            return "*";
+        return propertyName(specifier.imported) || "[dynamic-import]";
+    });
+    addBinding({
+        context,
+        node,
+        specifier: node.source.value,
+        kind: "import",
+        members,
+    });
+};
+const inspectNamedExport = (node, context) => {
+    if (node.source === null ||
+        node.source === undefined ||
+        !isNativeSpecifier(node.source.value))
+        return;
+    const members = node.specifiers.map((specifier) => {
+        if (t.isExportSpecifier(specifier))
+            return propertyName(specifier.local);
+        return "*";
+    });
+    addBinding({
+        context,
+        node,
+        specifier: node.source.value,
+        kind: "re-export",
+        members,
+    });
+};
+const inspectExportAll = (node, context) => {
+    if (node.source === undefined || !isNativeSpecifier(node.source.value))
+        return;
+    addBinding({
+        context,
+        node,
+        specifier: node.source.value,
+        kind: "re-export",
+        members: ["*"],
+    });
+};
+const inspectRequireBinding = (node, context) => {
+    const required = nativeRequire(node.init);
+    if (required === undefined)
+        return;
+    addBinding({
+        context,
+        node,
+        specifier: required.specifier,
+        kind: "require",
+        members: required.member === null ? bindingMembers(node.id) : [required.member],
+    });
+};
+const inspectReExport = (node, context) => {
+    const required = nativeRequire(node.right);
+    if (required === undefined || !isModuleExport(node.left))
+        return;
+    addBinding({
+        context,
+        node,
+        specifier: required.specifier,
+        kind: "re-export",
+        members: [required.member ?? exportedMember(node.left) ?? "*"],
+    });
+};
+const addBinding = (input) => {
+    const { context, node, specifier, kind } = input;
+    const unique = [
+        ...new Set(input.members.filter((member) => member !== "")),
+    ].sort(compareCodePoints);
+    const members = (unique.length === 0 ? ["*"] : unique).slice(0, MAX_NATIVE_MEMBERS);
+    const omitted = Math.max(0, unique.length - MAX_NATIVE_MEMBERS);
+    if (omitted > 0) {
+        context.accumulator.structuralTruncation = true;
+        context.accumulator.droppedFindings += omitted;
+    }
+    addLocatedFinding(context, {
+        collection: context.accumulator.nativeAddonBindings,
+        key: `native-addon-binding\0${kind}\0${specifier}\0${members.join("\0")}`,
+        node,
+        value: {
+            specifier,
+            binding_kind: kind,
+            members,
+            members_truncated: omitted > 0,
+            module_key: null,
+            location: range(node),
+        },
+    });
+};
+const nativeRequire = (node) => {
+    if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+        const nested = t.isNode(node.object)
+            ? nativeRequire(node.object)
+            : undefined;
+        if (nested === undefined)
+            return undefined;
+        const member = propertyName(node.property);
+        return { ...nested, member: member === "" ? nested.member : member };
+    }
+    if (!t.isCallExpression(node))
+        return undefined;
+    const name = calleeName(node.callee);
+    if (name !== "require" &&
+        !name.endsWith(".require") &&
+        !name.includes("__webpack_require__"))
+        return undefined;
+    const specifier = stringValue(argumentNode(node.arguments[0]));
+    return specifier !== undefined && isNativeSpecifier(specifier)
+        ? { specifier, member: null }
+        : undefined;
+};
+const bindingMembers = (pattern) => {
+    if (t.isIdentifier(pattern))
+        return ["*"];
+    if (!t.isObjectPattern(pattern))
+        return ["*"];
+    return pattern.properties.map((property) => {
+        if (t.isRestElement(property))
+            return "*";
+        return propertyName(property.key) || "[dynamic-import]";
+    });
+};
+const isModuleExport = (node) => {
+    const name = calleeName(node);
+    return (name === "module.exports" ||
+        name.startsWith("module.exports.") ||
+        name.startsWith("exports."));
+};
+const exportedMember = (node) => {
+    const name = calleeName(node);
+    if (name.startsWith("module.exports."))
+        return name.slice("module.exports.".length);
+    if (name.startsWith("exports."))
+        return name.slice("exports.".length);
+    return undefined;
+};
+const isNativeSpecifier = (specifier) => {
+    const path = specifier.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+    return path.toLowerCase().endsWith(".node");
+};

package/dist/domain/electronStaticAnalysisTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/electronStaticAnalysisValues.js

@@ -0,0 +1,103 @@
+import * as t from "@babel/types";
+import { compareCodePoints, propertyName, sourceSlice, } from "./javascriptStaticAnalysisHelpers.js";
+const MAX_EXPRESSION_CHARACTERS = 4_096;
+/** Preserve one literal value or the exact bounded inert expression. */
+export const electronStaticValue = (source, node) => {
+    const literal = literalValue(node);
+    return literal.found
+        ? { status: "literal", value: literal.value, expression: null }
+        : {
+            status: "dynamic",
+            value: null,
+            expression: boundedExpression(source, node),
+        };
+};
+/** Return an actionable bounded expression without evaluating it. */
+export const boundedExpression = (source, node) => {
+    if (node === null || node === undefined)
+        return "[missing-expression]";
+    const expression = sourceSlice(source, node).trim();
+    return (expression === "" ? `[${node.type}]` : expression).slice(0, MAX_EXPRESSION_CHARACTERS);
+};
+/** Read one named object property without following spreads or bindings. */
+export const objectProperty = (object, name) => object.properties.find((property) => t.isObjectProperty(property) && propertyName(property.key) === name);
+/** Classify a handler argument while retaining its exact source range. */
+export const handlerKind = (node) => {
+    if (node === null || node === undefined)
+        return "missing";
+    if (t.isArrowFunctionExpression(node) ||
+        t.isFunctionExpression(node) ||
+        t.isFunctionDeclaration(node))
+        return "inline-function";
+    if (t.isIdentifier(node))
+        return "identifier";
+    if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
+        return "member-expression";
+    return "dynamic-expression";
+};
+/** Collect bounded dotted keys from one literal contextBridge API object. */
+export const collectContextBridgeMembers = (node, maximum = 128) => {
+    if (node === null || node === undefined)
+        return {
+            status: "missing",
+            members: [],
+            unknown: 0,
+            omitted: 0,
+        };
+    if (!t.isObjectExpression(node))
+        return {
+            status: "dynamic",
+            members: [],
+            unknown: 1,
+            omitted: 0,
+        };
+    const state = { members: [], unknown: 0 };
+    collectMembersAt(node, "", 0, state);
+    const members = [...new Set(state.members)].sort(compareCodePoints);
+    return {
+        status: "object-literal",
+        members: members.slice(0, maximum),
+        unknown: state.unknown,
+        omitted: Math.max(0, members.length - maximum),
+    };
+};
+const collectMembersAt = (object, prefix, depth, state) => {
+    if (depth >= 8) {
+        state.unknown += 1;
+        return;
+    }
+    for (const property of object.properties) {
+        if (t.isSpreadElement(property)) {
+            state.unknown += 1;
+            continue;
+        }
+        const name = propertyName(property.key);
+        if (name === "" || property.computed) {
+            state.unknown += 1;
+            continue;
+        }
+        const path = (prefix === "" ? name : `${prefix}.${name}`).slice(0, MAX_EXPRESSION_CHARACTERS);
+        state.members.push(path);
+        if (t.isObjectProperty(property) && t.isObjectExpression(property.value))
+            collectMembersAt(property.value, path, depth + 1, state);
+    }
+};
+const literalValue = (node) => {
+    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
+        return { found: true, value: node.value };
+    if (t.isBooleanLiteral(node))
+        return { found: true, value: node.value };
+    if (t.isNullLiteral(node))
+        return { found: true, value: null };
+    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
+        return {
+            found: true,
+            value: (node.quasis[0]?.value.cooked ??
+                node.quasis[0]?.value.raw ??
+                "").slice(0, MAX_EXPRESSION_CHARACTERS),
+        };
+    if (t.isUnaryExpression(node, { operator: "-" }) &&
+        t.isNumericLiteral(node.argument))
+        return { found: true, value: -node.argument.value };
+    return { found: false };
+};