feat(electron): map static process and IPC boundaries
This commit is contained in:
@@ -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;
|
||||
@@ -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;
|
||||
@@ -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. */
|
||||
|
||||
Reference in New Issue
Block a user