refactor(mcp): make analysis states unrepresentable (#468)
* refactor(config): parse capability settings into exact states * refactor(runtime): encode replay and process outcomes exactly * refactor: make analysis states unrepresentable * refactor(mcp): register canonical schemas with SDK * fix: preserve capability and catalog invariants * fix(build): remove stale compiled modules * fix(replay): update real verifier policy dependency * fix(package): verify the complete MCP catalog * fix(test): supply complete replay reload policy * refactor(contracts): centralize output schema lookup * refactor(mcp): delegate protocol boundaries to SDK * fix(browser): approve real source capture * fix(mcp): preserve catalog guidance
This commit is contained in:
+184
-151
@@ -5,50 +5,65 @@ import {
|
||||
createRequestStateCodec,
|
||||
McpServer,
|
||||
PROTOCOL_VERSION_META_KEY,
|
||||
type ServerContext,
|
||||
} from "@modelcontextprotocol/server";
|
||||
|
||||
import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
|
||||
import type { BinarySessionPort } from "../application/BinarySession.js";
|
||||
import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
import { silentLogger, type Logger } from "../logger.js";
|
||||
import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
|
||||
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
|
||||
import { registerGuidedPrompts } from "./registerPrompts.js";
|
||||
import { registerEvidenceResources } from "./registerEvidenceResources.js";
|
||||
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
|
||||
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
|
||||
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
|
||||
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
|
||||
import type { ElectronActiveObservationPort } from "../application/ElectronActiveObservationPort.js";
|
||||
import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
|
||||
import type {
|
||||
JavaScriptReplayHost,
|
||||
JavaScriptReplayPolicy,
|
||||
JavaScriptReplayRunner,
|
||||
} from "../application/JavaScriptReplayPlanning.js";
|
||||
import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js";
|
||||
import type { ManagedRuntimePolicy } from "../application/ManagedRuntimeCorrelationService.js";
|
||||
import { MANAGED_RUNTIME_DISABLED } from "../application/ManagedRuntimeCorrelationService.js";
|
||||
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
|
||||
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
|
||||
import type { ProcessExecutionPolicy } from "../domain/processCapture.js";
|
||||
import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
import { silentLogger, type Logger } from "../logger.js";
|
||||
import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
|
||||
import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
|
||||
import { mcpClientMetadata, mcpEnvelopeValue } from "./mcpClientMetadata.js";
|
||||
import {
|
||||
PROCESS_CAPTURE_ELICITATION_POLICY,
|
||||
type ProcessCaptureElicitationState,
|
||||
} from "./ProcessCaptureElicitation.js";
|
||||
import { registerApplicationTools } from "./registerApplicationTools.js";
|
||||
import { registerArtifactTools } from "./registerArtifactTools.js";
|
||||
import { registerBrowserScenarioTool } from "./registerBrowserScenarioTool.js";
|
||||
import { registerBrowserTools } from "./registerBrowserTools.js";
|
||||
import { registerElectronTools } from "./registerElectronTools.js";
|
||||
import { registerEnhancedTools } from "./registerEnhancedTools.js";
|
||||
import { registerEvidenceResources } from "./registerEvidenceResources.js";
|
||||
import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";
|
||||
import { registerManagedTools } from "./registerManagedTools.js";
|
||||
import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
|
||||
import { registerNativeTools } from "./registerNativeTools.js";
|
||||
import { registerOfficialTools } from "./registerOfficialTools.js";
|
||||
import { registerGuidedPrompts } from "./registerPrompts.js";
|
||||
import { registerSessionTools } from "./registerSessionTools.js";
|
||||
import type { SessionAvailability } from "./sessionAvailabilityPolicy.js";
|
||||
import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
|
||||
import {
|
||||
DENY_EVIDENCE_FILE_POLICY,
|
||||
DENY_PROCESS_POLICY,
|
||||
} from "./sessionToolPolicies.js";
|
||||
import { installDynamicToolAvailability } from "./DynamicToolAvailability.js";
|
||||
|
||||
const TARGET_FREE_INSTRUCTIONS =
|
||||
"ASAR/JavaScript -> analyze_javascript_application; archive/package -> open_binary(path), then inspect_artifact/inventory_artifact (active target); managed PE/CLI -> inspect_managed_artifact; browser/Electron -> list_browser_targets/list_electron_targets; approved -> capture_browser_scenario/capture_electron_scenario; Node/Electron Inspector -> list_javascript_runtime_targets; native binary/database -> open_binary, then binary_overview. Start with binary_session; use tools/list; capabilities via binary_session. Use summaries, cite Evidence IDs; Never repeat identical analysis or read full Evidence.";
|
||||
|
||||
const ACTIVE_TARGET_INSTRUCTIONS =
|
||||
"REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
|
||||
import type {
|
||||
JavaScriptReplayHost,
|
||||
JavaScriptReplayPolicy,
|
||||
JavaScriptReplayRunner,
|
||||
} from "../application/JavaScriptReplayPlanning.js";
|
||||
import type { ManagedRuntimePolicy } from "../application/ManagedRuntimeCorrelationService.js";
|
||||
import {
|
||||
PROCESS_CAPTURE_ELICITATION_POLICY,
|
||||
type ProcessCaptureElicitationState,
|
||||
} from "./ProcessCaptureElicitation.js";
|
||||
import { LazyToolCatalog } from "./LazyToolCatalog.js";
|
||||
|
||||
export interface CreateServerOptions {
|
||||
readonly logger?: Logger;
|
||||
readonly processPolicy?: ProcessExecutionPolicy;
|
||||
readonly processPolicy?: () => ProcessExecutionPolicy;
|
||||
readonly evidenceFilePolicy?: EvidenceFilePolicy;
|
||||
readonly investigationInputRoots?: readonly string[];
|
||||
readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy;
|
||||
@@ -59,18 +74,11 @@ export interface CreateServerOptions {
|
||||
readonly electronActiveObservation?: ElectronActiveObservationPort;
|
||||
readonly javascriptRuntimeObservation?: JavaScriptRuntimeObservationPort;
|
||||
readonly artifactIntegrityContinueEnabled?: () => boolean;
|
||||
readonly javascriptReplayPolicy?: JavaScriptReplayPolicy;
|
||||
readonly javascriptReplayPolicy?: () => JavaScriptReplayPolicy;
|
||||
readonly javascriptReplayHost?: JavaScriptReplayHost;
|
||||
readonly javascriptReplayRunner?: JavaScriptReplayRunner;
|
||||
readonly managedRuntimePolicy?: ManagedRuntimePolicy;
|
||||
readonly managedRuntimePolicy?: () => ManagedRuntimePolicy;
|
||||
readonly availabilityPolicy?: () => SessionAvailability;
|
||||
readonly loadOptionalProviders?: () => Promise<{
|
||||
readonly browserObservation: BrowserObservationPort;
|
||||
readonly browserScenarioCapture: BrowserScenarioCapturePort;
|
||||
readonly electronObservation: ElectronObservationPort;
|
||||
readonly electronActiveObservation: ElectronActiveObservationPort;
|
||||
readonly javascriptRuntimeObservation: JavaScriptRuntimeObservationPort;
|
||||
}>;
|
||||
}
|
||||
|
||||
const installSessionToolAvailability = (
|
||||
@@ -80,7 +88,7 @@ const installSessionToolAvailability = (
|
||||
) => {
|
||||
if (session === undefined) return undefined;
|
||||
const policy = sessionAvailabilityPolicy(options.availabilityPolicy, {
|
||||
processPolicy: options.processPolicy ?? DENY_PROCESS_POLICY,
|
||||
processPolicy: options.processPolicy?.() ?? DENY_PROCESS_POLICY,
|
||||
evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
|
||||
investigationInputRoots: options.investigationInputRoots ?? [],
|
||||
optionalFeatures: {
|
||||
@@ -92,13 +100,14 @@ const installSessionToolAvailability = (
|
||||
options.permissionAuthority !== undefined,
|
||||
v8InspectorObservationEnabled:
|
||||
options.javascriptRuntimeObservation !== undefined,
|
||||
javascriptReplayEnabled: options.javascriptReplayPolicy?.enabled ?? false,
|
||||
managedRuntimeEnabled: options.managedRuntimePolicy?.enabled ?? false,
|
||||
javascriptReplayEnabled:
|
||||
options.javascriptReplayPolicy?.().status === "enabled",
|
||||
managedRuntimeEnabled:
|
||||
options.managedRuntimePolicy?.().status === "enabled",
|
||||
},
|
||||
});
|
||||
return {
|
||||
policy,
|
||||
controller: installDynamicToolAvailability(server, session, policy),
|
||||
};
|
||||
};
|
||||
|
||||
@@ -107,9 +116,7 @@ type ProcessCaptureElicitation = {
|
||||
typeof createRequestStateCodec<ProcessCaptureElicitationState>
|
||||
>;
|
||||
readonly supported: (context: {
|
||||
readonly mcpReq: {
|
||||
readonly envelope?: Readonly<Record<string, unknown>>;
|
||||
};
|
||||
readonly mcpReq: Pick<ServerContext["mcpReq"], "envelope">;
|
||||
}) => boolean;
|
||||
readonly now: typeof Date.now;
|
||||
readonly consumedNonces: Map<string, number>;
|
||||
@@ -121,8 +128,11 @@ const createProcessCaptureElicitation = (
|
||||
stateCodec,
|
||||
supported: (context) => {
|
||||
const envelope = context.mcpReq.envelope;
|
||||
const version = envelope?.[PROTOCOL_VERSION_META_KEY];
|
||||
const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
|
||||
const version = mcpEnvelopeValue(envelope, PROTOCOL_VERSION_META_KEY);
|
||||
const capabilities = mcpEnvelopeValue(
|
||||
envelope,
|
||||
CLIENT_CAPABILITIES_META_KEY,
|
||||
);
|
||||
return (
|
||||
typeof version === "string" &&
|
||||
PROCESS_CAPTURE_ELICITATION_POLICY.protocolVersions.some(
|
||||
@@ -137,93 +147,6 @@ const createProcessCaptureElicitation = (
|
||||
consumedNonces: new Map<string, number>(),
|
||||
});
|
||||
|
||||
const createOptionalProviderLoader = (options: CreateServerOptions) => {
|
||||
let optionalProviders:
|
||||
| ReturnType<NonNullable<CreateServerOptions["loadOptionalProviders"]>>
|
||||
| undefined;
|
||||
return () => {
|
||||
optionalProviders ??= options
|
||||
.loadOptionalProviders?.()
|
||||
.catch((cause: unknown) => {
|
||||
optionalProviders = undefined;
|
||||
throw cause;
|
||||
});
|
||||
return optionalProviders;
|
||||
};
|
||||
};
|
||||
|
||||
const createLazyToolCatalog = ({
|
||||
server,
|
||||
analysis,
|
||||
session,
|
||||
options,
|
||||
toolLogger,
|
||||
permissionAuthority,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
availabilityPolicy,
|
||||
startedAt,
|
||||
processCaptureElicitation,
|
||||
}: {
|
||||
readonly server: McpServer;
|
||||
readonly analysis: AnalysisOperationPort;
|
||||
readonly session: BinarySessionPort | undefined;
|
||||
readonly options: CreateServerOptions;
|
||||
readonly toolLogger: Logger;
|
||||
readonly permissionAuthority: PermissionAuthority | undefined;
|
||||
readonly activeTarget: ReturnType<
|
||||
typeof createSessionRecorders
|
||||
>["activeTarget"];
|
||||
readonly recordEvidence: ReturnType<
|
||||
typeof createSessionRecorders
|
||||
>["recordEvidence"];
|
||||
readonly recordEvidenceWithUnknown: ReturnType<
|
||||
typeof createSessionRecorders
|
||||
>["recordEvidenceWithUnknown"];
|
||||
readonly availabilityPolicy: CreateServerOptions["availabilityPolicy"];
|
||||
readonly startedAt: string;
|
||||
readonly processCaptureElicitation: ProcessCaptureElicitation;
|
||||
}): LazyToolCatalog => {
|
||||
const loadOptionalProviders = createOptionalProviderLoader(options);
|
||||
return new LazyToolCatalog(
|
||||
server,
|
||||
async (kind) => {
|
||||
const needsObservationProviders =
|
||||
kind === "browser-provider" ||
|
||||
kind === "electron-provider" ||
|
||||
kind === "runtime-provider";
|
||||
const [{ hydrateServerToolFamily }, loadedOptionalProviders] =
|
||||
await Promise.all([
|
||||
import("./hydrateServerTools.js"),
|
||||
needsObservationProviders ? loadOptionalProviders() : undefined,
|
||||
]);
|
||||
const hydratedOptions =
|
||||
loadedOptionalProviders === undefined
|
||||
? options
|
||||
: { ...options, ...loadedOptionalProviders };
|
||||
await hydrateServerToolFamily({
|
||||
kind,
|
||||
server,
|
||||
analysis,
|
||||
session,
|
||||
options: hydratedOptions,
|
||||
context: {
|
||||
logger: toolLogger,
|
||||
permissionAuthority,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
availabilityPolicy,
|
||||
startedAt,
|
||||
processCaptureElicitation,
|
||||
},
|
||||
});
|
||||
},
|
||||
session !== undefined,
|
||||
);
|
||||
};
|
||||
|
||||
const createMcpServer = (
|
||||
processCaptureStateCodec: ProcessCaptureElicitation["stateCodec"],
|
||||
session: BinarySessionPort | undefined,
|
||||
@@ -235,8 +158,7 @@ const createMcpServer = (
|
||||
},
|
||||
{
|
||||
capabilities: {
|
||||
tools: { listChanged: true },
|
||||
resources: { listChanged: true, subscribe: true },
|
||||
resources: { subscribe: true },
|
||||
},
|
||||
inputRequired: {
|
||||
maxRounds: 3,
|
||||
@@ -270,13 +192,10 @@ export const createServer = (
|
||||
ttlSeconds: PROCESS_CAPTURE_ELICITATION_POLICY.stateTtlSeconds,
|
||||
});
|
||||
const server = createMcpServer(processCaptureStateCodec, session);
|
||||
const dynamicTools = installSessionToolAvailability(server, session, options);
|
||||
const availability = installSessionToolAvailability(server, session, options);
|
||||
server.server.onclose = () => {
|
||||
permissionAuthority?.clearSessionGrants();
|
||||
};
|
||||
if (dynamicTools !== undefined)
|
||||
server.server.oninitialized = () => server.sendToolListChanged();
|
||||
session?.onAvailabilityChanged?.(() => server.sendToolListChanged());
|
||||
registerServerIdentityResource(server, startedAt);
|
||||
const toolLogger = logger.child({ layer: "server" });
|
||||
const { activeTarget, recordEvidence, recordEvidenceWithUnknown } =
|
||||
@@ -284,34 +203,38 @@ export const createServer = (
|
||||
const processCaptureElicitation = createProcessCaptureElicitation(
|
||||
processCaptureStateCodec,
|
||||
);
|
||||
const lazyTools = createLazyToolCatalog({
|
||||
const toolContext: ServerToolContext = {
|
||||
server,
|
||||
analysis,
|
||||
session,
|
||||
options,
|
||||
toolLogger,
|
||||
logger: toolLogger,
|
||||
permissionAuthority,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
availabilityPolicy: dynamicTools?.policy,
|
||||
startedAt,
|
||||
processCaptureElicitation,
|
||||
});
|
||||
lazyTools.register();
|
||||
};
|
||||
registerBinaryAnalysisTools(toolContext);
|
||||
registerObservationTools(toolContext);
|
||||
registerGuidedPrompts(server, analysis, session);
|
||||
if (session !== undefined) {
|
||||
registerEvidenceResources(server, session);
|
||||
registerSessionTools(server, session, toolLogger, {
|
||||
...options,
|
||||
...(availability === undefined
|
||||
? {}
|
||||
: { availabilityPolicy: availability.policy }),
|
||||
...(permissionAuthority === undefined ? {} : { permissionAuthority }),
|
||||
startedAt,
|
||||
processCaptureElicitation,
|
||||
});
|
||||
}
|
||||
dynamicTools?.controller.synchronize();
|
||||
const close = server.close.bind(server);
|
||||
server.close = async () => {
|
||||
await lazyTools.close();
|
||||
await close();
|
||||
};
|
||||
return server;
|
||||
};
|
||||
|
||||
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
||||
typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
|
||||
const createSessionRecorders = (
|
||||
server: McpServer,
|
||||
session: BinarySessionPort | undefined,
|
||||
@@ -337,6 +260,120 @@ const createSessionRecorders = (
|
||||
},
|
||||
});
|
||||
|
||||
interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {
|
||||
readonly server: McpServer;
|
||||
readonly analysis: AnalysisOperationPort;
|
||||
readonly session: BinarySessionPort | undefined;
|
||||
readonly options: CreateServerOptions;
|
||||
readonly logger: Logger;
|
||||
readonly permissionAuthority: PermissionAuthority | undefined;
|
||||
}
|
||||
|
||||
const registerBinaryAnalysisTools = ({
|
||||
server,
|
||||
analysis,
|
||||
session,
|
||||
options,
|
||||
logger,
|
||||
permissionAuthority,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
}: ServerToolContext): void => {
|
||||
const recordUnknown =
|
||||
session === undefined
|
||||
? undefined
|
||||
: (input: Parameters<typeof session.recordUnknown>[0]) =>
|
||||
session.recordUnknown(input);
|
||||
const analysisOptions = {
|
||||
logger,
|
||||
activeTarget,
|
||||
recordEvidence,
|
||||
recordUnknown,
|
||||
};
|
||||
registerOfficialTools(server, analysis, analysisOptions);
|
||||
registerEnhancedTools(server, analysis, {
|
||||
...analysisOptions,
|
||||
analysisProfile:
|
||||
session === undefined ? undefined : () => session.analysisProfile(),
|
||||
});
|
||||
const evidenceOptions = { logger, activeTarget, recordEvidence };
|
||||
registerNativeTools(server, analysis, evidenceOptions);
|
||||
registerArtifactTools(server, analysis, {
|
||||
...evidenceOptions,
|
||||
...(permissionAuthority === undefined ? {} : { permissionAuthority }),
|
||||
});
|
||||
registerManagedTools(server, analysis, {
|
||||
...evidenceOptions,
|
||||
session,
|
||||
});
|
||||
if (session !== undefined)
|
||||
registerManagedWorkflowTools(server, {
|
||||
logger,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
session,
|
||||
runtime: {
|
||||
policy:
|
||||
options.managedRuntimePolicy ?? (() => MANAGED_RUNTIME_DISABLED),
|
||||
authority: permissionAuthority,
|
||||
},
|
||||
});
|
||||
};
|
||||
|
||||
const registerObservationTools = ({
|
||||
server,
|
||||
session,
|
||||
options,
|
||||
logger,
|
||||
permissionAuthority,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
}: ServerToolContext): void => {
|
||||
const common = { logger, permissionAuthority, recordEvidence };
|
||||
registerBrowserTools(server, {
|
||||
...common,
|
||||
browser: options.browserObservation,
|
||||
});
|
||||
registerBrowserScenarioTool(server, {
|
||||
...common,
|
||||
provider: options.browserScenarioCapture,
|
||||
});
|
||||
registerElectronTools(server, {
|
||||
...common,
|
||||
electron: options.electronObservation,
|
||||
electronActive: options.electronActiveObservation,
|
||||
});
|
||||
registerJavaScriptRuntimeObservationTools(server, {
|
||||
...common,
|
||||
runtime: options.javascriptRuntimeObservation,
|
||||
});
|
||||
registerApplicationTools(server, {
|
||||
logger,
|
||||
recordEvidence,
|
||||
recordEvidenceWithUnknown,
|
||||
evidenceLookup:
|
||||
session === undefined
|
||||
? undefined
|
||||
: (evidenceId) => session.evidenceById(evidenceId),
|
||||
evidenceFilePolicy: options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY,
|
||||
permissionAuthority,
|
||||
retainCoverageWorkspace:
|
||||
session === undefined
|
||||
? undefined
|
||||
: (workspace) =>
|
||||
session.retainReconstructionCoverageWorkspace(workspace),
|
||||
replay: {
|
||||
policy:
|
||||
options.javascriptReplayPolicy ?? (() => ({ status: "disabled" })),
|
||||
host: options.javascriptReplayHost ?? new SystemJavaScriptReplayHost(),
|
||||
runner:
|
||||
options.javascriptReplayRunner ?? new LinuxJavaScriptReplayRunner(),
|
||||
authority: permissionAuthority,
|
||||
},
|
||||
});
|
||||
};
|
||||
|
||||
const registerServerIdentityResource = (
|
||||
server: McpServer,
|
||||
startedAt: string,
|
||||
@@ -349,10 +386,9 @@ const registerServerIdentityResource = (
|
||||
description: "Live package, SDK, protocol, and catalog identity.",
|
||||
mimeType: "application/json",
|
||||
},
|
||||
async (uri) => {
|
||||
async (uri, context) => {
|
||||
const { createServerIdentity } = await import("../serverIdentity.js");
|
||||
const client = server.server.getClientVersion();
|
||||
const protocolVersion = server.server.getNegotiatedProtocolVersion();
|
||||
const { client, protocolVersion } = mcpClientMetadata(context);
|
||||
return {
|
||||
contents: [
|
||||
{
|
||||
@@ -373,6 +409,3 @@ const registerServerIdentityResource = (
|
||||
},
|
||||
);
|
||||
};
|
||||
|
||||
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
||||
typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
|
||||
Reference in New Issue
Block a user