feat(electron): map static process and IPC boundaries

This commit is contained in:
N0zoM1z0
2026-07-16 07:56:13 +09:00
committed by N0zoM1z0
parent 3988a866f1
commit 3fa2304bc7
279 changed files with 7481 additions and 775 deletions
+203
View File
@@ -0,0 +1,203 @@
import type { ElectronIpcFinding } from "../domain/electronStaticAnalysisTypes.js";
import type { ElectronBoundarySummary } from "../domain/javascriptApplicationAnalysis.js";
import type { JavaScriptArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
import { resolveArtifactPath } from "./JavaScriptArtifactGraphContext.js";
/** One IPC fact retaining its exact owning artifact for graph projection. */
export interface ElectronIpcRecord {
readonly key: string;
readonly file: JavaScriptArtifactFile;
readonly finding: ElectronIpcFinding;
}
/** An unambiguous literal renderer-to-main static pairing. */
export interface ElectronIpcPairing {
readonly transmission: ElectronIpcRecord;
readonly handler: ElectronIpcRecord;
}
/** Pairing state for one renderer transmission without overclaiming ambiguity. */
export interface ElectronIpcPairingState {
readonly transmission: ElectronIpcRecord;
readonly candidates: readonly ElectronIpcRecord[];
readonly status: "paired" | "ambiguous" | "unpaired";
}
/** Flatten all per-file IPC facts into deterministic application records. */
export const collectElectronIpcRecords = (
analysis: JavaScriptArtifactAnalysis,
): readonly ElectronIpcRecord[] =>
analysis.files
.flatMap(({ file, javascript }) =>
(javascript?.electron.ipc ?? []).map((finding) => ({
key: ipcRecordKey(file.path, finding),
file,
finding,
})),
)
.sort((left, right) => compareCodePoints(left.key, right.key));
/** Match only exact literal channels and retain ambiguous matches separately. */
export const classifyElectronIpcPairings = (
records: readonly ElectronIpcRecord[],
): readonly ElectronIpcPairingState[] => {
const handlers = records.filter(isMainHandler);
return records.filter(isPairableRendererTransmission).map((transmission) => {
const candidates =
transmission.finding.channel === null
? []
: handlers.filter(
(handler) =>
handler.finding.channel === transmission.finding.channel &&
compatibleIpcModes(transmission.finding, handler.finding),
);
return {
transmission,
candidates,
status:
candidates.length === 1
? "paired"
: candidates.length > 1
? "ambiguous"
: "unpaired",
};
});
};
/** Return only pairings supported by one unique literal main handler. */
export const unambiguousElectronIpcPairings = (
records: readonly ElectronIpcRecord[],
): readonly ElectronIpcPairing[] =>
classifyElectronIpcPairings(records).flatMap((state) => {
const handler = state.candidates[0];
return state.status === "paired" && handler !== undefined
? [{ transmission: state.transmission, handler }]
: [];
});
/** Summarize static Electron findings without treating gaps as absence. */
export const summarizeElectronBoundaries = (
analysis: JavaScriptArtifactAnalysis,
): ElectronBoundarySummary => {
const files = new Map(analysis.files.map(({ file }) => [file.path, file]));
const javascript = analysis.files.flatMap(({ javascript: value }) =>
value === null ? [] : [value],
);
const windows = javascript.flatMap(
({ electron }) => electron.browser_windows,
);
const bridges = javascript.flatMap(
({ electron }) => electron.context_bridge_apis,
);
const validations = javascript.flatMap(
({ electron }) => electron.sender_validations,
);
const utilities = analysis.files.flatMap(({ file, javascript: value }) =>
(value?.electron.utility_processes ?? []).map((finding) => ({
file,
finding,
})),
);
const nativeBindings = analysis.files.flatMap(({ file, javascript: value }) =>
(value?.electron.native_addon_bindings ?? []).map((finding) => ({
file,
finding,
})),
);
const ipc = collectElectronIpcRecords(analysis);
const pairing = classifyElectronIpcPairings(ipc);
const literalChannels = new Set(
ipc.flatMap(({ finding }) =>
finding.channel === null ? [] : [finding.channel],
),
);
return {
browser_windows: windows.length,
explicit_web_preferences: windows.reduce(
(count, window) => count + window.web_preferences.length,
0,
),
preload_entrypoints: windows.filter(
({ preload_path: path }) => path !== null,
).length,
context_bridge_apis: bridges.length,
exposed_api_members: bridges.reduce(
(count, bridge) => count + bridge.members.length,
0,
),
ipc: {
operations: ipc.length,
literal_channels: literalChannels.size,
dynamic_channel_operations: ipc.filter(
({ finding }) => finding.channel === null,
).length,
renderer_transmissions: ipc.filter(isRendererTransmission).length,
renderer_listeners: ipc.filter(
({ finding }) =>
finding.side === "renderer" && finding.mode === "listen",
).length,
main_handlers: ipc.filter(isMainHandler).length,
paired_renderer_transmissions: pairing.filter(
({ status }) => status === "paired",
).length,
ambiguous_renderer_transmissions: pairing.filter(
({ status }) => status === "ambiguous",
).length,
unpaired_literal_renderer_transmissions: pairing.filter(
({ status, transmission }) =>
status === "unpaired" && transmission.finding.channel !== null,
).length,
},
sender_validation_observations: validations.length,
utility_processes: utilities.length,
resolved_utility_entrypoints: utilities.filter(({ file, finding }) =>
resolvesToFile(file, finding.module_path, files),
).length,
native_addon_bindings: nativeBindings.length,
resolved_native_addon_bindings: nativeBindings.filter(({ file, finding }) =>
resolvesToFile(file, finding.specifier, files, "native-addon"),
).length,
};
};
const compatibleIpcModes = (
transmission: ElectronIpcFinding,
handler: ElectronIpcFinding,
): boolean =>
transmission.mode === "invoke"
? handler.mode === "handle"
: transmission.operation === "send-to-host"
? false
: transmission.mode === "send" && handler.mode === "listen";
const isRendererTransmission = ({ finding }: ElectronIpcRecord): boolean =>
finding.side === "renderer" &&
(finding.mode === "send" || finding.mode === "invoke");
const isPairableRendererTransmission = (record: ElectronIpcRecord): boolean =>
isRendererTransmission(record) && record.finding.operation !== "send-to-host";
const isMainHandler = ({ finding }: ElectronIpcRecord): boolean =>
finding.side === "main" &&
(finding.mode === "listen" || finding.mode === "handle");
const resolvesToFile = (
file: JavaScriptArtifactFile,
specifier: string | null,
files: ReadonlyMap<string, JavaScriptArtifactFile>,
kind?: JavaScriptArtifactFile["kind"],
): boolean => {
if (specifier === null) return false;
const resolved = resolveArtifactPath(specifier, file.path, files);
return (
resolved !== null &&
(kind === undefined || files.get(resolved)?.kind === kind)
);
};
const ipcRecordKey = (path: string, finding: ElectronIpcFinding): string =>
`${path}\0${String(finding.location.start.line)}:${String(finding.location.start.column)}\0${finding.side}\0${finding.operation}`;
const compareCodePoints = (left: string, right: string): number =>
left < right ? -1 : left > right ? 1 : 0;
+13
View File
@@ -0,0 +1,13 @@
import type { JavaScriptArtifactGraphContext } from "./JavaScriptArtifactGraphContext.js";
import { addElectronIpcBoundaries } from "./ElectronBoundaryGraphIpc.js";
import { addElectronNativeBoundaries } from "./ElectronBoundaryGraphNative.js";
import { addElectronWindowBoundaries } from "./ElectronBoundaryGraphWindows.js";
/** Add every static Electron process and security-boundary fact to the JAG. */
export const addElectronBoundaries = (
context: JavaScriptArtifactGraphContext,
): void => {
addElectronWindowBoundaries(context);
addElectronIpcBoundaries(context);
addElectronNativeBoundaries(context);
};
@@ -0,0 +1,127 @@
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
import { sha256Text } from "../domain/javascriptStaticAnalysisHelpers.js";
import type { JavaScriptSourceRange } from "../domain/javascriptStaticAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
import type {
JavaScriptArtifactGraphContext,
JavaScriptArtifactGraphCoverage,
} from "./JavaScriptArtifactGraphContext.js";
import {
astObservationEvidence,
staticInferenceEvidence,
} from "./JavaScriptArtifactGraphEvidence.js";
/** Values for one Electron syntax relationship retained in the graph. */
export interface ElectronGraphEdgeInput {
readonly source: ApplicationNode;
readonly target: ApplicationNode;
readonly file: JavaScriptArtifactFile;
readonly range: JavaScriptSourceRange;
readonly coverage: JavaScriptArtifactGraphCoverage;
readonly relation:
| "contains"
| "loads"
| "imports"
| "maps_to"
| "exposes"
| "sends"
| "invokes"
| "handles";
readonly operation: string;
readonly properties: Readonly<Record<string, unknown>>;
readonly confidence?: "high" | "medium" | "low";
readonly limitations?: readonly string[];
}
/** Resolve the file or recovered bundle module that owns one finding. */
export const electronFindingSourceNode = (
context: JavaScriptArtifactGraphContext,
file: JavaScriptArtifactFile,
moduleKey: string | null,
): ApplicationNode | undefined =>
moduleKey === null
? (context.assetNodes.get(file.path) ?? context.fileNodes.get(file.path))
: context.moduleNodes.get(`${file.path}\0${moduleKey}`);
/** Observation-scoped identity shared safely across different artifact files. */
export const electronObservationIdentity = (
context: JavaScriptArtifactGraphContext,
scope: string,
key: string,
) => ({
strategy: "observation-fingerprint" as const,
stability: "observation-only" as const,
observation_sha256: sha256Text(
`${context.snapshot.manifest.root_sha256}\0${scope}\0${key}`,
),
scope: scope.slice(0, 4_096),
});
/** Add a direct AST syntax relationship. */
export const addElectronAstEdge = (
context: JavaScriptArtifactGraphContext,
input: ElectronGraphEdgeInput,
): void => {
context.accumulator.addEdge({
source_node_id: input.source.node_id,
target_node_id: input.target.node_id,
relation: input.relation,
properties: input.properties,
evidence: astObservationEvidence({
sha256: input.file.sha256,
path: input.file.path,
range: input.range,
operation: input.operation,
coverage: input.coverage,
...(input.limitations === undefined
? {}
: { limitations: input.limitations }),
}),
});
};
/** Add an Electron relationship that static syntax suggests but cannot prove. */
export const addElectronInferenceEdge = (
context: JavaScriptArtifactGraphContext,
input: ElectronGraphEdgeInput,
): void => {
context.accumulator.addEdge({
source_node_id: input.source.node_id,
target_node_id: input.target.node_id,
relation: input.relation,
properties: input.properties,
evidence: staticInferenceEvidence({
sha256: input.file.sha256,
path: input.file.path,
range: input.range,
operation: input.operation,
coverage: input.coverage,
...(input.confidence === undefined
? {}
: { confidence: input.confidence }),
...(input.limitations === undefined
? {}
: { limitations: input.limitations }),
}),
});
};
/** Deterministic source-range key for artifact-local graph identities. */
export const electronRangeKey = (range: JavaScriptSourceRange): string =>
`${String(range.start.line)}:${String(range.start.column)}-${String(range.end.line)}:${String(range.end.column)}`;
/** Test exact source-range containment without assuming runtime reachability. */
export const electronRangeContains = (
outer: JavaScriptSourceRange,
inner: JavaScriptSourceRange,
): boolean =>
comparePoint(outer.start, inner.start) <= 0 &&
comparePoint(outer.end, inner.end) >= 0;
const comparePoint = (
left: JavaScriptSourceRange["start"],
right: JavaScriptSourceRange["start"],
): number =>
left.line === right.line
? left.column - right.column
: left.line - right.line;
+345
View File
@@ -0,0 +1,345 @@
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
import type { ElectronSenderValidationFinding } from "../domain/electronStaticAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
import {
artifactLocalIdentity,
javascriptAnalysisCoverage,
type JavaScriptArtifactGraphContext,
type JavaScriptArtifactGraphCoverage,
} from "./JavaScriptArtifactGraphContext.js";
import { astObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
import {
collectElectronIpcRecords,
unambiguousElectronIpcPairings,
type ElectronIpcRecord,
} from "./ElectronBoundaryAnalysis.js";
import {
addElectronAstEdge,
addElectronInferenceEdge,
electronFindingSourceNode,
electronObservationIdentity,
electronRangeContains,
electronRangeKey,
} from "./ElectronBoundaryGraphContext.js";
interface IpcGraphState {
readonly context: JavaScriptArtifactGraphContext;
readonly records: readonly ElectronIpcRecord[];
readonly channels: Map<string, ApplicationNode>;
readonly handlers: Map<string, ApplicationNode>;
readonly sources: Map<string, ApplicationNode>;
}
interface IpcHandlerInput {
readonly context: JavaScriptArtifactGraphContext;
readonly record: ElectronIpcRecord;
readonly source: ApplicationNode;
readonly channel: ApplicationNode;
readonly coverage: JavaScriptArtifactGraphCoverage;
}
interface ValidationObservationInput {
readonly context: JavaScriptArtifactGraphContext;
readonly file: JavaScriptArtifactFile;
readonly validation: ElectronSenderValidationFinding;
readonly target: ApplicationNode;
readonly coverage: JavaScriptArtifactGraphCoverage;
}
/** Project IPC syntax, handler locations, validations, and exact pairings. */
export const addElectronIpcBoundaries = (
context: JavaScriptArtifactGraphContext,
): void => {
const state: IpcGraphState = {
context,
records: collectElectronIpcRecords(context.analysis),
channels: new Map(),
handlers: new Map(),
sources: new Map(),
};
for (const record of state.records) addIpcRecord(state, record);
addValidationObservations(state);
addLiteralPairings(state);
};
const addIpcRecord = (
state: IpcGraphState,
record: ElectronIpcRecord,
): void => {
const { context } = state;
const coverage = coverageFor(context, record.file);
if (coverage === undefined) return;
const source = electronFindingSourceNode(
context,
record.file,
record.finding.module_key,
);
if (source === undefined) return;
state.sources.set(record.key, source);
const channel = addChannelNode(context, record, coverage);
state.channels.set(record.key, channel);
if (record.finding.mode === "listen" || record.finding.mode === "handle") {
const handler = addHandlerNode({
context,
record,
source,
channel,
coverage,
});
state.handlers.set(record.key, handler);
return;
}
addElectronInferenceEdge(context, {
source,
target: channel,
file: record.file,
range: record.finding.location,
coverage,
relation: record.finding.mode === "invoke" ? "invokes" : "sends",
operation: "map-ipc-transmission",
properties: {
side: record.finding.side,
operation: record.finding.operation,
channel: record.finding.channel,
channel_expression: record.finding.channel_expression,
resolution: record.finding.channel === null ? "dynamic" : "literal",
},
});
};
const addChannelNode = (
context: JavaScriptArtifactGraphContext,
record: ElectronIpcRecord,
coverage: JavaScriptArtifactGraphCoverage,
): ApplicationNode => {
const { finding, file } = record;
const identityKey =
finding.channel === null
? `dynamic:${record.key}`
: `literal:${finding.channel}`;
return context.accumulator.addNode({
kind: "ipc-channel",
identity: electronObservationIdentity(
context,
"electron-ipc-channel",
identityKey,
),
observations: [
{
label: finding.channel ?? finding.channel_expression,
properties: {
side: finding.side,
operation: finding.operation,
mode: finding.mode,
channel: finding.channel,
channel_expression: finding.channel_expression,
resolution: finding.channel === null ? "dynamic" : "literal",
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: finding.location,
operation: "observe-ipc-channel-expression",
coverage,
limitations:
finding.channel === null
? [
"The channel expression is dynamic; its runtime value and pairings remain unknown.",
]
: [],
}),
},
],
});
};
const addHandlerNode = (input: IpcHandlerInput): ApplicationNode => {
const { context, record, source, channel, coverage } = input;
const { finding, file } = record;
const handlerRange = finding.handler_location ?? finding.location;
const handler = context.accumulator.addNode({
kind: "ipc-handler",
identity: artifactLocalIdentity(
file.sha256,
"electron-ipc-handler",
`${finding.side}:${finding.operation}:${finding.channel ?? finding.channel_expression ?? "[missing]"}:${electronRangeKey(handlerRange)}`,
),
observations: [
{
label: finding.channel,
properties: {
side: finding.side,
operation: finding.operation,
mode: finding.mode,
channel: finding.channel,
channel_expression: finding.channel_expression,
handler_kind: finding.handler_kind,
handler_location: finding.handler_location,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: handlerRange,
operation: "observe-ipc-handler",
coverage,
}),
},
],
});
addElectronAstEdge(context, {
source,
target: handler,
file,
range: handlerRange,
coverage,
relation: "contains",
operation: "locate-ipc-handler",
properties: { side: finding.side, operation: finding.operation },
});
addElectronInferenceEdge(context, {
source: handler,
target: channel,
file,
range: finding.location,
coverage,
relation: "handles",
operation: "map-ipc-handler-registration",
properties: {
channel: finding.channel,
channel_expression: finding.channel_expression,
resolution: finding.channel === null ? "dynamic" : "literal",
},
});
return handler;
};
const addLiteralPairings = (state: IpcGraphState): void => {
for (const pairing of unambiguousElectronIpcPairings(state.records)) {
const source = state.sources.get(pairing.transmission.key);
const handler = state.handlers.get(pairing.handler.key);
const coverage = coverageFor(state.context, pairing.transmission.file);
if (source === undefined || handler === undefined || coverage === undefined)
continue;
addElectronInferenceEdge(state.context, {
source,
target: handler,
file: pairing.transmission.file,
range: pairing.transmission.finding.location,
coverage,
relation:
pairing.transmission.finding.mode === "invoke" ? "invokes" : "sends",
operation: "pair-ipc-literal-channel",
properties: {
channel: pairing.transmission.finding.channel,
pairing_basis: "unique-exact-literal-channel",
handler_path: pairing.handler.file.path,
handler_operation: pairing.handler.finding.operation,
},
limitations: [
"Literal channel equality does not prove that the handler is registered or reachable at runtime.",
],
});
}
};
const addValidationObservations = (state: IpcGraphState): void => {
for (const analyzed of state.context.analysis.files) {
const { file, javascript } = analyzed;
if (javascript === null) continue;
const coverage = javascriptAnalysisCoverage(
javascript,
state.context.input,
);
for (const validation of javascript.electron.sender_validations) {
const handlerRecord = containingHandler(state.records, file, validation);
const target =
handlerRecord === undefined
? electronFindingSourceNode(
state.context,
file,
validation.module_key,
)
: state.handlers.get(handlerRecord.key);
if (target !== undefined)
addValidationObservation({
context: state.context,
file,
validation,
target,
coverage,
});
}
}
};
const addValidationObservation = (input: ValidationObservationInput): void => {
const { context, file, validation, target, coverage } = input;
context.accumulator.addNode({
kind: target.kind,
identity: target.identity,
observations: [
{
label: `${validation.subject} validation candidate`,
properties: {
fact_kind: "sender-validation-candidate",
subject: validation.subject,
mechanism: validation.mechanism,
expected: validation.expected,
enforcement: validation.enforcement,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: validation.location,
operation: "observe-ipc-sender-validation-candidate",
coverage,
limitations: [
"A comparison or string check is visible, but static syntax alone does not prove rejection, ordering, or complete sender validation.",
],
}),
},
],
});
};
const containingHandler = (
records: readonly ElectronIpcRecord[],
file: JavaScriptArtifactFile,
validation: ElectronSenderValidationFinding,
): ElectronIpcRecord | undefined =>
records
.filter(
(record) =>
record.file.path === file.path &&
record.finding.handler_location !== null &&
electronRangeContains(
record.finding.handler_location,
validation.location,
),
)
.sort(
(left, right) =>
rangeMagnitude(left.finding.handler_location) -
rangeMagnitude(right.finding.handler_location),
)[0];
const rangeMagnitude = (
range: ElectronIpcRecord["finding"]["handler_location"],
): number =>
range === null
? Number.MAX_SAFE_INTEGER
: (range.end.line - range.start.line) * 1_000_000 +
range.end.column -
range.start.column;
const coverageFor = (
context: JavaScriptArtifactGraphContext,
file: JavaScriptArtifactFile,
): JavaScriptArtifactGraphCoverage | undefined => {
const javascript = context.analysis.files.find(
({ file: candidate }) => candidate.path === file.path,
)?.javascript;
return javascript === null || javascript === undefined
? undefined
: javascriptAnalysisCoverage(javascript, context.input);
};
@@ -0,0 +1,114 @@
import type { ElectronNativeAddonBindingFinding } from "../domain/electronStaticAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
import {
javascriptAnalysisCoverage,
resolveArtifactPath,
type JavaScriptArtifactGraphContext,
type JavaScriptArtifactGraphCoverage,
} from "./JavaScriptArtifactGraphContext.js";
import { astObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
import {
addElectronInferenceEdge,
electronFindingSourceNode,
electronObservationIdentity,
electronRangeKey,
} from "./ElectronBoundaryGraphContext.js";
interface NativeBindingInput {
readonly context: JavaScriptArtifactGraphContext;
readonly file: JavaScriptArtifactFile;
readonly value: ElectronNativeAddonBindingFinding;
readonly coverage: JavaScriptArtifactGraphCoverage;
}
/** Project JavaScript-requested native addon binding and re-export surfaces. */
export const addElectronNativeBoundaries = (
context: JavaScriptArtifactGraphContext,
): void => {
for (const analyzed of context.analysis.files) {
const { file, javascript } = analyzed;
if (javascript === null) continue;
const coverage = javascriptAnalysisCoverage(javascript, context.input);
for (const value of javascript.electron.native_addon_bindings)
addNativeBinding({ context, file, value, coverage });
}
};
const addNativeBinding = (input: NativeBindingInput): void => {
const { context, file, value, coverage } = input;
const source = electronFindingSourceNode(context, file, value.module_key);
if (source === undefined) return;
const resolved = resolveArtifactPath(
value.specifier,
file.path,
context.filesByPath,
);
const addon = resolved === null ? undefined : context.fileNodes.get(resolved);
const binding = context.accumulator.addNode({
kind: "native-export",
identity: electronObservationIdentity(
context,
"javascript-requested-native-export",
`${file.path}:${value.specifier}:${value.binding_kind}:${value.members.join("\0")}:${electronRangeKey(value.location)}`,
),
observations: [
{
label: value.members.join(", "),
properties: {
specifier: value.specifier,
binding_kind: value.binding_kind,
requested_members: value.members,
members_truncated: value.members_truncated,
resolved_path: resolved,
native_export_verification: "not-performed",
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: value.location,
operation: "observe-native-addon-binding",
coverage,
limitations: [
"JavaScript syntax identifies requested member names; it does not prove that the native binary exports or implements them.",
],
}),
},
],
});
addElectronInferenceEdge(context, {
source,
target: binding,
file,
range: value.location,
coverage,
relation: value.binding_kind === "re-export" ? "exposes" : "imports",
operation: "map-native-addon-binding",
properties: {
specifier: value.specifier,
binding_kind: value.binding_kind,
requested_members: value.members,
},
limitations: [
"Requested JavaScript members are not verified native exports.",
],
});
if (addon === undefined || resolved === null) return;
addElectronInferenceEdge(context, {
source: addon,
target: binding,
file,
range: value.location,
coverage,
relation: "exposes",
operation: "associate-native-addon-requested-exports",
properties: {
resolved_path: resolved,
requested_members: value.members,
verified: false,
},
confidence: "medium",
limitations: [
"The .node artifact path is resolved, but requested JavaScript members have not been verified against native symbols.",
],
});
};
@@ -0,0 +1,260 @@
import type { ApplicationNode } from "../domain/javascriptApplicationGraph.js";
import type {
ElectronBrowserWindowFinding,
ElectronContextBridgeFinding,
ElectronUtilityProcessFinding,
} from "../domain/electronStaticAnalysisTypes.js";
import type { JavaScriptArtifactFile } from "./JavaScriptArtifactFiles.js";
import {
artifactLocalIdentity,
createElectronRoleNode,
javascriptAnalysisCoverage,
linkElectronRoleToAsset,
resolveArtifactPath,
type JavaScriptArtifactGraphContext,
type JavaScriptArtifactGraphCoverage,
} from "./JavaScriptArtifactGraphContext.js";
import { astObservationEvidence } from "./JavaScriptArtifactGraphEvidence.js";
import {
addElectronAstEdge,
addElectronInferenceEdge,
electronFindingSourceNode,
electronRangeKey,
} from "./ElectronBoundaryGraphContext.js";
interface FindingInput<Value> {
readonly context: JavaScriptArtifactGraphContext;
readonly file: JavaScriptArtifactFile;
readonly source: ApplicationNode;
readonly value: Value;
readonly coverage: JavaScriptArtifactGraphCoverage;
}
/** Project BrowserWindow, contextBridge, preload, and utility-process facts. */
export const addElectronWindowBoundaries = (
context: JavaScriptArtifactGraphContext,
): void => {
for (const analyzed of context.analysis.files) {
const { file, javascript } = analyzed;
if (javascript === null) continue;
const coverage = javascriptAnalysisCoverage(javascript, context.input);
for (const value of javascript.electron.browser_windows) {
const source = electronFindingSourceNode(context, file, value.module_key);
if (source !== undefined)
addBrowserWindow({ context, file, source, value, coverage });
}
for (const value of javascript.electron.context_bridge_apis) {
const source = electronFindingSourceNode(context, file, value.module_key);
if (source !== undefined)
addContextBridge({ context, file, source, value, coverage });
}
for (const value of javascript.electron.utility_processes) {
const source = electronFindingSourceNode(context, file, value.module_key);
if (source !== undefined)
addUtilityProcess({ context, file, source, value, coverage });
}
}
};
const addBrowserWindow = (
input: FindingInput<ElectronBrowserWindowFinding>,
): void => {
const { context, file, value, coverage } = input;
const window = context.accumulator.addNode({
kind: "browser-window",
identity: artifactLocalIdentity(
file.sha256,
"electron-browser-window",
electronRangeKey(value.location),
),
observations: [
{
label: `BrowserWindow@${electronRangeKey(value.location)}`,
properties: {
source_path: file.path,
options_status: value.options_status,
web_preferences_status: value.web_preferences_status,
web_preferences: value.web_preferences,
omitted_web_preferences: value.omitted_web_preferences,
preload_path: value.preload_path,
absence_means_default: false,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: value.location,
operation: "observe-browser-window-construction",
coverage,
limitations: [
"Only explicitly present webPreferences are reported; omitted properties are not interpreted as Electron defaults.",
],
}),
},
],
});
addElectronAstEdge(context, {
source: input.source,
target: window,
file,
range: value.location,
coverage,
relation: "contains",
operation: "locate-browser-window-construction",
properties: { source_path: file.path },
});
addWindowPreload(input, window);
};
const addWindowPreload = (
input: FindingInput<ElectronBrowserWindowFinding>,
window: ApplicationNode,
): void => {
const declared = input.value.preload_path;
if (declared === null) return;
const resolved = resolveArtifactPath(
declared,
input.file.path,
input.context.filesByPath,
);
const role = createElectronRoleNode(input.context, {
kind: "electron-preload",
anchor: input.file,
declaredPath: declared,
resolvedPath: resolved,
mechanism: "BrowserWindow:webPreferences.preload",
range: input.value.location,
coverage: input.coverage,
});
addElectronInferenceEdge(input.context, {
source: window,
target: role,
file: input.file,
range: input.value.location,
coverage: input.coverage,
relation: "loads",
operation: "associate-browser-window-preload",
properties: { declared_path: declared, resolved_path: resolved },
});
linkElectronRoleToAsset(input.context, {
role,
anchor: input.file,
path: resolved,
range: input.value.location,
coverage: input.coverage,
});
};
const addContextBridge = (
input: FindingInput<ElectronContextBridgeFinding>,
): void => {
const { context, file, value, coverage } = input;
const bridge = context.accumulator.addNode({
kind: "context-bridge-api",
identity: artifactLocalIdentity(
file.sha256,
"electron-context-bridge",
`${value.world}:${value.api_key ?? value.api_key_expression ?? "[missing]"}:${electronRangeKey(value.location)}`,
),
observations: [
{
label: value.api_key,
properties: {
world: value.world,
world_id: value.world_id,
api_key: value.api_key,
api_key_expression: value.api_key_expression,
api_status: value.api_status,
members: value.members,
unknown_members: value.unknown_members,
omitted_members: value.omitted_members,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: value.location,
operation: "observe-context-bridge-api",
coverage,
}),
},
],
});
addElectronInferenceEdge(context, {
source: input.source,
target: bridge,
file,
range: value.location,
coverage,
relation: "exposes",
operation: "map-context-bridge-exposure",
properties: {
world: value.world,
api_key: value.api_key,
resolution: value.api_key === null ? "dynamic" : "literal",
},
});
};
const addUtilityProcess = (
input: FindingInput<ElectronUtilityProcessFinding>,
): void => {
const { context, file, value, coverage } = input;
const utility = context.accumulator.addNode({
kind: "electron-utility",
identity: artifactLocalIdentity(
file.sha256,
"electron-utility-process",
`${value.module_path ?? value.module_expression ?? "[missing]"}:${electronRangeKey(value.location)}`,
),
observations: [
{
label: value.service_name ?? value.module_path,
properties: {
module_path: value.module_path,
module_expression: value.module_expression,
service_name: value.service_name,
},
evidence: astObservationEvidence({
sha256: file.sha256,
path: file.path,
range: value.location,
operation: "observe-utility-process-fork",
coverage,
}),
},
],
});
addElectronInferenceEdge(context, {
source: input.source,
target: utility,
file,
range: value.location,
coverage,
relation: "loads",
operation: "map-utility-process-launch",
properties: {
declared_path: value.module_path,
expression: value.module_expression,
},
});
if (value.module_path === null) return;
const resolved = resolveArtifactPath(
value.module_path,
file.path,
context.filesByPath,
);
const target =
resolved === null
? undefined
: (context.assetNodes.get(resolved) ?? context.fileNodes.get(resolved));
if (target === undefined) return;
addElectronInferenceEdge(context, {
source: utility,
target,
file,
range: value.location,
coverage,
relation: "maps_to",
operation: "resolve-utility-process-entrypoint",
properties: { resolved_path: resolved },
});
};
@@ -25,6 +25,13 @@ export const ARTIFACT_GRAPH_PROVIDER = {
version: "1",
} as const;
/** Provider identity for deterministic static JavaScript application analysis. */
export const JAVASCRIPT_APPLICATION_PROVIDER = {
id: "rea-javascript-application",
name: "REA JavaScript application analyzer",
version: "1",
} as const;
/** Provider identity for deterministic cross-artifact comparisons. */
export const ARTIFACT_COMPARISON_PROVIDER = {
id: "rea-artifact-comparison",
@@ -0,0 +1,46 @@
import {
createEvidence,
type Evidence,
type EvidenceObservation,
} from "../domain/evidence.js";
import type {
AnalyzeJavaScriptApplicationInput,
JavaScriptApplicationAnalysisResult,
} from "../domain/javascriptApplicationAnalysis.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { JAVASCRIPT_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
/** Create Evidence v2 for one deterministic local JavaScript application graph. */
export const createJavaScriptApplicationEvidence = (
input: AnalyzeJavaScriptApplicationInput,
result: JavaScriptApplicationAnalysisResult,
): Evidence =>
createEvidence(
{
path: result.input_path,
sha256: result.root_artifact_sha256,
format: result.format,
},
JAVASCRIPT_APPLICATION_PROVIDER,
{
predicateType: "rea.javascript-application-analysis/v1",
operation: "analyze_javascript_application",
parameters: parameters(input),
result: jsonValueSchema.parse(result),
rawResult: null,
confidence: "derived",
authority: "shipped-artifact",
environment: null,
limitations: result.limitations,
locations: [{ kind: "artifact-path", path: "artifact-root" }],
},
);
const parameters = (
input: AnalyzeJavaScriptApplicationInput,
): EvidenceObservation["parameters"] => ({
format: input.format,
approved: input.approved,
source_map_read_approved: input.source_map_read_approved,
limits: input.limits,
});
@@ -0,0 +1,109 @@
import { z } from "zod";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
analyzeJavaScriptApplicationInputSchema,
javascriptApplicationAnalysisResultSchema,
} from "../domain/javascriptApplicationAnalysis.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisInputError,
AnalysisProtocolError,
ArtifactOperationError,
PermissionRequiredError,
type AnalysisError,
} from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import type { Evidence } from "../domain/evidence.js";
import type { ExecutionOptions } from "./AnalysisProvider.js";
import { createJavaScriptApplicationEvidence } from "./JavaScriptApplicationEvidence.js";
import { reconstructJavaScriptArtifact } from "./JavaScriptArtifactReconstruction.js";
import type { PermissionAuthority } from "./PermissionAuthority.js";
const OPERATION = "analyze_javascript_application" as const;
/** Authorize and statically analyze one local JavaScript/Electron application. */
export const analyzeJavaScriptApplication = async (
authority: PermissionAuthority | undefined,
rawInput: unknown,
options: ExecutionOptions = {},
): Promise<Result<Evidence, AnalysisError>> => {
const parsed = analyzeJavaScriptApplicationInputSchema.safeParse(rawInput);
if (!parsed.success) return err(new AnalysisInputError(OPERATION));
if (authority === undefined)
return err(
new AnalysisCapabilityUnavailableError(
"rea-javascript-application",
OPERATION,
"JavaScript application permission policy is not configured",
),
);
const authorized = await authority.authorize(
{
capability: "investigation_input",
roots: [parsed.data.input_path],
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `${OPERATION}:${parsed.data.input_path}`,
},
"read",
);
if (!authorized.ok)
return err(
authorized.error instanceof PermissionRequiredError
? authorized.error
: new ArtifactOperationError(OPERATION, "path", {
logicalPath: parsed.data.input_path,
declaredSha256: null,
calculatedSha256: null,
unpacked: false,
}),
);
await options.progress?.report({
phase: "analyze_javascript_application",
completed: 0,
total: 1,
message: "Inventorying and parsing approved application artifacts",
});
try {
const reconstructed = await reconstructJavaScriptArtifact(
{
input_path: parsed.data.input_path,
format: parsed.data.format,
source_map_read_approved: parsed.data.source_map_read_approved,
limits: parsed.data.limits,
},
options.signal,
);
const { electron_summary: summary, ...application } = reconstructed;
const result = javascriptApplicationAnalysisResultSchema.parse({
schema_version: 1,
...application,
summary,
limitations: reconstructed.graph.limitations,
});
await options.progress?.report({
phase: "analyze_javascript_application",
completed: 1,
total: 1,
message: "Application graph and Electron boundaries reconstructed",
terminal: true,
});
return ok(createJavaScriptApplicationEvidence(parsed.data, result));
} catch (cause: unknown) {
if (cause instanceof ArtifactReaderFailure)
return err(
new ArtifactOperationError(OPERATION, cause.reason, cause.details),
);
if (cause instanceof z.ZodError)
return err(
new AnalysisProtocolError(
"JavaScript application analysis produced an invalid result",
{ cause },
),
);
return err(new ArtifactOperationError(OPERATION, "io"));
}
};
@@ -414,7 +414,13 @@ const findingCount = (analysis: JavaScriptStaticAnalysis): number =>
analysis.storage.length +
analysis.role_paths.length +
analysis.source_map_urls.length +
analysis.bundler_registrations.length;
analysis.bundler_registrations.length +
analysis.electron.browser_windows.length +
analysis.electron.context_bridge_apis.length +
analysis.electron.ipc.length +
analysis.electron.sender_validations.length +
analysis.electron.utility_processes.length +
analysis.electron.native_addon_bindings.length;
const rangeForOffsets = (
text: string,
@@ -27,6 +27,11 @@ import {
createJavaScriptArtifactRootNode,
} from "./JavaScriptArtifactGraphStructure.js";
import type { JavaScriptArtifactReconstructionInput } from "./JavaScriptArtifactReconstructionInput.js";
import { addElectronBoundaries } from "./ElectronBoundaryGraph.js";
import {
classifyElectronIpcPairings,
collectElectronIpcRecords,
} from "./ElectronBoundaryAnalysis.js";
/** Project bounded artifact and AST facts into JavaScript Application Graph v1. */
export const buildJavaScriptArtifactGraph = (
@@ -55,6 +60,7 @@ export const buildJavaScriptArtifactGraph = (
const packageRoots = addJavaScriptPackageNodes(context);
addJavaScriptBundlerNodes(context);
addJavaScriptStaticFindings(context);
addElectronBoundaries(context);
addJavaScriptHtmlRoles(context);
addJavaScriptSourceMapOriginals(context);
const coverage = graphCoverage(context);
@@ -82,11 +88,16 @@ const graphCoverage = (context: JavaScriptArtifactGraphContext) => {
const malformedStructuredData =
context.analysis.packages.some(({ status }) => status !== "included") ||
context.analysis.source_maps.some(({ status }) => status === "invalid");
const partialJavaScript = context.analysis.files.some(
({ javascript }) =>
javascript !== null && javascript.parse_status === "partial",
);
const unknownGap =
context.analysis.parse_failures > 0 ||
context.fileSet.invalid_utf8_files > 0 ||
sourceMapPolicyGap ||
malformedStructuredData;
malformedStructuredData ||
partialJavaScript;
if (context.analysis.truncated_scopes > 0)
return partialReconstructionCoverage(
reconstructionLimits(context.input),
@@ -111,21 +122,69 @@ const graphCoverage = (context: JavaScriptArtifactGraphContext) => {
const graphLimitations = (
context: JavaScriptArtifactGraphContext,
coverage: "complete" | "partial" | "unknown" | "unavailable",
): string[] => [
...context.analysis.limitations,
"Webpack/Rspack factories were recovered from AST literals; REA did not invoke push handlers or bundle bootstrap code.",
"Static imports, entrypoints, workers, endpoints, and storage relationships do not prove runtime execution.",
...(context.accumulator.omittedObservations() === 0
? []
: [
"Repeated content identities exceeded the per-node observation bound; containment edges still preserve inventoried paths.",
]),
...(coverage === "complete"
? []
: [
"Graph coverage is incomplete; unavailable facts remain explicit and must not be read as absence.",
]),
];
): string[] => {
const ipc = collectElectronIpcRecords(context.analysis);
const pairings = classifyElectronIpcPairings(ipc);
const electronFindings = context.analysis.files.reduce(
(count, { javascript }) =>
count +
(javascript === null
? 0
: javascript.electron.browser_windows.length +
javascript.electron.context_bridge_apis.length +
javascript.electron.ipc.length +
javascript.electron.sender_validations.length +
javascript.electron.utility_processes.length +
javascript.electron.native_addon_bindings.length),
0,
);
return [
...context.analysis.limitations,
"Webpack/Rspack factories were recovered from AST literals; REA did not invoke push handlers or bundle bootstrap code.",
"Static imports, entrypoints, workers, endpoints, and storage relationships do not prove runtime execution.",
...(electronFindings === 0
? []
: [
"Electron relationships are derived from inert syntax; runtime registration, reachability, defaults, and enforcement remain unproven.",
]),
...(ipc.some(({ finding }) => finding.channel === null)
? [
"Dynamic IPC channel expressions remain unresolved and are never paired by textual similarity.",
]
: []),
...(pairings.some(({ status }) => status === "ambiguous")
? [
"Some literal IPC channels have multiple compatible main handlers; ambiguous calls are not paired to any handler.",
]
: []),
...(context.analysis.files.some(
({ javascript }) =>
(javascript?.electron.sender_validations.length ?? 0) > 0,
)
? [
"Sender, frame, URL, and origin checks are observations only; REA does not claim that they enforce a complete authorization policy.",
]
: []),
...(context.analysis.files.some(
({ javascript }) =>
(javascript?.electron.native_addon_bindings.length ?? 0) > 0,
)
? [
"Native member names are requested by JavaScript syntax and are not verified binary exports in this workflow.",
]
: []),
...(context.accumulator.omittedObservations() === 0
? []
: [
"Repeated content identities exceeded the per-node observation bound; containment edges still preserve inventoried paths.",
]),
...(coverage === "complete"
? []
: [
"Graph coverage is incomplete; unavailable facts remain explicit and must not be read as absence.",
]),
];
};
const reconstructionLimits = (input: JavaScriptArtifactReconstructionInput) => [
{
@@ -42,20 +42,30 @@ export const artifactObservationEvidence = (
/** Exact AST syntax evidence with an actionable source range. */
export const astObservationEvidence = (
input: EvidenceInput & { readonly range: JavaScriptSourceRange },
): ApplicationGraphEvidence => ({
authority: "ast-static-analysis",
state: "observed",
confidence: "exact",
artifact: artifactReference(input.sha256),
location: {
available: true,
value: { kind: "source-range", source: input.path, ...input.range },
},
extractor: { ...EXTRACTOR, operation: input.operation },
coverage: input.coverage,
limitations: [...(input.limitations ?? [])],
evidence_ids: [],
});
): ApplicationGraphEvidence => {
const limitations = [
...(input.limitations ?? []),
...(input.coverage.status === "complete"
? []
: [
"AST coverage is incomplete; omitted or dynamic facts must not be interpreted as absence.",
]),
];
return {
authority: "ast-static-analysis",
state: "observed",
confidence: "exact",
artifact: artifactReference(input.sha256),
location: {
available: true,
value: { kind: "source-range", source: input.path, ...input.range },
},
extractor: { ...EXTRACTOR, operation: input.operation },
coverage: input.coverage,
limitations,
evidence_ids: [],
};
};
/** Explicit static relationship inference; never promoted to observation. */
export const staticInferenceEvidence = (
@@ -8,6 +8,7 @@ import {
} from "../artifacts/ArtifactReader.js";
import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
import type { JavaScriptApplicationGraph } from "../domain/javascriptApplicationGraph.js";
import type { ElectronBoundarySummary } from "../domain/javascriptApplicationAnalysis.js";
import { analyzeJavaScriptArtifactFiles } from "./JavaScriptArtifactAnalysis.js";
import { readJavaScriptArtifactFiles } from "./JavaScriptArtifactFiles.js";
import { buildJavaScriptArtifactGraph } from "./JavaScriptArtifactGraphBuilder.js";
@@ -17,14 +18,17 @@ import {
type JavaScriptArtifactReconstructionInput,
} from "./JavaScriptArtifactReconstructionInput.js";
import { scanCanonicalArtifactInventory } from "./ArtifactInventory.js";
import { summarizeElectronBoundaries } from "./ElectronBoundaryAnalysis.js";
/** Application-layer result retaining local diagnostics outside the canonical graph. */
export interface JavaScriptArtifactReconstructionResult {
readonly input_path: string;
readonly format: "asar" | "directory";
readonly root_artifact_sha256: string;
readonly inventory_manifest_id: string;
readonly inventory_graph_sha256: string;
readonly graph: JavaScriptApplicationGraph;
readonly electron_summary: ElectronBoundarySummary;
readonly statistics: {
readonly relevant_files: number;
readonly nested_asar_containers: number;
@@ -84,9 +88,11 @@ export const reconstructJavaScriptArtifact = async (
return {
input_path: path,
format,
root_artifact_sha256: snapshot.manifest.root_sha256,
inventory_manifest_id: snapshot.manifest.manifest_id,
inventory_graph_sha256: snapshot.manifest.graph_sha256,
graph,
electron_summary: summarizeElectronBoundaries(analysis),
statistics: {
relevant_files: files.files.length,
nested_asar_containers: files.containers.length,
@@ -1,101 +1,19 @@
import { z } from "zod";
import type { ArtifactLimits } from "../artifacts/ArtifactReader.js";
const MAX_GRAPH_NODES = 100_000;
const MAX_GRAPH_EDGES = 200_000;
const reconstructionLimitsSchema = z
.strictObject({
max_entries: z.number().int().min(1).max(1_000_000).default(8_000),
max_total_artifact_bytes: z
.number()
.int()
.min(1)
.max(Number.MAX_SAFE_INTEGER)
.default(512 * 1_024 * 1_024),
max_artifact_entry_bytes: z
.number()
.int()
.min(1)
.max(Number.MAX_SAFE_INTEGER)
.default(128 * 1_024 * 1_024),
max_compression_ratio: z.number().min(1).max(100_000).default(1_000),
max_depth: z.number().int().min(1).max(100).default(64),
max_path_bytes: z.number().int().min(1).max(65_535).default(4_096),
max_text_files: z.number().int().min(1).max(100_000).default(5_000),
max_total_text_bytes: z
.number()
.int()
.min(1)
.max(512 * 1_024 * 1_024)
.default(128 * 1_024 * 1_024),
max_text_file_bytes: z
.number()
.int()
.min(1)
.max(64 * 1_024 * 1_024)
.default(8 * 1_024 * 1_024),
max_ast_nodes: z.number().int().min(1).max(20_000_000).default(2_000_000),
max_findings: z.number().int().min(1).max(200_000).default(10_000),
max_modules: z.number().int().min(1).max(100_000).default(20_000),
max_source_map_sources: z.number().int().min(1).max(100_000).default(5_000),
max_parse_milliseconds: z
.number()
.int()
.min(1)
.max(300_000)
.default(30_000),
})
.superRefine((limits, context) => {
const projectedNodes =
7 * limits.max_entries +
limits.max_findings +
limits.max_modules +
limits.max_source_map_sources +
1;
if (projectedNodes > MAX_GRAPH_NODES)
context.addIssue({
code: "custom",
path: ["max_entries"],
message:
"Combined reconstruction limits can exceed the 100000-node graph contract",
});
const projectedEdges =
9 * limits.max_entries +
5 * limits.max_findings +
limits.max_modules +
limits.max_source_map_sources;
if (projectedEdges > MAX_GRAPH_EDGES)
context.addIssue({
code: "custom",
path: ["max_entries"],
message:
"Combined reconstruction limits can exceed the 200000-edge graph contract",
});
});
import {
JAVASCRIPT_APPLICATION_ANALYSIS_DEFAULT_LIMITS,
javascriptApplicationAnalysisLimitsSchema,
} from "../domain/javascriptApplicationAnalysis.js";
/** Local ASAR/directory reconstruction request with explicit source-map authority. */
export const javascriptArtifactReconstructionInputSchema = z.strictObject({
input_path: z.string().min(1).max(16_384),
format: z.enum(["auto", "asar", "directory"]).default("auto"),
source_map_read_approved: z.boolean().default(false),
limits: reconstructionLimitsSchema.default({
max_entries: 8_000,
max_total_artifact_bytes: 512 * 1_024 * 1_024,
max_artifact_entry_bytes: 128 * 1_024 * 1_024,
max_compression_ratio: 1_000,
max_depth: 64,
max_path_bytes: 4_096,
max_text_files: 5_000,
max_total_text_bytes: 128 * 1_024 * 1_024,
max_text_file_bytes: 8 * 1_024 * 1_024,
max_ast_nodes: 2_000_000,
max_findings: 10_000,
max_modules: 20_000,
max_source_map_sources: 5_000,
max_parse_milliseconds: 30_000,
}),
limits: javascriptApplicationAnalysisLimitsSchema.default(
JAVASCRIPT_APPLICATION_ANALYSIS_DEFAULT_LIMITS,
),
});
/** Parsed bounded reconstruction request. */