Files
reverse-engineering-anything/src/application/CapabilityInventory.ts
T
morluto d1675822f6 refactor(capabilities): declare standalone and host-gated availability on the contract (#11270)
Contracts declare availability: "standalone" or { host: <feature> }, and CapabilityInventory interprets the declaration once through one feature table, replacing 39 per-name branches. HOST_RESTRICTED_FEATURES moves to the contracts layer.
2026-11-15 23:52:56 +08:00

1264 lines
44 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { PCAP_CAPTURE_UNSUPPORTED_HOST_REASON } from "../domain/pcap/pcapAnalysis.js";
import { DEFAULT_CALL_RELATIONSHIP_DIRECTION } from "../contracts/enhancedInputs.js";
import {
FIRMWARE_OPERATION_ENGINES,
FIRMWARE_TOOL_REQUIREMENTS,
} from "../contracts/firmware/firmwareToolRequirements.js";
import { CALL_RELATIONSHIP_TRAVERSALS } from "./CallRelationshipTraversal.js";
import { ADDRESS_CONTEXT_FACET_OPERATIONS } from "./AnalysisContextQueries.js";
import { NATIVE_DISPATCH_METADATA_SOURCES } from "./native/NativeDispatchMetadataInspection.js";
import { NATIVE_UI_ACTION_OPERATIONS } from "./native/NativeUiActionTrace.js";
import { NATIVE_CALL_ROUTE_SOURCES } from "./native/NativeCallRoutes.js";
import { z } from "zod";
import type { BinarySessionDetail } from "../contracts/sessionStatusContract.js";
import { sqliteDatabaseCapability } from "./sqlite/SqliteDatabaseCapability.js";
import type {
OptionalProviderLoadFailures,
OptionalProviderLoadFailure,
} from "./OptionalObservationProviders.js";
import type {
CommandProviderLaunchFailures,
ReverseEngineeringOperation,
} from "./reverse/ReverseEngineeringService.js";
import {
expandProviderCapabilities,
providerCapabilitySet,
toolAvailabilityInventory,
toolAvailabilitySummaryInventory,
TOOL_ANNOTATION_NAMES,
TOOL_EFFECT_NAMES,
type ToolAvailabilityInventory,
type ToolAvailabilitySummaryInventory,
type ToolAvailability,
type ToolAvailabilityMode,
type ToolUnavailabilityReason,
} from "../contracts/toolOutputSchemaPrimitives.js";
import {
annotationsFromEffects,
toolSessionEffects,
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 {
AnalysisOperation,
ProviderAvailability,
} from "./AnalysisProvider.js";
import type { JebAnalysisAvailability } from "./jeb/JebAnalysisPort.js";
import { FRIDA_TOOL_CONTRACTS } from "../contracts/fridaToolContracts.js";
import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import {
analysisCleanupRetrySchema,
cleanupRetryRemediation,
type AnalysisCleanupRetry,
} from "../domain/analysisErrorRecovery.js";
import { isBundleResourceOperation } from "./binary/BundleResourceSession.js";
import { offeredOperationAlternatives } from "./OperationAlternatives.js";
const FRIDA_OPERATION_NAMES: ReadonlySet<string> = new Set(
FRIDA_TOOL_CONTRACTS.map(({ name }) => name),
);
const statusSchema = z.object({
open: z.boolean(),
cleanup_retry: analysisCleanupRetrySchema.optional(),
session_kind: z.literal("bundle_resources").optional(),
kind: z.enum(["executable", "database", "archive", "artifact"]).optional(),
format: z.string().optional(),
capabilities: z
.array(providerCapabilitySet)
.transform(expandProviderCapabilities),
});
type ToolAvailabilityReason = "available" | ToolUnavailabilityReason;
type ProviderDescriptor = ReturnType<typeof expandProviderCapabilities>[number];
type UnavailableDescriptor = Extract<ProviderDescriptor, { available: false }>;
export type AvailabilityPolicy = {
/** Integrations this host cannot run, whatever their configuration. */
readonly hostUnsupported?: Readonly<
Partial<Record<HostRestrictedFeature, boolean>>
>;
readonly packetCaptureEnabled?: boolean;
readonly signalRecordingEnabled?: boolean;
readonly wasmArtifactEnabled?: boolean;
readonly evmInterfaceEnabled?: boolean;
/** Fresh owner observation of the selected required EVM limiter. */
readonly evmLimiterAvailability?: ProviderAvailability;
readonly processCaptureEnabled: boolean;
readonly optionalProviderLoadFailures?: OptionalProviderLoadFailures;
readonly commandProviderFailures?: CommandProviderLaunchFailures;
readonly binaryLayoutEnabled?: boolean;
readonly recordedCrashEnabled?: boolean;
readonly firmwareInspectionEnabled?: boolean;
readonly firmwareExtractionEnabled?: boolean;
readonly androidAnalysisAvailability?: ProviderAvailability;
readonly adbAnalysisAvailability?: ProviderAvailability;
readonly apktoolAnalysisAvailability?: ProviderAvailability;
readonly jebAnalysisAvailability?: JebAnalysisAvailability;
readonly javascriptRecoveryEnabled?: boolean;
readonly webModuleResolutionEnabled?: boolean;
readonly browserObservationEnabled?: boolean;
readonly browserScenarioEnabled?: boolean;
readonly electronObservationEnabled?: boolean;
readonly electronAutomationEnabled?: boolean;
readonly v8InspectorObservationEnabled?: boolean;
};
type AvailabilityFacts = {
readonly defaultModeAvailable?: boolean;
readonly modes?: readonly ToolAvailabilityMode[];
/** Advertised operations the current provider offers for part of the question. */
readonly alternatives?: readonly AnalysisOperation[];
};
type Availability = AvailabilityFacts &
(
| { readonly reason: "available"; readonly remediation: null }
| {
readonly reason: ToolUnavailabilityReason;
readonly remediation: string | null;
}
);
type AvailabilityModeResult =
| (Extract<ToolAvailabilityMode, { available: true }> & {
readonly reason: "available";
})
| (Extract<ToolAvailabilityMode, { available: false }> & {
readonly reason: ToolUnavailabilityReason;
});
/** Recovery when unavailable modes require different actions. */
export const MULTI_MODE_REMEDIATION =
"No mode is currently advertised as available. Inspect each mode's missing operations and remediation.";
type AvailabilityContext = {
readonly name: string;
readonly kind: ToolKind;
readonly declared: ToolAvailabilityDeclaration | undefined;
readonly targetOpen: boolean;
readonly cleanupRetry: AnalysisCleanupRetry | undefined;
readonly resourceSession: boolean;
readonly requiresActiveTarget: boolean;
readonly targetKind:
| "executable"
| "database"
| "archive"
| "artifact"
| undefined;
readonly targetFormat: string | undefined;
readonly descriptors: ReadonlyMap<string, ProviderDescriptor>;
readonly policy: AvailabilityPolicy;
readonly isToolAdvertised: (name: string) => boolean;
};
type EnhancedContractName = Extract<
(typeof TOOL_CONTRACTS)[number],
{ readonly kind: "enhanced" }
>["name"];
type RequiredCompositionSource =
| AnalysisOperation
| readonly AnalysisOperation[];
type CompositionSource =
| RequiredCompositionSource
| { readonly optional: AnalysisOperation };
// Parallel stages are flat: every member dispatches before any sibling outcome is selected.
type CompositionRequirements = readonly (
| CompositionSource
| { readonly parallel: readonly CompositionSource[] }
)[];
const stageSources = (
stage: CompositionRequirements[number],
): readonly CompositionSource[] =>
typeof stage !== "string" && "parallel" in stage ? stage.parallel : [stage];
const optionalSource = (
source: CompositionSource,
): source is { readonly optional: AnalysisOperation } =>
typeof source !== "string" && "optional" in source;
const sourceOperations = (
source: CompositionSource,
): readonly AnalysisOperation[] =>
typeof source === "string"
? [source]
: optionalSource(source)
? [source.optional]
: source;
type AvailabilityMode = {
readonly name: string;
readonly requirements: CompositionRequirements;
};
type ModeComposition = {
readonly defaultMode?: string;
readonly modes: readonly AvailabilityMode[];
};
type ProviderComposition = CompositionRequirements | ModeComposition;
const CALL_RELATIONSHIP_COMPOSITION: ModeComposition = {
defaultMode: DEFAULT_CALL_RELATIONSHIP_DIRECTION,
modes: Object.entries(CALL_RELATIONSHIP_TRAVERSALS).map(
([name, traversal]) => ({
name,
requirements: ["procedure_address", traversal.operation],
}),
),
};
const NATIVE_UI_ACTION_COMPOSITION: ModeComposition = {
modes: [
{
name: "authored_ui_dispatch",
requirements: [
NATIVE_UI_ACTION_OPERATIONS.interfaceBuilder,
Object.values(NATIVE_DISPATCH_METADATA_SOURCES),
],
},
{
name: "native_seed_call_trace",
requirements: [
Object.values(NATIVE_DISPATCH_METADATA_SOURCES),
NATIVE_UI_ACTION_OPERATIONS.nativeSeed,
Object.values(NATIVE_CALL_ROUTE_SOURCES),
],
},
],
};
// Complete coverage is checked against canonical enhanced contracts, rather than
// allowing a newly registered workflow to silently look like a missing provider.
const ENHANCED_REQUIREMENTS: ReadonlyMap<string, ProviderComposition> = new Map(
Object.entries({
trace_native_values: ["analyze_function", "resolve_native_call_targets"],
trace_native_ui_action: NATIVE_UI_ACTION_COMPOSITION,
inspect_native_dispatch_metadata: [
Object.values(NATIVE_DISPATCH_METADATA_SOURCES),
],
get_objc_classes: [
"list_names",
{ optional: "inspect_native_dispatch_metadata" },
],
get_objc_protocols: ["list_names"],
batch_decompile: [
{ optional: "procedure_address" },
{ optional: "address_name" },
"procedure_pseudo_code",
],
decompile_all: ["list_procedures", "procedure_pseudo_code"],
get_call_graph: CALL_RELATIONSHIP_COMPOSITION,
trace_call_path: CALL_RELATIONSHIP_COMPOSITION,
analyze_swift_types: ["list_procedures", { optional: "list_names" }],
find_xrefs_to_name: ["list_names", "xrefs"],
binary_overview: [
{ optional: "read_binary_inventory_summary" },
["current_document", "list_documents"],
{
parallel: [
{ optional: "list_segments" },
"list_procedures",
"list_strings",
],
},
],
analyze_function: ["analyze_function"],
inspect_native_api: ["analyze_function"],
trace_feature: [
"search_strings",
"search_procedures",
"xrefs",
{ optional: "resolve_containing_procedure" },
],
} satisfies Readonly<Record<EnhancedContractName, ProviderComposition>>),
);
/** Native contracts defined only for an active Mach-O executable. */
const MACHO_TARGET_OPERATIONS: ReadonlySet<string> = new Set([
"inspect_signature",
"inspect_macho",
"list_architectures",
"observe_native_calls",
"observe_native_ui",
"capture_native_ui_scenario",
]);
const NAVIGATION_CONTEXT_MODES = [
{
name: "current_selection",
requirements: [
"current_document",
"current_address",
"resolve_containing_procedure",
],
},
{
name: "explicit_document",
requirements: ["current_address", "resolve_containing_procedure"],
},
] as const;
const ADDRESS_CONTEXT_EFFECT_COMPOSITION: ModeComposition = {
modes: [
{
name: "explicit_document",
requirements: [ADDRESS_CONTEXT_FACET_OPERATIONS],
},
{
name: "provider_document",
requirements: [
["current_document", "list_documents"],
ADDRESS_CONTEXT_FACET_OPERATIONS,
],
},
],
};
/**
* Build stable per-operation availability for the caller's advertised tools.
* Each tool's availability still derives from the complete provider facts;
* advertisement narrows only the reported tools and the alternatives named.
*/
export const buildCapabilityInventory = (
sessionStatus: JsonValue,
policy: AvailabilityPolicy,
isToolAdvertised: (name: string) => boolean = () => true,
): readonly ToolAvailability[] => {
const status = statusSchema.parse(sessionStatus);
const descriptors = new Map<string, ProviderDescriptor>(
status.capabilities.map((descriptor) => [descriptor.operation, descriptor]),
);
return TOOL_CONTRACTS.map((contract): ToolAvailability => {
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",
requiresActiveTarget:
"requiresActiveTarget" in contract &&
contract.requiresActiveTarget === true,
targetKind: status.kind,
targetFormat: status.format,
descriptors,
policy,
isToolAdvertised,
});
const effects = composedEffects(
contract.name,
toolSessionEffects(contract.name),
status.capabilities,
);
const annotations = annotationsFromEffects(effects);
const facts = {
name: contract.name,
surface: contract.kind,
...(contract.name === "trace_native_values"
? {
value_flow_support: (() => {
const source = descriptors.get("analyze_function");
return source?.native_value_flow === undefined
? {
status: "unknown" as const,
provider_id: source?.provider.id ?? null,
}
: {
...source.native_value_flow,
provider_id: source.provider.id,
};
})(),
}
: {}),
...(availability.defaultModeAvailable === undefined
? {}
: { default_mode_available: availability.defaultModeAvailable }),
...(availability.modes === undefined
? {}
: { modes: [...availability.modes] }),
client_requirements: emptyClientRequirements(),
effects,
annotations: {
read_only: annotations.readOnlyHint,
destructive: annotations.destructiveHint,
idempotent: annotations.idempotentHint,
open_world: annotations.openWorldHint,
},
};
return availability.reason === "available"
? {
...facts,
available: true,
reason: availability.reason,
remediation: null,
}
: {
...facts,
available: false,
reason: availability.reason,
remediation: availability.remediation,
...(availability.alternatives === undefined
? {}
: { alternatives: [...availability.alternatives] }),
};
})
.filter(({ name }) => isToolAdvertised(name))
.sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
};
type ClientRequirements = ToolAvailability["client_requirements"];
// Current workflows do not require negotiated MCP client features.
const emptyClientRequirements = (): ClientRequirements => ({
required: [],
optional: [],
missing_required: [],
missing_optional: [],
});
/**
* Group every operation's current availability inline. Complete detail also
* groups by the static surface, effect, and annotation flags; summary omits
* those flags so tools that share a status collapse into one group.
*/
export function compactToolAvailability(
availability: readonly ToolAvailability[],
detail?: "complete",
): ToolAvailabilityInventory;
export function compactToolAvailability(
availability: readonly ToolAvailability[],
detail: BinarySessionDetail,
): ToolAvailabilityInventory | ToolAvailabilitySummaryInventory;
export function compactToolAvailability(
availability: readonly ToolAvailability[],
detail: BinarySessionDetail = "complete",
): ToolAvailabilityInventory | ToolAvailabilitySummaryInventory {
const clientRequirements =
availability[0]?.client_requirements ?? emptyClientRequirements();
const groups = new Map<string, { names: string[] }>();
for (const entry of availability) {
const statusFacts = {
available: entry.available,
reason: entry.reason,
remediation: entry.remediation,
...(entry.value_flow_support === undefined
? {}
: { value_flow_support: entry.value_flow_support }),
...(entry.default_mode_available === undefined
? {}
: { default_mode_available: entry.default_mode_available }),
...(entry.modes === undefined ? {} : { modes: [...entry.modes] }),
...(entry.available || entry.alternatives === undefined
? {}
: { alternatives: [...entry.alternatives] }),
...(JSON.stringify(entry.client_requirements) ===
JSON.stringify(clientRequirements)
? {}
: { client_requirements: entry.client_requirements }),
};
const groupFacts =
detail === "summary"
? statusFacts
: {
surface: entry.surface,
effects: TOOL_EFFECT_NAMES.filter((name) => entry.effects[name]),
annotations: TOOL_ANNOTATION_NAMES.filter(
(name) => entry.annotations[name],
),
...statusFacts,
};
const key = JSON.stringify(groupFacts);
const existing = groups.get(key);
if (existing) existing.names.push(entry.name);
else groups.set(key, { ...groupFacts, names: [entry.name] });
}
const inventory = {
client_requirements: clientRequirements,
groups: [...groups.values()],
};
return detail === "summary"
? toolAvailabilitySummaryInventory.parse(inventory)
: toolAvailabilityInventory.parse(inventory);
}
const availabilityFor = (context: AvailabilityContext): Availability => {
const workflowAvailability = workflowAvailabilityFor(context);
if (
context.targetOpen &&
context.resourceSession &&
context.requiresActiveTarget &&
!isBundleResourceOperation(context.name) &&
(workflowAvailability === null || context.kind === "session")
)
return {
reason: "target_unsupported",
remediation:
"This resource-only session cannot execute this operation. Call open_binary with an executable analysis target.",
};
// 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);
if (target !== null) {
return {
...target,
defaultModeAvailable: false,
modes: NAVIGATION_CONTEXT_MODES.map((mode) => ({
name: mode.name,
available: false,
missing_operations: [...mode.requirements],
remediation: target.remediation,
})),
};
}
const modes = availabilityForModes(
NAVIGATION_CONTEXT_MODES,
"current_selection",
context.descriptors,
);
return modes;
}
const failure = optionalProviderFailureFor(context);
if (failure !== undefined)
return {
reason: "provider_unavailable",
remediation: `Adapter ${failure.providerId} could not load: ${failure.reason}. Repair the adapter installation and restart REA; other capabilities remain available.`,
};
if (workflowAvailability !== null) return workflowAvailability;
const hostDecision = hostAvailability(context);
if (hostDecision !== null) return hostDecision;
const targetDecision = targetAvailability(context);
if (targetDecision !== null) return targetDecision;
return providerAvailability(context);
};
const optionalProviderFailureFor = ({
name,
kind,
policy,
}: AvailabilityContext): OptionalProviderLoadFailure | undefined => {
const failures = policy.optionalProviderLoadFailures;
if (name === "capture_browser_scenario")
return failures?.browserScenarioCapture;
if (kind === "browser-provider") return failures?.browserObservation;
if (name === "capture_electron_scenario")
return failures?.electronActiveObservation;
if (kind === "electron-provider") return failures?.electronObservation;
if (kind === "runtime-provider")
return failures?.javascriptRuntimeObservation;
if (FRIDA_OPERATION_NAMES.has(name)) return failures?.fridaInstrumentation;
return undefined;
};
const workflowAvailabilityFor = (
context: AvailabilityContext,
): Availability | null => {
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
? { reason: "available", remediation: null }
: {
reason: "provider_unavailable",
remediation: capability.reason,
};
}
if (name === "trace_web_module_imports")
return webModuleImportAvailability(policy);
if (name === "inspect_wasm_artifact")
return policy.wasmArtifactEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY. No active binary target is required; tools are checked at execution.",
};
if (kind === "android-provider")
return policy.androidAnalysisAvailability?.status === "available"
? { reason: "available", remediation: null }
: {
reason:
policy.androidAnalysisAvailability?.code === "unsupported_host"
? "unsupported_host"
: policy.androidAnalysisAvailability?.code ===
"runtime_unavailable"
? "provider_unavailable"
: "provider_missing",
remediation:
policy.androidAnalysisAvailability?.remediation ??
"Set REA_JADX_MCP_JAR to the jadx-headless-mcp 0.7.1 release JAR (rea doctor --provider jadx names its download URL and SHA-256) and provide a full JDK on Linux, macOS, or Windows x64 with its matching bundled native controls.",
};
if (kind === "adb-provider")
return ownerProbeAvailability(
policy.adbAnalysisAvailability,
"Set REA_ADB_PATH to a caller-supplied adb executable or make adb available on PATH. This checks the client version only; device and serial availability depend on the request.",
);
if (kind === "apktool-provider")
return ownerProbeAvailability(
policy.apktoolAnalysisAvailability,
"Set REA_APKTOOL_COMMAND to a caller-supplied Apktool executable or make Apktool 2.7.0 or newer available on PATH.",
);
if (kind === "jeb-provider") {
const availability = policy.jebAnalysisAvailability;
if (availability?.status === "available")
return availability.supportedOperations.some(
(operation) => operation === name,
)
? { reason: "available", remediation: null }
: {
reason: "provider_unavailable",
remediation: `The running JEB endpoint does not advertise support for ${name}. Use a JEB client build that provides this operation.`,
};
return ownerProbeAvailability(
availability,
"Start a JEB client serving MCP (GUI client, or headless via its programmatic launcher) and point REA_JEB_MCP_URL at it (default http://127.0.0.1:8425/mcp). REA does not install or launch JEB.",
);
}
const browser = browserProviderAvailability(name, kind, policy);
if (browser !== null) return browser;
if (name === "capture_process_scenario" && !policy.processCaptureEnabled)
return {
reason: "unsupported_host",
remediation: "Run process capture on a supported Linux or macOS host.",
};
if (kind === "application") return { reason: "available", remediation: null };
if (kind === "pcap-provider" || kind === "flutter-provider")
return { reason: "available", remediation: null };
const electron = electronProviderAvailability(name, kind, policy);
if (electron !== null) return electron;
if (kind === "runtime-provider")
return policy.v8InspectorObservationEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"Start REA with its JavaScript runtime provider available.",
};
if (kind === "session")
return (
targetAvailability(context) ?? { reason: "available", remediation: null }
);
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.
*/
const hostRestrictedAvailability = (
policy: AvailabilityPolicy,
feature: HostRestrictedFeature,
enabled: boolean | undefined,
remediation: string,
): Availability => {
if (policy.hostUnsupported?.[feature] === true)
return { reason: "unsupported_host", remediation };
return enabled === true
? { reason: "available", remediation: null }
: { reason: "provider_missing", remediation };
};
const ownerProbeAvailability = (
observation: ProviderAvailability | undefined,
missingRemediation: string,
): Availability => {
if (observation === undefined)
return { reason: "provider_missing", remediation: missingRemediation };
if (observation.status === "available")
return { reason: "available", remediation: null };
return {
reason:
observation.code === "unsupported_host"
? "unsupported_host"
: observation.code === "not_configured"
? "provider_missing"
: "provider_unavailable",
remediation: observation.remediation,
};
};
const electronProviderAvailability = (
name: string,
kind: ToolKind,
policy: AvailabilityPolicy,
): Availability | null => {
if (kind !== "electron-provider") return null;
if (name === "capture_electron_scenario")
return policy.electronAutomationEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"Start REA with the Electron scenario provider available.",
};
return policy.electronObservationEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"Start REA with its Electron observation provider available.",
};
};
const browserProviderAvailability = (
name: string,
kind: ToolKind,
policy: AvailabilityPolicy,
): Availability | null => {
if (name === "capture_browser_scenario")
return policy.browserScenarioEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"Start REA with its browser scenario provider available.",
};
if (kind !== "browser-provider") return null;
return policy.browserObservationEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"Start REA with its browser observation provider available.",
};
};
/**
* Opening another target cannot make an operation run on an unsupported host.
* Composed operations are decided by their requirements, which another
* provider may satisfy.
*/
const hostAvailability = ({
descriptors,
kind,
name,
}: AvailabilityContext): Availability | null => {
if (kind === "enhanced") return null;
const descriptor = descriptors.get(name);
return descriptor?.available === false &&
descriptor.availability_code === "unsupported_host"
? {
reason: "unsupported_host",
remediation: descriptorRemediation(descriptor),
}
: null;
};
const targetAvailability = ({
name,
kind,
targetKind,
targetFormat,
targetOpen,
cleanupRetry,
requiresActiveTarget,
descriptors,
}: AvailabilityContext): Availability | null => {
if (!targetOpen && requiresActiveTarget)
return {
reason: "target_required",
remediation:
cleanupRetry === undefined
? "Call open_binary with a supported local target."
: `${cleanupRetryRemediation(cleanupRetry)} After cleanup succeeds, call open_binary with a supported local target.`,
};
const descriptor = descriptors.get(name);
if (
targetOpen &&
kind !== "enhanced" &&
descriptor?.available === false &&
(descriptor.availability_code === "target_kind_unsupported" ||
descriptor.availability_code === "target_format_unsupported")
)
return {
reason: "target_unsupported",
remediation: descriptorRemediation(descriptor),
};
if (
targetKind !== undefined &&
targetKind !== "executable" &&
targetKind !== "database" &&
(kind === "official-proxy" ||
kind === "enhanced" ||
name === "get_navigation_context" ||
name === "inspect_address_context")
)
return {
reason: "target_unsupported",
remediation:
name === "inspect_address_context"
? "Inventory or extract a native executable, then call open_binary on that executable. An explicit document can still be queried, but its facets may be unavailable."
: "Inventory or extract a native executable, then call open_binary on that executable.",
};
if (
targetOpen &&
MACHO_TARGET_OPERATIONS.has(name) &&
(targetKind !== "executable" || !isMachOFormat(targetFormat))
)
return {
reason: "target_unsupported",
remediation:
"Call open_binary with a Mach-O executable or an app bundle whose main executable is Mach-O.",
};
return null;
};
const providerAvailability = ({
descriptors,
kind,
name,
policy,
isToolAdvertised,
}: AvailabilityContext): Availability => {
if (kind === "enhanced") return composedAvailability(name, descriptors);
const launchFailure =
policy.commandProviderFailures?.[name as ReverseEngineeringOperation];
if (launchFailure !== undefined)
return {
reason: "provider_unavailable",
remediation: launchFailure.remediation,
};
const descriptor = descriptors.get(name);
if (
descriptor === undefined &&
(kind === "artifact-provider" ||
kind === "managed-provider" ||
kind === "native-provider")
)
return { reason: "available", remediation: null };
if (descriptor === undefined) {
const offered = offeredOperationAlternatives(
name,
(alternative) =>
descriptors.get(alternative)?.available === true &&
isToolAdvertised(alternative),
);
return {
reason: "provider_missing",
remediation:
"Install or configure a provider that declares this operation.",
...(offered === undefined ? {} : { alternatives: offered.operations }),
};
}
return descriptor.available
? { reason: "available", remediation: null }
: {
reason: "provider_unavailable",
remediation: descriptorRemediation(descriptor),
};
};
/**
* Prefer the readiness owner's repair instruction. A static capability fact
* declares no separate repair, so its reason remains the only guidance.
*/
const descriptorRemediation = (descriptor: UnavailableDescriptor): string =>
descriptor.remediation ??
descriptor.reason ??
"Choose another target or configured provider.";
const composedAvailability = (
name: string,
descriptors: ReadonlyMap<string, ProviderDescriptor>,
): Availability => {
if (
name === "binary_overview" &&
descriptors.get("read_binary_inventory_summary")?.available === true
)
return { reason: "available", remediation: null };
const requirements = ENHANCED_REQUIREMENTS.get(name);
if (requirements === undefined)
return {
reason: "provider_missing",
remediation: "No provider composition is declared for this operation.",
};
const result =
"modes" in requirements
? availabilityForModes(
requirements.modes,
requirements.defaultMode,
descriptors,
)
: composedAvailabilityFor(requirements, descriptors).availability;
if (name !== "trace_native_values") return result;
const source = descriptors.get("analyze_function");
if (source?.available !== true) return result;
if (source.native_value_flow?.status === "unavailable")
return {
reason:
result.reason === "provider_unavailable" ||
result.reason === "unsupported_host"
? result.reason
: "provider_missing",
remediation: `${source.native_value_flow.reason} Select a provider that can report native value-flow observations; cross-function tracing also needs call-target resolution.${(result.reason === "provider_unavailable" || result.reason === "unsupported_host") && result.remediation !== null ? ` ${result.remediation}` : ""}`,
};
if (
result.reason === "provider_missing" &&
descriptors.get("resolve_native_call_targets") === undefined
)
return {
...result,
remediation:
source.native_value_flow?.status === "supported"
? "A direct trace may still return local value-flow observations with call-resolution unknowns. Configure a provider with resolve_native_call_targets for call resolution and cross-function tracing."
: "Value-flow support is undeclared. A direct trace may return partial results or an unknown. Configure a provider with resolve_native_call_targets for call resolution and cross-function tracing.",
};
return result;
};
/** Evaluate source groups once so discovery and missing-operation facts agree. */
const composedAvailabilityFor = (
requirements: CompositionRequirements,
descriptors: ReadonlyMap<string, ProviderDescriptor>,
): {
readonly availability: Availability;
readonly missingOperations: readonly AnalysisOperation[];
} => {
const unmet = requirements
.flatMap(stageSources)
.filter(
(source): source is RequiredCompositionSource => !optionalSource(source),
)
.map((requirement) => {
const operations = sourceOperations(requirement);
const observations = operations.map((operation) =>
descriptors.get(operation),
);
return {
requirement,
operations,
available: observations.some(
(descriptor) => descriptor?.available === true,
),
unavailable: observations.find(
(descriptor): descriptor is UnavailableDescriptor =>
descriptor?.available === false,
),
};
})
.filter((group) => !group.available);
const missingOperations = [
...new Set(unmet.flatMap((group) => group.operations)),
];
// Preserve the existing admission rule: report an undeclared prerequisite
// before an unhealthy declaration, in requirement order within each class.
const undeclared = unmet.find((group) => group.unavailable === undefined);
if (undeclared !== undefined)
return {
missingOperations,
availability: {
reason: "provider_missing",
remediation:
typeof undeclared.requirement === "string"
? `Configure a provider for required operation ${undeclared.requirement}.`
: `Configure a provider for one of: ${undeclared.operations.join(", ")}.`,
},
};
const unavailable = unmet[0]?.unavailable;
if (unavailable !== undefined)
return {
missingOperations,
availability: {
reason:
unavailable.availability_code === "unsupported_host"
? "unsupported_host"
: "provider_unavailable",
remediation: descriptorRemediation(unavailable),
},
};
return {
availability: { reason: "available", remediation: null },
missingOperations,
};
};
const availabilityForModes = (
declarations: readonly AvailabilityMode[],
defaultMode: string | undefined,
descriptors: ReadonlyMap<string, ProviderDescriptor>,
): Availability => {
const modeResults: AvailabilityModeResult[] = declarations.map((mode) => {
const { availability, missingOperations } = composedAvailabilityFor(
mode.requirements,
descriptors,
);
if (availability.reason === "available")
return {
name: mode.name,
available: true,
reason: availability.reason,
missing_operations: [],
remediation: null,
};
return {
name: mode.name,
available: false,
reason: availability.reason,
missing_operations: [...missingOperations],
remediation: availability.remediation,
};
});
const modes: ToolAvailabilityMode[] = modeResults.map((mode) =>
mode.available
? {
name: mode.name,
available: true,
missing_operations: [],
remediation: null,
}
: {
name: mode.name,
available: false,
missing_operations: [...mode.missing_operations],
remediation: mode.remediation,
},
);
const availableMode = modeResults.find((mode) => mode.available);
const failures = modeResults.flatMap((mode) =>
mode.available ? [] : [mode],
);
const failure = failures.sort(
(left, right) =>
availabilityFailurePriority(left.reason) -
availabilityFailurePriority(right.reason),
)[0];
const specificFailureRemediation =
failure?.reason === "provider_missing" ? undefined : failure?.remediation;
const distinctModeRemediations =
defaultMode === undefined &&
failures.length > 1 &&
new Set(failures.map((mode) => mode.remediation)).size > 1;
const facts = {
...(defaultMode === undefined
? {}
: {
defaultModeAvailable:
modes.find((mode) => mode.name === defaultMode)?.available ?? false,
}),
modes,
};
if (availableMode !== undefined)
return { ...facts, reason: "available", remediation: null };
const missingOperations = [
...new Set(modes.flatMap((mode) => mode.missing_operations)),
];
return {
...facts,
reason: failure?.reason ?? "provider_missing",
remediation: distinctModeRemediations
? MULTI_MODE_REMEDIATION
: (specificFailureRemediation ??
`Configure a provider for one of: ${missingOperations.join(", ")}.`),
};
};
const availabilityFailurePriority = (
reason: ToolAvailabilityReason,
): number => {
switch (reason) {
case "unsupported_host":
return 0;
case "provider_unavailable":
return 1;
case "provider_missing":
return 2;
default:
return 3;
}
};
/** Include operations the selected route can still dispatch, including runtime retries. */
const reachableRequirements = (
requirements: CompositionRequirements,
descriptors: ReadonlyMap<string, ProviderDescriptor>,
): readonly string[] => {
const reached: string[] = [];
for (const stage of requirements) {
let blocked = false;
for (const source of stageSources(stage)) {
const available = sourceOperations(source).filter((operation) => {
const descriptor = descriptors.get(operation);
return (
descriptor?.available === true ||
(descriptor?.available === false &&
descriptor.runtime_unavailable === true)
);
});
reached.push(...available);
if (available.length === 0 && !optionalSource(source)) blocked = true;
}
if (blocked) break;
}
return reached;
};
/** Use the same composition requirements as availability when exposing provider effects. */
const composedEffects = (
name: string,
base: ToolEffects,
descriptors: readonly ProviderDescriptor[],
): ToolEffects => {
const composition: ProviderComposition | undefined =
name === "get_navigation_context"
? { modes: NAVIGATION_CONTEXT_MODES }
: name === "inspect_address_context"
? ADDRESS_CONTEXT_EFFECT_COMPOSITION
: ENHANCED_REQUIREMENTS.get(name);
const byOperation = new Map(
descriptors.map((descriptor) => [descriptor.operation, descriptor]),
);
const reachable =
composition === undefined
? []
: "modes" in composition
? composition.modes.flatMap(({ requirements }) =>
reachableRequirements(requirements, byOperation),
)
: reachableRequirements(composition, byOperation);
const operations = new Set<string>([name, ...reachable]);
const effects = { ...base };
for (const descriptor of descriptors) {
if (!operations.has(descriptor.operation)) continue;
const source = descriptor.effects;
effects.mutatesTarget ||= source.mutates_artifact;
effects.launchesProcess ||= source.launches_process;
effects.changesUiState ||= source.may_show_ui;
effects.accessesNetwork ||= source.may_access_network;
effects.writesFilesystem ||=
source.may_write_filesystem || source.changes_permissions;
}
return effects;
};