From d1675822f660c6d8da58af9787440662446ddd14 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:52:56 +0800 Subject: [PATCH] refactor(capabilities): declare standalone and host-gated availability on the contract (#11270) Contracts declare availability: "standalone" or { host: }, and CapabilityInventory interprets the declaration once through one feature table, replacing 39 per-name branches. HOST_RESTRICTED_FEATURES moves to the contracts layer. --- src/application/CapabilityInventory.test.ts | 57 ++++ src/application/CapabilityInventory.ts | 309 ++++++++---------- .../apkSignature/apkSignatureToolContracts.ts | 1 + .../captures/captureToolContracts.ts | 2 + .../desktopApplicationToolContracts.ts | 1 + src/contracts/erlang/beamToolContracts.ts | 1 + src/contracts/evm/evmToolContracts.ts | 1 + .../firmware/firmwareToolContracts.ts | 2 + src/contracts/gdbToolContracts.ts | 1 + src/contracts/go/goToolContracts.ts | 1 + src/contracts/gpu/gpuToolContracts.ts | 1 + src/contracts/il2cpp/il2cppToolContracts.ts | 1 + .../javascript/electronToolContracts.ts | 3 + .../javascriptRecoveryToolContracts.ts | 1 + src/contracts/model/modelToolContracts.ts | 1 + .../native/binaryDiagnosticsToolContracts.ts | 17 + src/contracts/pcap/pcapToolContracts.ts | 1 + .../python/pythonPycToolContracts.ts | 1 + src/contracts/releaseExposureToolContracts.ts | 1 + src/contracts/rizinDebugToolContracts.ts | 1 + src/contracts/rust/rustToolContracts.ts | 1 + src/contracts/signals/signalToolContracts.ts | 2 + src/contracts/toolAvailability.ts | 32 ++ src/contracts/toolContractTypes.ts | 3 + src/contracts/v8/v8CodeCacheToolContracts.ts | 1 + src/contracts/webRuntimeToolContracts.ts | 2 + src/server/sessionAvailabilityPolicy.ts | 4 +- 27 files changed, 274 insertions(+), 175 deletions(-) create mode 100644 src/contracts/toolAvailability.ts diff --git a/src/application/CapabilityInventory.test.ts b/src/application/CapabilityInventory.test.ts index 3e3cd98a46..6b406b4bff 100644 --- a/src/application/CapabilityInventory.test.ts +++ b/src/application/CapabilityInventory.test.ts @@ -1216,3 +1216,60 @@ describe("summary tool availability", () => { ); }); }); + +describe("declared contract availability", () => { + const declared = TOOL_CONTRACTS.flatMap((contract) => + "availability" in contract && contract.availability !== undefined + ? [{ name: contract.name, availability: contract.availability }] + : [], + ); + const failed = { providerId: "fixture", reason: "load failed" }; + const inventory = (policy: Parameters[1]) => + new Map( + buildCapabilityInventory({ open: false, capabilities: [] }, policy).map( + (tool) => [tool.name, tool], + ), + ); + + it("keeps standalone workflows available without providers, a target or configuration", () => { + const tools = inventory({ + processCaptureEnabled: false, + optionalProviderLoadFailures: { + browserObservation: failed, + browserScenarioCapture: failed, + electronObservation: failed, + electronActiveObservation: failed, + javascriptRuntimeObservation: failed, + fridaInstrumentation: failed, + }, + }); + const standalone = declared.filter( + ({ availability }) => availability === "standalone", + ); + expect(standalone.length).toBeGreaterThan(0); + for (const { name } of standalone) + expect(tools.get(name), name).toMatchObject({ + available: true, + reason: "available", + }); + }); + + it("refuses each host-restricted declaration on an unsupported host before its configuration", () => { + const hosted = declared.flatMap(({ name, availability }) => + availability === "standalone" ? [] : [{ name, ...availability }], + ); + expect(hosted.length).toBeGreaterThan(0); + const tools = inventory({ + processCaptureEnabled: true, + hostUnsupported: Object.fromEntries( + hosted.map(({ host }) => [host, true]), + ), + }); + for (const { name } of hosted) + expect(tools.get(name), name).toMatchObject({ + available: false, + reason: "unsupported_host", + remediation: expect.any(String), + }); + }); +}); diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts index 1ca915e89a..31025c2bcb 100644 --- a/src/application/CapabilityInventory.ts +++ b/src/application/CapabilityInventory.ts @@ -40,6 +40,10 @@ import { type ToolEffects, } from "../contracts/toolEffects.js"; import type { ToolKind } from "../contracts/toolContractTypes.js"; +import type { + HostRestrictedFeature, + ToolAvailabilityDeclaration, +} from "../contracts/toolAvailability.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { isMachOFormat } from "../domain/binaryTargetTypes.js"; import type { @@ -78,21 +82,6 @@ type ToolAvailabilityReason = "available" | ToolUnavailabilityReason; type ProviderDescriptor = ReturnType[number]; type UnavailableDescriptor = Extract; -/** Optional integrations whose verified hosts exclude some platforms. */ -export const HOST_RESTRICTED_FEATURES = [ - "packetCapture", - "pcapCapture", - "signalRecording", - "evmInterface", - "binaryLayout", - "recordedCrash", - "firmwareInspection", - "firmwareExtraction", - "javascriptRecovery", - "persistentDebugger", -] as const; -export type HostRestrictedFeature = (typeof HOST_RESTRICTED_FEATURES)[number]; - export type AvailabilityPolicy = { /** Integrations this host cannot run, whatever their configuration. */ readonly hostUnsupported?: Readonly< @@ -152,6 +141,7 @@ export const MULTI_MODE_REMEDIATION = type AvailabilityContext = { readonly name: string; readonly kind: ToolKind; + readonly declared: ToolAvailabilityDeclaration | undefined; readonly targetOpen: boolean; readonly cleanupRetry: AnalysisCleanupRetry | undefined; readonly resourceSession: boolean; @@ -344,6 +334,7 @@ export const buildCapabilityInventory = ( const availability = availabilityFor({ name: contract.name, kind: contract.kind, + declared: "availability" in contract ? contract.availability : undefined, targetOpen: status.open, cleanupRetry: status.cleanup_retry, resourceSession: status.session_kind === "bundle_resources", @@ -508,12 +499,9 @@ const availabilityFor = (context: AvailabilityContext): Availability => { remediation: "This resource-only session cannot execute this operation. Call open_binary with an executable analysis target.", }; - // These built-in workflows accept a caller-selected endpoint; they do not load the optional passive provider. - if ( - context.name === "inspect_byte_entropy" || - context.name === "observe_web_execution" || - context.name === "inspect_web_event_listeners" - ) + // Standalone workflows take caller-selected input; they do not load an + // optional provider, so its load failure does not apply to them. + if (context.declared === "standalone") return { reason: "available", remediation: null }; if (context.name === "get_navigation_context") { const target = targetAvailability(context); @@ -536,8 +524,6 @@ const availabilityFor = (context: AvailabilityContext): Availability => { ); return modes; } - const javascriptApplication = javascriptApplicationAvailability(context); - if (javascriptApplication !== null) return javascriptApplication; const failure = optionalProviderFailureFor(context); if (failure !== undefined) return { @@ -570,42 +556,18 @@ const optionalProviderFailureFor = ({ return undefined; }; -const javascriptApplicationAvailability = ({ - name, -}: AvailabilityContext): Availability | null => { - if (name === "analyze_javascript_application") - return { reason: "available", remediation: null }; - return name === "reconcile_javascript_runtime" - ? { reason: "available", remediation: null } - : null; -}; - const workflowAvailabilityFor = ( context: AvailabilityContext, ): Availability | null => { - const { name, kind, policy } = context; - if (name === "start_gdb_session" || name === "start_rizin_debug_session") - return hostRestrictedAvailability( - policy, - "persistentDebugger", - true, - "Run persistent debugger sessions on Linux with /proc descriptor readback.", - ); - if ( - name === "inspect_apk_signature" || - name === "inspect_desktop_application" || - name === "inspect_go_binary" || - name === "inspect_il2cpp_metadata" || - name === "inspect_model_artifact" || - name === "inspect_gpu_code_objects" || - name === "inspect_rust_binary" || - name === "inspect_python_pyc" || - name === "inspect_apple_ips" || - name === "inspect_erlang_beam" || - name === "inspect_v8_code_cache" || - name === "inspect_electron_fuses" - ) + const { name, kind, policy, declared } = context; + if (declared === "standalone") return { reason: "available", remediation: null }; + if (declared !== undefined) { + const host = hostFeatureAvailability(policy, declared.host); + return declared.host === "evmInterface" && host.reason === "available" + ? evmLimiterAvailability(policy) + : host; + } if (name === "inspect_sqlite_database") { const capability = sqliteDatabaseCapability(process.versions.node); return capability.available @@ -616,61 +578,7 @@ const workflowAvailabilityFor = ( }; } if (name === "trace_web_module_imports") - return { - reason: "available", - remediation: null, - defaultModeAvailable: policy.webModuleResolutionEnabled === true, - modes: [ - { - name: "sources-without-literal-imports", - available: true, - missing_operations: [], - remediation: null, - }, - policy.webModuleResolutionEnabled === true - ? { - name: "native-literal-resolution", - available: true, - missing_operations: [], - remediation: null, - } - : { - name: "native-literal-resolution", - available: false, - missing_operations: ["native-module-resolver"], - remediation: - "Provide an absolute REA_BROWSER_EXECUTABLE supporting import.meta.resolve; no binary target is required.", - }, - ], - }; - if (name === "recover_javascript_sources") - return hostRestrictedAvailability( - policy, - "javascriptRecovery", - policy.javascriptRecoveryEnabled, - "On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru ^1.13.0 (verified with 1.14.0) and util-linux prlimit; see docs/guides/javascript/javascript-recovery.md#install-wakaru. No binary target is required.", - ); - if (name === "inspect_binary_layout") - return hostRestrictedAvailability( - policy, - "binaryLayout", - policy.binaryLayoutEnabled, - "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.", - ); - if (name === "inspect_packet_capture" || name === "inspect_packet_fields") - return hostRestrictedAvailability( - policy, - "packetCapture", - policy.packetCaptureEnabled, - "On Linux, supply TShark 4.x on PATH or through absolute REA_TSHARK_COMMAND, and util-linux prlimit (REA_TSHARK_PRLIMIT_COMMAND, default /usr/bin/prlimit). No active binary target or hardware is required; the tool is checked at execution.", - ); - if (name === "decode_signal_recording" || name === "inspect_signal_decoders") - return hostRestrictedAvailability( - policy, - "signalRecording", - policy.signalRecordingEnabled, - "On Linux, supply sigrok-cli 0.7.2 via absolute REA_SIGROK_COMMAND and util-linux prlimit (REA_SIGROK_PRLIMIT_COMMAND, default /usr/bin/prlimit). No active binary target or hardware is required; the tool is checked at execution.", - ); + return webModuleImportAvailability(policy); if (name === "inspect_wasm_artifact") return policy.wasmArtifactEnabled === true ? { reason: "available", remediation: null } @@ -679,62 +587,6 @@ const workflowAvailabilityFor = ( remediation: "Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY. No active binary target is required; tools are checked at execution.", }; - if (name === "inspect_pe_resources" || name === "inspect_native_exports") - return { reason: "available", remediation: null }; - if ( - name === "inspect_pe_certificates" || - name === "inspect_pe_imports" || - name === "inspect_windows_shortcut" - ) - return { reason: "available", remediation: null }; - if ( - name === "inspect_elf_notes" || - name === "inspect_native_initializers" || - name === "inspect_elf_unwind_ranges" || - name === "inspect_devicetree" || - name === "inspect_kernel_module" || - name === "inspect_kernel_build_config" || - name === "inspect_pe_load_config" || - name === "audit_release_exposure" || - name === "inspect_binary_hardening" - ) - return { reason: "available", remediation: null }; - if (name === "inspect_evm_interface") { - const profile = hostRestrictedAvailability( - policy, - "evmInterface", - policy.evmInterfaceEnabled, - "The bundled offline EVM interface profile is currently real-verified on Linux x64. No active binary target or chain endpoint is required.", - ); - if (profile.reason !== "available") return profile; - const limiter = policy.evmLimiterAvailability; - if (limiter?.status === "unavailable") - return { reason: "provider_missing", remediation: limiter.remediation }; - return { reason: "available", remediation: null }; - } - if (name === "inspect_recorded_crash") - return hostRestrictedAvailability( - policy, - "recordedCrash", - policy.recordedCrashEnabled, - "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.", - ); - if (kind === "firmware-provider") { - const inspection = name === "inspect_firmware_regions"; - const operation = inspection - ? "inspect_firmware_regions" - : "extract_firmware"; - const requirement = - FIRMWARE_TOOL_REQUIREMENTS[FIRMWARE_OPERATION_ENGINES[operation]]; - return hostRestrictedAvailability( - policy, - inspection ? "firmwareInspection" : "firmwareExtraction", - inspection - ? policy.firmwareInspectionEnabled - : policy.firmwareExtractionEnabled, - `On Linux, provide an absolute ${requirement.commandEnvironment} (${requirement.requirement}) path, util-linux prlimit and procps ps.${inspection ? "" : " Extraction also requires the selected format’s external extractor."}`, - ); - } if (kind === "android-provider") return policy.androidAnalysisAvailability?.status === "available" ? { reason: "available", remediation: null } @@ -784,13 +636,6 @@ const workflowAvailabilityFor = ( remediation: "Run process capture on a supported Linux or macOS host.", }; if (kind === "application") return { reason: "available", remediation: null }; - if (name === "inspect_pcap_capture") - return hostRestrictedAvailability( - policy, - "pcapCapture", - true, - PCAP_CAPTURE_UNSUPPORTED_HOST_REASON, - ); if (kind === "pcap-provider" || kind === "flutter-provider") return { reason: "available", remediation: null }; const electron = electronProviderAvailability(name, kind, policy); @@ -810,6 +655,124 @@ const workflowAvailabilityFor = ( return null; }; +const firmwareRemediation = ( + operation: "inspect_firmware_regions" | "extract_firmware", +): string => { + const requirement = + FIRMWARE_TOOL_REQUIREMENTS[FIRMWARE_OPERATION_ENGINES[operation]]; + return `On Linux, provide an absolute ${requirement.commandEnvironment} (${requirement.requirement}) path, util-linux prlimit and procps ps.${operation === "inspect_firmware_regions" ? "" : " Extraction also requires the selected format’s external extractor."}`; +}; + +const PWNTOOLS_REMEDIATION = + "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required."; + +/** Each host-restricted feature's configuration flag and setup remediation. */ +const HOST_FEATURES: Readonly< + Record< + HostRestrictedFeature, + { + readonly enabled: (policy: AvailabilityPolicy) => boolean | undefined; + readonly remediation: string; + } + > +> = { + persistentDebugger: { + enabled: () => true, + remediation: + "Run persistent debugger sessions on Linux with /proc descriptor readback.", + }, + javascriptRecovery: { + enabled: (policy) => policy.javascriptRecoveryEnabled, + remediation: + "On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru ^1.13.0 (verified with 1.14.0) and util-linux prlimit; see docs/guides/javascript/javascript-recovery.md#install-wakaru. No binary target is required.", + }, + binaryLayout: { + enabled: (policy) => policy.binaryLayoutEnabled, + remediation: PWNTOOLS_REMEDIATION, + }, + recordedCrash: { + enabled: (policy) => policy.recordedCrashEnabled, + remediation: PWNTOOLS_REMEDIATION, + }, + packetCapture: { + enabled: (policy) => policy.packetCaptureEnabled, + remediation: + "On Linux, supply TShark 4.x on PATH or through absolute REA_TSHARK_COMMAND, and util-linux prlimit (REA_TSHARK_PRLIMIT_COMMAND, default /usr/bin/prlimit). No active binary target or hardware is required; the tool is checked at execution.", + }, + signalRecording: { + enabled: (policy) => policy.signalRecordingEnabled, + remediation: + "On Linux, supply sigrok-cli 0.7.2 via absolute REA_SIGROK_COMMAND and util-linux prlimit (REA_SIGROK_PRLIMIT_COMMAND, default /usr/bin/prlimit). No active binary target or hardware is required; the tool is checked at execution.", + }, + evmInterface: { + enabled: (policy) => policy.evmInterfaceEnabled, + remediation: + "The bundled offline EVM interface profile is currently real-verified on Linux x64. No active binary target or chain endpoint is required.", + }, + pcapCapture: { + enabled: () => true, + remediation: PCAP_CAPTURE_UNSUPPORTED_HOST_REASON, + }, + firmwareInspection: { + enabled: (policy) => policy.firmwareInspectionEnabled, + remediation: firmwareRemediation("inspect_firmware_regions"), + }, + firmwareExtraction: { + enabled: (policy) => policy.firmwareExtractionEnabled, + remediation: firmwareRemediation("extract_firmware"), + }, +}; + +const hostFeatureAvailability = ( + policy: AvailabilityPolicy, + feature: HostRestrictedFeature, +): Availability => + hostRestrictedAvailability( + policy, + feature, + HOST_FEATURES[feature].enabled(policy), + HOST_FEATURES[feature].remediation, + ); + +/** The EVM profile also needs a fresh observation of its required limiter. */ +const evmLimiterAvailability = (policy: AvailabilityPolicy): Availability => { + const limiter = policy.evmLimiterAvailability; + return limiter?.status === "unavailable" + ? { reason: "provider_missing", remediation: limiter.remediation } + : { reason: "available", remediation: null }; +}; + +/** Literal-import resolution is a mode; source tracing alone is always available. */ +const webModuleImportAvailability = ( + policy: AvailabilityPolicy, +): Availability => ({ + reason: "available", + remediation: null, + defaultModeAvailable: policy.webModuleResolutionEnabled === true, + modes: [ + { + name: "sources-without-literal-imports", + available: true, + missing_operations: [], + remediation: null, + }, + policy.webModuleResolutionEnabled === true + ? { + name: "native-literal-resolution", + available: true, + missing_operations: [], + remediation: null, + } + : { + name: "native-literal-resolution", + available: false, + missing_operations: ["native-module-resolver"], + remediation: + "Provide an absolute REA_BROWSER_EXECUTABLE supporting import.meta.resolve; no binary target is required.", + }, + ], +}); + /** * An unsupported host takes precedence over configuration: no environment * setting lets these integrations pass their execution host checks here. diff --git a/src/contracts/apkSignature/apkSignatureToolContracts.ts b/src/contracts/apkSignature/apkSignatureToolContracts.ts index 4856b58f3c..cf49217a16 100644 --- a/src/contracts/apkSignature/apkSignatureToolContracts.ts +++ b/src/contracts/apkSignature/apkSignatureToolContracts.ts @@ -12,6 +12,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; /** Static APK signature-scheme inspection of a selected local archive. */ export const INSPECT_APK_SIGNATURE_CONTRACT = { name: "inspect_apk_signature", + availability: "standalone", ...toolContractMetadata("inspect_apk_signature"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/captures/captureToolContracts.ts b/src/contracts/captures/captureToolContracts.ts index ff21389f09..8cee05a30d 100644 --- a/src/contracts/captures/captureToolContracts.ts +++ b/src/contracts/captures/captureToolContracts.ts @@ -12,6 +12,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; export const CAPTURE_TOOL_CONTRACTS = [ { name: "inspect_packet_fields", + availability: { host: "packetCapture" }, ...toolContractMetadata("inspect_packet_fields"), kind: "artifact-provider", requiresActiveTarget: true, @@ -29,6 +30,7 @@ export const CAPTURE_TOOL_CONTRACTS = [ }, { name: "inspect_packet_capture", + availability: { host: "packetCapture" }, ...toolContractMetadata("inspect_packet_capture"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/desktopApplicationToolContracts.ts b/src/contracts/desktopApplicationToolContracts.ts index f910d93a60..d526c337c0 100644 --- a/src/contracts/desktopApplicationToolContracts.ts +++ b/src/contracts/desktopApplicationToolContracts.ts @@ -12,6 +12,7 @@ import type { ToolContract } from "./toolContractTypes.js"; export const DESKTOP_APPLICATION_TOOL_CONTRACTS = [ { name: "inspect_desktop_application", + availability: "standalone", ...toolContractMetadata("inspect_desktop_application"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/erlang/beamToolContracts.ts b/src/contracts/erlang/beamToolContracts.ts index bc3884d54a..87b84effac 100644 --- a/src/contracts/erlang/beamToolContracts.ts +++ b/src/contracts/erlang/beamToolContracts.ts @@ -29,6 +29,7 @@ export const inspectErlangBeamRequestSchema = presentRootDiscriminator( export const ERLANG_BEAM_TOOL_CONTRACTS = [ { name: "inspect_erlang_beam", + availability: "standalone", ...toolContractMetadata("inspect_erlang_beam"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/evm/evmToolContracts.ts b/src/contracts/evm/evmToolContracts.ts index 59f2d59112..1d596349e2 100644 --- a/src/contracts/evm/evmToolContracts.ts +++ b/src/contracts/evm/evmToolContracts.ts @@ -20,6 +20,7 @@ const evmInterfaceInspectionInputSchema = inspectEvmInterfaceInputSchema.extend( /** Target-free EVM capabilities are independent of archive/Apple artifact providers. */ export const INSPECT_EVM_INTERFACE_CONTRACT = { name: "inspect_evm_interface", + availability: { host: "evmInterface" }, ...toolContractMetadata("inspect_evm_interface"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/firmware/firmwareToolContracts.ts b/src/contracts/firmware/firmwareToolContracts.ts index 6e029b7003..66d8e21d21 100644 --- a/src/contracts/firmware/firmwareToolContracts.ts +++ b/src/contracts/firmware/firmwareToolContracts.ts @@ -14,6 +14,7 @@ import { export const FIRMWARE_TOOL_CONTRACTS = [ { name: "inspect_firmware_regions", + availability: { host: "firmwareInspection" }, ...toolContractMetadata("inspect_firmware_regions"), kind: "firmware-provider", description: `Inspect signature candidates in a local firmware file with ${FIRMWARE_TOOL_REQUIREMENTS[FIRMWARE_OPERATION_ENGINES.inspect_firmware_regions].requirement}. Returns offsets, reported lengths, descriptions and raw confidence values. Length validation and runtime addresses remain unknown. No extraction or target execution. Linux, caller-supplied tool, util-linux prlimit and procps ps required; 128 MiB input limit, one worker. Adjust analysis_timeout_ms for the analysis wall-clock budget (default 120000); fixed per-process limits are unchanged.`, @@ -30,6 +31,7 @@ export const FIRMWARE_TOOL_CONTRACTS = [ }, { name: "extract_firmware", + availability: { host: "firmwareExtraction" }, ...toolContractMetadata("extract_firmware"), kind: "firmware-provider", description: `Extract selected local firmware bytes with ${FIRMWARE_TOOL_REQUIREMENTS[FIRMWARE_OPERATION_ENGINES.extract_firmware].requirement} into an absent output directory. Returns verified child paths/digests, derivations, uncovered ranges, unknown chunks and extraction_gaps with continuation_id recovery instructions. Linux, format-specific extractors, prlimit and procps ps are required. Preserves the sandbox and publishes only regular files; no mounts or extracted-code execution. Select a returned native file with open_binary for analysis. Decompressed offsets are not original-file addresses.`, diff --git a/src/contracts/gdbToolContracts.ts b/src/contracts/gdbToolContracts.ts index b419e2579c..564fb0a3ac 100644 --- a/src/contracts/gdbToolContracts.ts +++ b/src/contracts/gdbToolContracts.ts @@ -16,6 +16,7 @@ const sessionId = z.string().uuid(); export const GDB_TOOL_CONTRACTS = [ { name: "start_gdb_session", + availability: { host: "persistentDebugger" }, ...toolContractMetadata("start_gdb_session"), kind: "native-provider", description: diff --git a/src/contracts/go/goToolContracts.ts b/src/contracts/go/goToolContracts.ts index d4b33fd430..4c5e72306e 100644 --- a/src/contracts/go/goToolContracts.ts +++ b/src/contracts/go/goToolContracts.ts @@ -11,6 +11,7 @@ import { goBinarySummaryViewResultSchema } from "../../domain/analysisView/analy export const GO_TOOL_CONTRACTS = [ { name: "inspect_go_binary", + availability: "standalone", ...toolContractMetadata("inspect_go_binary"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/gpu/gpuToolContracts.ts b/src/contracts/gpu/gpuToolContracts.ts index 77bf42f2b2..8b6cf1bdfb 100644 --- a/src/contracts/gpu/gpuToolContracts.ts +++ b/src/contracts/gpu/gpuToolContracts.ts @@ -13,6 +13,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; export const GPU_TOOL_CONTRACTS = [ { name: "inspect_gpu_code_objects", + availability: "standalone", ...toolContractMetadata("inspect_gpu_code_objects"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/il2cpp/il2cppToolContracts.ts b/src/contracts/il2cpp/il2cppToolContracts.ts index 66d26eb57c..454be0fc3d 100644 --- a/src/contracts/il2cpp/il2cppToolContracts.ts +++ b/src/contracts/il2cpp/il2cppToolContracts.ts @@ -12,6 +12,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; export const IL2CPP_TOOL_CONTRACTS = [ { name: "inspect_il2cpp_metadata", + availability: "standalone", ...toolContractMetadata("inspect_il2cpp_metadata"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/javascript/electronToolContracts.ts b/src/contracts/javascript/electronToolContracts.ts index b1e3467c79..e385e60593 100644 --- a/src/contracts/javascript/electronToolContracts.ts +++ b/src/contracts/javascript/electronToolContracts.ts @@ -112,6 +112,7 @@ export const ELECTRON_TOOL_CONTRACTS = [ }, { name: "analyze_javascript_application", + availability: "standalone", ...toolContractMetadata("analyze_javascript_application"), description: 'Build a static application graph from a local ASAR or extracted JavaScript app without executing it. Supply input_path, e.g. {input_path:"/apps/client",source_paths:["main.js"],detail:"summary"}. Copy source_paths exactly from the inventory, not host-absolute paths inferred from input_path. Returns nodes, edges, semantic relations, integrity contradictions, coverage and unknowns. source_paths limits source analysis to exact inventoried paths without narrowing inventory or artifact identity; dependencies are not implicitly analyzed and unselected sources remain unknown. detail summary reduces delivery, retaining complete Evidence for inspect_analysis_view; it does not reduce analysis. With summary detail, view {kind:"javascript-routes",collection:"routes",offset:0,limit:64} selects static route patterns; static routes do not prove reachability or the complete route set. Integrity mismatches fail by default; record-and-continue retains untrusted observed bytes and partial coverage. analysis_timeout_ms is a per-source provider budget. A host-only timeout needs a longer client deadline, not that budget; do not repeat unchanged work or assume it stopped. If configuration cannot be edited, report the host setting (Codex: mcp_servers..tool_timeout_sec, seconds).', @@ -146,6 +147,7 @@ export const ELECTRON_TOOL_CONTRACTS = [ }, { name: "reconcile_javascript_runtime", + availability: "standalone", ...toolContractMetadata("reconcile_javascript_runtime"), description: "Reconcile verified static JavaScript application graphs with existing passive web/Electron CDP, passive V8 Inspector, or provider-owned active Electron Evidence. Active Electron captures contribute an explicitly partial target-only runtime record; they never invent renderer scripts, frames, workers, or execution claims. Exact captured-source digests take priority over caller-declared file/URL mappings; target, frame, script, and worker ambiguity remains explicit, and source-map authority stays separate.", @@ -173,6 +175,7 @@ export const ELECTRON_TOOL_CONTRACTS = [ }, { name: "inspect_electron_fuses", + availability: "standalone", ...toolContractMetadata("inspect_electron_fuses"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/javascript/javascriptRecoveryToolContracts.ts b/src/contracts/javascript/javascriptRecoveryToolContracts.ts index 420a796ddc..0ed421d96f 100644 --- a/src/contracts/javascript/javascriptRecoveryToolContracts.ts +++ b/src/contracts/javascript/javascriptRecoveryToolContracts.ts @@ -10,6 +10,7 @@ import type { ToolContract } from "../toolContractTypes.js"; export const JAVASCRIPT_RECOVERY_TOOL_CONTRACTS = [ { name: "recover_javascript_sources", + availability: { host: "javascriptRecovery" }, ...toolContractMetadata("recover_javascript_sources"), kind: "application", description: diff --git a/src/contracts/model/modelToolContracts.ts b/src/contracts/model/modelToolContracts.ts index 2908d900a4..4d871d7714 100644 --- a/src/contracts/model/modelToolContracts.ts +++ b/src/contracts/model/modelToolContracts.ts @@ -11,6 +11,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; export const INSPECT_MODEL_ARTIFACT_CONTRACT = { name: "inspect_model_artifact", + availability: "standalone", ...toolContractMetadata("inspect_model_artifact"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/native/binaryDiagnosticsToolContracts.ts b/src/contracts/native/binaryDiagnosticsToolContracts.ts index 6b0d98ef2d..1100084245 100644 --- a/src/contracts/native/binaryDiagnosticsToolContracts.ts +++ b/src/contracts/native/binaryDiagnosticsToolContracts.ts @@ -92,6 +92,7 @@ export const inspectByteEntropyRequestSchema = export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ { name: "inspect_devicetree", + availability: "standalone", ...toolContractMetadata("inspect_devicetree"), kind: "native-provider", description: @@ -112,6 +113,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_pe_load_config", + availability: "standalone", ...toolContractMetadata("inspect_pe_load_config"), kind: "native-provider", description: @@ -127,6 +129,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_binary_hardening", + availability: "standalone", ...toolContractMetadata("inspect_binary_hardening"), kind: "native-provider", description: @@ -143,6 +146,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ { name: "inspect_native_initializers", + availability: "standalone", ...toolContractMetadata("inspect_native_initializers"), kind: "native-provider", description: @@ -159,6 +163,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ { name: "inspect_elf_notes", + availability: "standalone", ...toolContractMetadata("inspect_elf_notes"), kind: "native-provider", description: @@ -174,6 +179,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_elf_unwind_ranges", + availability: "standalone", ...toolContractMetadata("inspect_elf_unwind_ranges"), kind: "native-provider", description: @@ -189,6 +195,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_apple_ips", + availability: "standalone", ...toolContractMetadata("inspect_apple_ips"), kind: "native-provider", description: @@ -211,6 +218,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_kernel_module", + availability: "standalone", ...toolContractMetadata("inspect_kernel_module"), kind: "native-provider", description: @@ -227,6 +235,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_kernel_build_config", + availability: "standalone", ...toolContractMetadata("inspect_kernel_build_config"), kind: "native-provider", description: @@ -249,6 +258,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_byte_entropy", + availability: "standalone", ...toolContractMetadata("inspect_byte_entropy"), kind: "native-provider", description: @@ -274,6 +284,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_pe_certificates", + availability: "standalone", ...toolContractMetadata("inspect_pe_certificates"), kind: "native-provider", description: @@ -289,6 +300,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_pe_imports", + availability: "standalone", ...toolContractMetadata("inspect_pe_imports"), kind: "native-provider", description: @@ -304,6 +316,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_windows_shortcut", + availability: "standalone", ...toolContractMetadata("inspect_windows_shortcut"), kind: "native-provider", description: @@ -319,6 +332,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_pe_resources", + availability: "standalone", ...toolContractMetadata("inspect_pe_resources"), kind: "native-provider", description: @@ -334,6 +348,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_native_exports", + availability: "standalone", ...toolContractMetadata("inspect_native_exports"), kind: "native-provider", description: @@ -352,6 +367,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_binary_layout", + availability: { host: "binaryLayout" }, ...toolContractMetadata("inspect_binary_layout"), kind: "native-provider", description: @@ -374,6 +390,7 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [ }, { name: "inspect_recorded_crash", + availability: { host: "recordedCrash" }, ...toolContractMetadata("inspect_recorded_crash"), kind: "native-provider", description: diff --git a/src/contracts/pcap/pcapToolContracts.ts b/src/contracts/pcap/pcapToolContracts.ts index 3940c1f252..efb14a1a1b 100644 --- a/src/contracts/pcap/pcapToolContracts.ts +++ b/src/contracts/pcap/pcapToolContracts.ts @@ -25,6 +25,7 @@ export const PCAP_TOOL_CONTRACTS = [ }, { name: "inspect_pcap_capture", + availability: { host: "pcapCapture" }, ...toolContractMetadata("inspect_pcap_capture"), description: "Summarize a saved pcap/pcapng snapshot: exact packet count, SHA-256, IP endpoints, DNS questions/addresses, TLS SNI, protocols and HTTP URIs. Use inspect_packet_capture for caller-selected TShark fields or display filters. Default complete returns full Evidence; detail summary retains it for inspect_analysis_view kind pcap. Unknown DNS attribution and excluded credentials stay explicit. Requires caller-supplied capinfos/tshark and Linux prlimit or Windows Job Objects; never captures live traffic.", diff --git a/src/contracts/python/pythonPycToolContracts.ts b/src/contracts/python/pythonPycToolContracts.ts index 8caba70bc5..9252f48859 100644 --- a/src/contracts/python/pythonPycToolContracts.ts +++ b/src/contracts/python/pythonPycToolContracts.ts @@ -29,6 +29,7 @@ export const inspectPythonPycRequestSchema = presentRootDiscriminator( export const PYTHON_PYC_TOOL_CONTRACTS = [ { name: "inspect_python_pyc", + availability: "standalone", ...toolContractMetadata("inspect_python_pyc"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/releaseExposureToolContracts.ts b/src/contracts/releaseExposureToolContracts.ts index af094a31ef..bf9bd0790a 100644 --- a/src/contracts/releaseExposureToolContracts.ts +++ b/src/contracts/releaseExposureToolContracts.ts @@ -10,6 +10,7 @@ import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js"; export const RELEASE_EXPOSURE_TOOL_CONTRACTS = [ { name: "audit_release_exposure", + availability: "standalone", ...toolContractMetadata("audit_release_exposure"), kind: "artifact-provider", description: diff --git a/src/contracts/rizinDebugToolContracts.ts b/src/contracts/rizinDebugToolContracts.ts index 0c9ac55860..97d27d2b6c 100644 --- a/src/contracts/rizinDebugToolContracts.ts +++ b/src/contracts/rizinDebugToolContracts.ts @@ -20,6 +20,7 @@ const commandResult = z.strictObject({ export const RIZIN_DEBUG_TOOL_CONTRACTS = [ { name: "start_rizin_debug_session", + availability: { host: "persistentDebugger" }, ...toolContractMetadata("start_rizin_debug_session"), kind: "native-provider", description: diff --git a/src/contracts/rust/rustToolContracts.ts b/src/contracts/rust/rustToolContracts.ts index 6358c5e00e..8bf2fd9898 100644 --- a/src/contracts/rust/rustToolContracts.ts +++ b/src/contracts/rust/rustToolContracts.ts @@ -13,6 +13,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; export const RUST_TOOL_CONTRACTS = [ { name: "inspect_rust_binary", + availability: "standalone", ...toolContractMetadata("inspect_rust_binary"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/signals/signalToolContracts.ts b/src/contracts/signals/signalToolContracts.ts index af9973931b..6f92089c15 100644 --- a/src/contracts/signals/signalToolContracts.ts +++ b/src/contracts/signals/signalToolContracts.ts @@ -12,6 +12,7 @@ import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; export const SIGNAL_TOOL_CONTRACTS = [ { name: "inspect_signal_decoders", + availability: { host: "signalRecording" }, ...toolContractMetadata("inspect_signal_decoders"), kind: "artifact-provider", requiresActiveTarget: true, @@ -29,6 +30,7 @@ export const SIGNAL_TOOL_CONTRACTS = [ }, { name: "decode_signal_recording", + availability: { host: "signalRecording" }, ...toolContractMetadata("decode_signal_recording"), kind: "artifact-provider", requiresActiveTarget: true, diff --git a/src/contracts/toolAvailability.ts b/src/contracts/toolAvailability.ts new file mode 100644 index 0000000000..93f480bc9a --- /dev/null +++ b/src/contracts/toolAvailability.ts @@ -0,0 +1,32 @@ +/** Optional integrations whose verified hosts exclude some platforms. */ +export const HOST_RESTRICTED_FEATURES = [ + "packetCapture", + "pcapCapture", + "signalRecording", + "evmInterface", + "binaryLayout", + "recordedCrash", + "firmwareInspection", + "firmwareExtraction", + "javascriptRecovery", + "persistentDebugger", +] as const; +export type HostRestrictedFeature = (typeof HOST_RESTRICTED_FEATURES)[number]; + +/** + * What a tool needs before it can run, declared with its contract and + * interpreted once by the capability inventory. + * + * - `"standalone"`: a built-in workflow over caller-selected input. It needs + * no optional provider, deep-analysis provider or host integration, so it + * is always available. + * - `{ host }`: an optional integration that the host must support and the + * operator must configure; the inventory owns each feature's configuration + * flag and remediation. + * + * A contract without a declaration takes its availability from its provider + * family, its active target, or a named rule in the inventory. + */ +export type ToolAvailabilityDeclaration = + | "standalone" + | { readonly host: HostRestrictedFeature }; diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts index c421563732..b13a10589d 100644 --- a/src/contracts/toolContractTypes.ts +++ b/src/contracts/toolContractTypes.ts @@ -1,6 +1,7 @@ import type { z } from "zod"; import type { JsonValue } from "../domain/jsonValue.js"; +import type { ToolAvailabilityDeclaration } from "./toolAvailability.js"; import type { DerivedToolAnnotations, ToolEffects } from "./toolEffects.js"; /** One validated example request for an MCP tool contract. */ @@ -47,6 +48,8 @@ export interface ToolContract< readonly title: string; readonly description: string; readonly kind: ToolKind; + /** What the tool needs before it can run; see ToolAvailabilityDeclaration. */ + readonly availability?: ToolAvailabilityDeclaration; /** This handler dispatches through the active binary-analysis session. */ readonly requiresActiveTarget?: boolean; /** Adapter delivery of a retained summary; detail never reaches analysis. */ diff --git a/src/contracts/v8/v8CodeCacheToolContracts.ts b/src/contracts/v8/v8CodeCacheToolContracts.ts index 107b36a9c9..a5434c11d3 100644 --- a/src/contracts/v8/v8CodeCacheToolContracts.ts +++ b/src/contracts/v8/v8CodeCacheToolContracts.ts @@ -10,6 +10,7 @@ import { toolContractMetadata } from "../toolEffects.js"; export const V8_CODE_CACHE_TOOL_CONTRACTS = [ { name: "inspect_v8_code_cache", + availability: "standalone", ...toolContractMetadata("inspect_v8_code_cache"), kind: "artifact-provider", description: diff --git a/src/contracts/webRuntimeToolContracts.ts b/src/contracts/webRuntimeToolContracts.ts index 5c723735fd..aa52f6fcb0 100644 --- a/src/contracts/webRuntimeToolContracts.ts +++ b/src/contracts/webRuntimeToolContracts.ts @@ -14,6 +14,7 @@ import { export const WEB_RUNTIME_TOOL_CONTRACTS = [ { name: "observe_web_execution", + availability: "standalone", ...toolContractMetadata("observe_web_execution"), description: "Instrument one selected CDP page for a finite, externally driven precise coverage window. Resets execution counters and prevents optimized execution until stopped. Returns complete nested UTF-16 ranges/counts, independently hashed script text and request initiator associations by session script ID. Does not navigate, click, evaluate selected code or close the externally owned page. Navigation ends document-scoped collection; workers and UI causality remain outside this claim. Emits an actual armed progress notification before external actions.", @@ -33,6 +34,7 @@ export const WEB_RUNTIME_TOOL_CONTRACTS = [ }, { name: "inspect_web_event_listeners", + availability: "standalone", ...toolContractMetadata("inspect_web_event_listeners"), description: "Inspect listeners registered directly on the first main-document CSS match in one selected CDP page. Returns event flags, native callback locations, source ownership and exact script text/digests inline. Does not dispatch events, evaluate JavaScript or invoke handlers. Delegated ancestor/framework listeners and execution history remain unknown. Releases REA's object group and transport, preserving the external page.", diff --git a/src/server/sessionAvailabilityPolicy.ts b/src/server/sessionAvailabilityPolicy.ts index 286f500ede..efbb883744 100644 --- a/src/server/sessionAvailabilityPolicy.ts +++ b/src/server/sessionAvailabilityPolicy.ts @@ -1,8 +1,8 @@ +import type { AvailabilityPolicy } from "../application/CapabilityInventory.js"; import { HOST_RESTRICTED_FEATURES, - type AvailabilityPolicy, type HostRestrictedFeature, -} from "../application/CapabilityInventory.js"; +} from "../contracts/toolAvailability.js"; import { platform } from "node:process"; import type { CapabilityAvailabilityFacts } from "../application/CapabilityAvailability.js";