Files
reverse-engineering-anything/src/cli/utilityCommands.ts
T
8c7977f174 fix(native)!: require separate inspection for plists outside bundles (#9754)
* fix(native): record inspected plist bytes and refuse files outside the bundle

An open app session keeps the executable as the Evidence subject for
inspect_plist, same as the other bundle-resource tools, but the result had
no digest of the plist bytes and any absolute path was sealed under that
subject. Record source_sha256 for the bytes read, and refuse a selection
that resolves outside the opened bundle.

Fixes #9479

* fix(native)!: scope plist selection to the opened bundle

BREAKING CHANGE: To inspect a plist outside an opened app bundle or resource root, open the plist as a separate target.

* fix(native): report plist snapshot filesystem effects

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-19 21:35:17 -05:00

366 lines
12 KiB
TypeScript

import { contractNamed } from "./contractCliDescription.js";
import { resolveJavaScriptMemberMutationAllowance } from "../config/javascriptMemberMutationAllowance.js";
import { z } from "zod";
import { cliDecimalField } from "./options.js";
import { requirePresence } from "../domain/schemaConstraints.js";
import type { DirectAnalysis } from "../composition/directAnalysis.js";
import { createHistoricalSourceSummary } from "../domain/referenceSourceSummary.js";
import { ArtifactResourceScope } from "../resources/index.js";
import { importReferenceSource } from "../application/ReferenceSourceImport.js";
import {
referenceSourceImportAnalysisError,
type ReferenceSourceImportOptions,
} from "../application/ReferenceSourceImportTypes.js";
import { err } from "../domain/result.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
import { parseConfig } from "../config/parseConfig.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import {
AnalysisInputError,
type AnalysisInputIssue,
} from "../domain/analysisErrorCore.js";
import { projectInputIssues } from "../domain/inputIssueProjection.js";
import { safeParseJson } from "../domain/safeJson.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { isCliOperationFailure, logCliCommand } from "../cliLogging.js";
import { CLI_COMMANDS, cliCommandFor } from "../contracts/cliCommandNames.js";
import { localPathStringSchema } from "../domain/localPath.js";
import type { Logger } from "pino";
import { registerCliCommand } from "./commandRegistry.js";
import type { CliInstance } from "./types.js";
import { registerNativeCallCommands } from "./nativeCallCommands.js";
import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
import {
registerContractCommand,
runOnSessionTarget,
} from "./contractCommand.js";
export const registerUtilityCommands = (
cli: CliInstance,
logger: Logger,
environment: Readonly<Record<string, string | undefined>>,
analysis: Pick<DirectAnalysis, "runProviderAnalysis" | "runSessionStatus">,
): void => {
const { runProviderAnalysis } = analysis;
const run = runOnSessionTarget(runProviderAnalysis, logger);
registerCapabilityCommands(cli, logger, analysis);
registerNativeCommands(cli, logger, runProviderAnalysis);
registerNativeCallCommands(cli, logger, runProviderAnalysis);
registerNativeUiCommands(cli, logger, run);
registerReferenceSourceCommand(cli, logger, environment);
};
/**
* Passive observation and active scenarios have different input contracts.
* Only the scenario command accepts steps, so passive observation rejects
* them as an unknown flag instead of silently dropping them.
*/
const registerNativeUiCommands = (
cli: CliInstance,
logger: Logger,
run: ReturnType<typeof runOnSessionTarget>,
): void => {
const sessionTarget = { description: "Local native executable or app path" };
const fields = {
pid: { description: "Existing application PID" },
window_id: { description: "Exact selected application window ID" },
max_nodes: { description: "Maximum accessibility nodes per capture" },
} as const;
registerContractCommand(
cli,
logger,
contractNamed(NATIVE_TOOL_CONTRACTS, "observe_native_ui"),
{
description:
"Observe one already-running native application window by PID and window ID",
sessionTarget,
fields,
},
run,
);
registerContractCommand(
cli,
logger,
contractNamed(NATIVE_TOOL_CONTRACTS, "capture_native_ui_scenario"),
{
description:
"Run declarative AX actions or waits in one exact native application window",
sessionTarget,
runtimeJson: { steps: "steps must be valid JSON" },
fields: {
...fields,
steps: {
description:
"Required JSON array of one or more declarative AX actions or waits",
},
},
},
run,
);
};
const registerCapabilityCommands = (
cli: CliInstance,
logger: Logger,
{ runSessionStatus }: Pick<DirectAnalysis, "runSessionStatus">,
): void => {
for (const command of [
CLI_COMMANDS.capabilities,
CLI_COMMANDS.providers,
] as const) {
registerCliCommand(cli, command, {
description:
command === "capabilities"
? "List provider capabilities and side effects"
: "List configured analysis providers",
run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
});
}
};
const registerNativeCommands = (
cli: CliInstance,
logger: Logger,
runProviderAnalysis: DirectAnalysis["runProviderAnalysis"],
): void => {
const run = runOnSessionTarget(runProviderAnalysis, logger);
const machoTarget = { description: "Mach-O or app path" };
registerContractCommand(
cli,
logger,
contractNamed(NATIVE_TOOL_CONTRACTS, "inspect_macho"),
{
description: "Run inspect_macho without launching Hopper",
sessionTarget: machoTarget,
evidenceDelivery: true,
},
run,
);
for (const [command, tool] of [
[cliCommandFor("inspect_signature"), "inspect_signature"],
[cliCommandFor("list_architectures"), "list_architectures"],
] as const)
registerContractCommand(
cli,
logger,
contractNamed(NATIVE_TOOL_CONTRACTS, tool),
{
command,
description: `Run ${tool} without launching Hopper`,
sessionTarget: machoTarget,
},
run,
);
registerContractCommand(
cli,
logger,
contractNamed(NATIVE_TOOL_CONTRACTS, "inspect_plist"),
{
description: "Parse app plist metadata without launching Hopper",
sessionTarget: { description: "App, Mach-O or plist path" },
fields: {
path: {
name: "relativePath",
description:
"Plist path relative to the app root, or an absolute path within the opened bundle (default: its Info.plist)",
},
},
},
run,
);
registerContractCommand(
cli,
logger,
contractNamed(NATIVE_TOOL_CONTRACTS, "demangle_swift"),
{
description: "Demangle Swift symbols without Hopper",
sessionTarget: {
description: "Artifact path used for evidence identity",
},
positionals: ["symbols"],
fields: {
symbols: { description: "Swift mangled symbols to demangle" },
},
},
run,
);
};
const referenceSourceExcludePathsSchema = z.object({
excludePaths: z.array(z.string().min(1)),
});
const EXCLUDE_PATHS_INPUT_MESSAGE =
"--exclude-paths must be a JSON array of nonempty Git-ignore rules. Each rule uses Git-ignore syntax, including wildcards, directory suffixes, and negations, rather than a literal path match.";
const invalidReferenceSourceExcludePaths = (
issues: readonly AnalysisInputIssue[],
) => ({
error: "Import failed" as const,
...projectAnalysisError(
new AnalysisInputError(
CLI_COMMANDS.importReferenceSource,
{ userMessage: EXCLUDE_PATHS_INPUT_MESSAGE },
issues,
),
),
});
/** Parse caller exclusions before the import opens the selected tree. */
const parseReferenceSourceExcludePaths = (
encoded: string | undefined,
):
| {
readonly ok: true;
readonly rules: readonly string[] | undefined;
}
| {
readonly ok: false;
readonly failure: ReturnType<typeof invalidReferenceSourceExcludePaths>;
} => {
if (encoded === undefined) return { ok: true, rules: undefined };
const decoded = safeParseJson(encoded);
if (!decoded.ok)
return {
ok: false,
failure: invalidReferenceSourceExcludePaths([
{
path: ["excludePaths"],
reason: "invalid_format",
expected: "JSON",
},
]),
};
const parsed = referenceSourceExcludePathsSchema.safeParse({
excludePaths: decoded.value,
});
if (!parsed.success)
return {
ok: false,
failure: invalidReferenceSourceExcludePaths(
projectInputIssues(parsed.error.issues, {
excludePaths: decoded.value,
}),
),
};
return { ok: true, rules: parsed.data.excludePaths };
};
const registerReferenceSourceCommand = (
cli: CliInstance,
logger: Logger,
environment: Readonly<Record<string, string | undefined>>,
): void => {
registerCliCommand(cli, CLI_COMMANDS.importReferenceSource, {
description: "Import a source tree as historical reference only",
args: z.object({
root: localPathStringSchema.describe(
"Local source directory to import as historical reference",
),
}),
options: requirePresence(
z.object({
excludePaths: z
.string()
.optional()
.describe(
"JSON array of Git-ignore rules to exclude. Rules use Git-ignore syntax, including wildcards, directory suffixes, and negations; they are not literal path matches. An empty array adds no caller exclusions.",
),
detail: z
.enum(["full", "summary"])
.default("full")
.describe(
"Complete committed graph or compact historical-source summary",
),
outlineDepth: cliDecimalField(
z
.int()
.min(0)
.optional()
.describe(
"Summary outline path depth (default: 2; 0 omits entries); requires --detail summary",
),
),
}),
[
{
when: "outlineDepth",
requires: "detail",
requiresValue: "summary",
message: "--outline-depth requires --detail summary",
},
],
),
run: ({ args, options }) =>
logCliCommand(
logger,
"import-reference-source",
async () => {
const excludePaths = parseReferenceSourceExcludePaths(
options.excludePaths,
);
if (!excludePaths.ok) return excludePaths.failure;
const config = parseConfig(environment);
if (!config.ok)
return {
error: "Import failed",
...projectAnalysisError(config.error),
};
const memberMutationAllowance =
resolveJavaScriptMemberMutationAllowance(environment);
if (!memberMutationAllowance.ok)
return {
error: "Import failed",
...projectAnalysisError(memberMutationAllowance.error),
};
return withCommandCancellation((signal) =>
runReferenceSourceImport(
{
root: args.root,
memberMutationAllowance: memberMutationAllowance.value,
caller: "rea-cli",
policy: config.value.referenceSourcePolicy,
importer: PRODUCT_IDENTITY.packageName,
importerVersion: PRODUCT_IDENTITY.packageVersion,
signal,
...(excludePaths.rules === undefined
? {}
: { excludePaths: excludePaths.rules }),
},
options.detail === "summary"
? (options.outlineDepth ?? 2)
: undefined,
),
);
},
isCliOperationFailure,
),
});
};
const runReferenceSourceImport = async (
options: ReferenceSourceImportOptions & { readonly signal: AbortSignal },
outlineDepth: number | undefined,
): Promise<unknown> => {
const resources = new ArtifactResourceScope();
const result = await finishAnalysisCommand(
async () => {
const imported = await importReferenceSource(options, resources);
return imported.ok
? imported
: err(referenceSourceImportAnalysisError(imported.error));
},
resources,
"filesystem",
"import_reference_source",
options.signal,
"reference source",
);
if (!result.ok) return { error: "Import failed", ...result.error };
return outlineDepth === undefined
? result.value
: createHistoricalSourceSummary(result.value, outlineDepth);
};