rea-agents 4.0.1 → 5.0.0

package/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -9,10 +9,25 @@ cross-references. Addresses and recovered pseudocode are analysis observations,
 not original source. Provider unavailability and unsupported metadata remain
 unknown rather than false.
 
-Use `binary_session` with its default summary to check the open target, selected
-provider, alignment, and recommended remediation. Request the capabilities view
-with a family filter and page bounds only when choosing a tool. Request the full
-view only for an explicit session-diagnostic need.
+Use `binary_session` with no arguments to check the open target, selected
+provider, and alignment. Its default `result.tool_availability` includes the
+complete tool inventory with availability reasons and remediation. When choosing
+a tool, use its entry in that result; `tools/list` retains the complete catalog
+when the target or provider state changes.
+
+## DOS MZ with Ghidra
+
+For an admitted DOS MZ target, use `inspect_native_load_image` to check measured
+loaded bytes, file mappings, relocations and the entry against the immutable
+snapshot. Keep `mismatch` and `unsupported` explicit. Verified import covers the
+reported static image, not runtime DOS or PC-98 hardware behavior.
+
+Use `read_bytes` for initialized analysis memory and `address_to_file_offset` to
+anchor one observed address to original file bytes. Loader fixups can change a
+word; a source offset does not imply byte equality. Complete function body ranges
+use inclusive ends and can contain gaps. Do not treat the enclosing span as code.
+For packed targets, retain the original and separately derived artifact identities;
+decompiling an unpacking stub does not recover the unpacked program.
 
 ## Managed PE/CLI
 
@@ -22,6 +37,31 @@ assembly. Keep managed/native boundaries and unavailable reconstruction facts
 explicit. A bring-your-own reconstruction oracle is separate from the canonical
 parser and must not become an implicit setup dependency.
 
+### .NET NativeAOT
+
+NativeAOT binaries contain native machine code, so ordinary CIL decompilers
+cannot recover the original method bodies. When managed metadata/CIL is absent,
+classify that as a native-analysis route rather than claiming source recovery.
+Open the native image with the selected deep provider and inspect functions,
+strings, calls, and references; describe decompiler output as pseudocode and
+inference.
+
+NativeAOT images can be PE/COFF, ELF, or Mach-O executables and shared
+libraries. Use file bytes and loader metadata rather than suffixes to identify
+them. For packaged apps, inventory/extract with REA's artifact tools and retain
+the exact contained image identity. PDB, ELF debug, or dSYM sidecars are
+additional evidence only when the provider accepts and matches them.
+
+For deeper type recovery, the optional third-party
+[Ghidra NativeAOT analyzer](https://github.com/Washi1337/ghidra-nativeaot)
+rehydrates ReadyToRun metadata and can recover method tables, type relationships,
+frozen objects, and strings. This is a Ghidra extension with its own install and
+interactive workflow; it is not currently part of REA's managed parser or
+headless Ghidra bridge. Treat its annotations as analysis evidence, retain the
+binary identity, and do not present recovered types as original source. Header
+discovery may require a symbol or analyst identification of the ReadyToRun
+header, depending on the binary and analyzer version.
+
 ## Packages and extraction
 
 Use `inspect_artifact` for application bundles, archives, ZIP/APK/IPA/MSIX/AppX,
@@ -29,6 +69,14 @@ ASAR, or DMG inputs when the artifact graph and findings help answer the
 question. It returns the complete artifact graph inline. Cite graph manifest
 IDs when using them.
 
+For an IPA or a macOS `.app`, ZIP, or DMG, pass the inventory Evidence to
+`project_apple_application_graph`. It reports application roots and nested
+bundles by path convention: app extensions, XPC services, frameworks, login
+items, system and driver extensions, and plug-ins. It also lists privileged
+helpers, launchd plists, symlinks, and each bundle's `info_plist_path` and
+executable candidates. Roles are path conventions, not parsed plists; read the
+listed plists with `inspect_plist`.
+
 Use `extract_artifact` when materialized files are needed. It takes no arguments
 and materializes all regular files into a fresh temporary directory chosen by
 REA. Symlinks and encrypted entries are inventory facts, not extractable files.
@@ -40,3 +88,12 @@ hosts, with an owned temporary mount directory and cleanup. It needs no approval
 flag. Unsupported hosts or mount failures remain explicit limitations; do not
 claim child inventory when only root identity is available. Extraction is a
 separate filesystem-writing operation.
+
+For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
+`--target-format dos-com`). Inspect the load image before trusting function
+analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
+context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
+
+### Function annotations in Ghidra
+
+Use `annotate_native_function` for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI `annotate-native-function` returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations.

package/dist/application/JavaScriptApplicationService.js

@@ -1,52 +0,0 @@
-import { z } from "zod";
-import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
-import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
-import { AnalysisInputError, AnalysisProtocolError, ArtifactOperationError, } from "../domain/errors.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
-import { err, ok } from "../domain/result.js";
-import { createJavaScriptApplicationEvidence } from "./JavaScriptApplicationEvidence.js";
-import { reconstructJavaScriptArtifact } from "./JavaScriptArtifactReconstruction.js";
-const OPERATION = "analyze_javascript_application";
-/** Statically analyze one local JavaScript/Electron application. */
-export const analyzeJavaScriptApplication = async (rawInput, options = {}) => {
-    const parsed = analyzeJavaScriptApplicationInputSchema.safeParse(rawInput);
-    if (!parsed.success)
-        return err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(parsed.error.issues, rawInput)));
-    return analyzeJavaScriptApplicationValidated(parsed.data, options);
-};
-/** Analyze input already parsed by a trusted adapter boundary. */
-export const analyzeJavaScriptApplicationValidated = async (input, options = {}) => {
-    await options.progress?.report({
-        phase: "analyze_javascript_application",
-        completed: 0,
-        total: 1,
-        message: "Inventorying and parsing application artifacts",
-    });
-    try {
-        const reconstructed = await reconstructJavaScriptArtifact({
-            input_path: input.input_path,
-            format: input.format,
-        }, options.signal);
-        const { electron_summary: summary, ...application } = reconstructed;
-        const result = javascriptApplicationAnalysisResultSchema.parse({
-            ...application,
-            summary,
-            limitations: reconstructed.graph.limitations,
-        });
-        await options.progress?.report({
-            phase: "analyze_javascript_application",
-            completed: 1,
-            total: 1,
-            message: "Application graph and Electron boundaries reconstructed",
-            terminal: true,
-        });
-        return ok(createJavaScriptApplicationEvidence(input, result));
-    }
-    catch (cause) {
-        if (cause instanceof ArtifactReaderFailure)
-            return err(new ArtifactOperationError(OPERATION, cause.reason, cause.details));
-        if (cause instanceof z.ZodError)
-            return err(new AnalysisProtocolError("JavaScript application analysis produced an invalid result", { cause }));
-        return err(new ArtifactOperationError(OPERATION, "io"));
-    }
-};

package/dist/application/runtime.js

@@ -1,51 +0,0 @@
-import { HopperProvider } from "../hopper/HopperProvider.js";
-import { GhidraProvider } from "../ghidra/GhidraProvider.js";
-import { silentLogger } from "../logger.js";
-import { GENERATED_AUXILIARY_PROVIDERS } from "../generatedMcpToolCatalog.js";
-import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
-import { composeBinarySession } from "./BinarySessionComposition.js";
-import { nativeHostCapabilities } from "../native/NativeHostCapabilities.js";
-import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
-import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
-import { SessionProviderRouter } from "./SessionProviderRouter.js";
-/**
- * Compose the target-switching runtime shared directly by CLI and MCP adapters.
- * This is the sole production wiring point, so both adapters share identical
- * provider selection, profile, lifecycle, and Evidence semantics.
- */
-export const createBinarySession = (config, logger = silentLogger) => {
-    const hopper = new HopperProvider(config, logger);
-    const ghidra = new GhidraProvider(config, logger);
-    const auxiliary = new Map(GENERATED_AUXILIARY_PROVIDERS.map((provider) => [
-        provider.identity.id,
-        provider,
-    ]));
-    const lazyProvider = (id, load) => {
-        const generated = auxiliary.get(id);
-        if (generated === undefined)
-            throw new TypeError(`Missing generated provider metadata for ${id}`);
-        return new LazyAnalysisProvider({
-            ...generated,
-            capabilities: nativeHostCapabilities(generated.capabilities),
-            load,
-        });
-    };
-    return composeBinarySession(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
-        lazyProvider("rea-artifact-graph", async () => {
-            const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
-            return new ArtifactProvider();
-        }),
-        lazyProvider("native-macos", async () => {
-            const { NativeMacOSProvider } = await import("../native/NativeMacOSProvider.js");
-            return new NativeMacOSProvider();
-        }),
-        lazyProvider("rea-dotnet-static", async () => {
-            const { ManagedStaticProvider } = await import("../dotnet/ManagedStaticProvider.js");
-            return new ManagedStaticProvider();
-        }),
-    ]);
-};
-/** Compose an execution-free managed session without native provider selection. */
-export const createManagedBinarySession = () => composeBinarySession(SessionProviderRouter.selectable(new AnalysisProviderRegistry([]), [
-    new ManagedStaticProvider(),
-]));

package/dist/browser/CdpCanonicalJsonDigest.js

@@ -1,9 +0,0 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
-/** Hash a value using the canonical JSON representation. */
-export const canonicalJsonDigest = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Expected canonical JSON");
-    return createHash("sha256").update(encoded).digest("hex");
-};

package/dist/domain/appleApplication.js

@@ -1,181 +0,0 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
-import { z } from "zod";
-import { parseArtifactInventoryEvidence } from "./artifactInventoryEvidence.js";
-import { evidenceSchema } from "./evidence.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
-const evidenceIdSchema = prefixedDigestSchema("ev");
-const pathSchema = z.string().min(1);
-const componentSchema = z.strictObject({
-    path: pathSchema,
-    artifact_id: prefixedDigestSchema("art"),
-    sha256: digestSchema,
-    format: z.string().min(1),
-});
-/** Authenticated artifact inventory pages projected as one Apple application. */
-export const appleApplicationProjectionInputSchema = z.strictObject({
-    inventory_evidence: z.array(evidenceSchema).min(1),
-});
-/** Deterministic, execution-free Apple application inventory projection. */
-export const appleApplicationProjectionResultSchema = z.strictObject({
-    projection_id: prefixedDigestSchema("aap"),
-    root_sha256: digestSchema,
-    root_format: z.literal("ipa"),
-    source_evidence_ids: z.array(evidenceIdSchema).min(1),
-    application_roots: z.array(pathSchema),
-    components: z.strictObject({
-        bundle_metadata: z.array(componentSchema),
-        executables: z.array(componentSchema),
-        frameworks: z.array(componentSchema),
-        native_libraries: z.array(componentSchema),
-        javascript: z.array(componentSchema),
-        signing: z.array(componentSchema),
-    }),
-    runtime_families: z.array(z.enum([
-        "native",
-        "swift-objective-c",
-        "javascript",
-        "react-native",
-        "flutter",
-        "unity",
-    ])),
-    bridge_candidates: z.array(z.strictObject({
-        source_path: pathSchema,
-        native_path: pathSchema,
-        basis: z.enum([
-            "javascript-and-native-content",
-            "react-native-convention",
-            "flutter-convention",
-            "unity-convention",
-        ]),
-    })),
-    coverage: z.strictObject({
-        status: z.enum(["complete-within-inventory", "partial"]),
-        inventory_complete: z.boolean(),
-    }),
-    limitations: z.array(z.string().min(1)),
-});
-/** Project exact IPA paths and hashes without parsing or executing target code. */
-export const projectAppleApplication = (input) => {
-    const parsed = appleApplicationProjectionInputSchema.parse(input);
-    const { evidence, inventory } = parseArtifactInventoryEvidence(parsed.inventory_evidence);
-    if (inventory.manifest.root_format !== "ipa")
-        throw new TypeError("Apple application projection requires IPA Evidence");
-    const nodes = new Map(inventory.nodes.map((node) => [node.artifact_id, node]));
-    const all = inventory.occurrences
-        .filter((occurrence) => occurrence.artifact_id !== null && occurrence.logical_path !== ".")
-        .map((occurrence) => {
-        const node = nodes.get(occurrence.artifact_id ?? "");
-        if (node === undefined)
-            throw new TypeError("Apple application occurrence has no artifact node");
-        return {
-            path: occurrence.logical_path,
-            artifact_id: node.artifact_id,
-            sha256: node.sha256,
-            format: node.format,
-        };
-    });
-    const roots = [
-        ...new Set(inventory.occurrences.flatMap(({ logical_path: path }) => {
-            const match = /^(Payload\/[^/]+\.app)(?:\/|$)/u.exec(path);
-            return match?.[1] === undefined ? [] : [match[1]];
-        })),
-    ].sort(compare);
-    const classified = classifyComponents(all, roots);
-    const runtimeFamilies = identifyRuntimeFamilies(all);
-    const bridgeProjection = identifyBridgeCandidates(classified.javascript, deduplicateComponents([
-        ...classified.executables,
-        ...classified.native_libraries,
-    ]));
-    const limitations = projectionLimitations(inventory.complete, roots);
-    const withoutId = {
-        root_sha256: inventory.manifest.root_sha256,
-        root_format: "ipa",
-        source_evidence_ids: evidence
-            .map(({ evidence_id: id }) => id)
-            .sort(compare),
-        application_roots: roots,
-        components: classified,
-        runtime_families: runtimeFamilies,
-        bridge_candidates: bridgeProjection.candidates,
-        coverage: {
-            status: inventory.complete
-                ? "complete-within-inventory"
-                : "partial",
-            inventory_complete: inventory.complete,
-        },
-        limitations,
-    };
-    return appleApplicationProjectionResultSchema.parse({
-        ...withoutId,
-        projection_id: `aap_${digest(withoutId)}`,
-    });
-};
-const classifyComponents = (all, roots) => {
-    const withinApp = (path) => roots.some((root) => path.startsWith(`${root}/`));
-    return {
-        bundle_metadata: all.filter(({ path }) => /(?:^|\/)Info\.plist$/u.test(path)),
-        executables: all.filter(({ path, format }) => withinApp(path) && ["mach-o", "mach-o-universal"].includes(format)),
-        frameworks: all.filter(({ path }) => /\.framework\//u.test(path)),
-        native_libraries: all.filter(({ path }) => /\.(?:dylib|so)$/iu.test(path)),
-        javascript: all.filter(({ format }) => format === "javascript-bundle"),
-        signing: all.filter(({ path }) => /(?:^|\/)(?:embedded\.mobileprovision|_CodeSignature\/CodeResources)$/u.test(path)),
-    };
-};
-const deduplicateComponents = (values) => [...new Map(values.map((value) => [value.path, value])).values()].sort((left, right) => compare(left.path, right.path));
-const identifyRuntimeFamilies = (all) => {
-    const paths = all.map(({ path }) => path.toLowerCase());
-    const families = new Set();
-    if (all.some(({ format }) => ["mach-o", "mach-o-universal"].includes(format)))
-        families.add("native");
-    if (paths.some((path) => /\.(?:dylib|framework\/[^/]+)$/u.test(path)))
-        families.add("swift-objective-c");
-    if (all.some(({ format }) => format === "javascript-bundle"))
-        families.add("javascript");
-    if (paths.some((path) => path.includes("reactnative") ||
-        path.includes("react.framework") ||
-        path.includes("hermes")))
-        families.add("react-native");
-    if (paths.some((path) => path.includes("flutter.framework") || path.includes("app.framework")))
-        families.add("flutter");
-    if (paths.some((path) => path.includes("unityframework.framework")))
-        families.add("unity");
-    return [...families].sort(compare);
-};
-const identifyBridgeCandidates = (scripts, native) => ({
-    candidates: scripts.flatMap((script) => native.map((item) => ({
-        source_path: script.path,
-        native_path: item.path,
-        basis: bridgeBasis(item.path),
-    }))),
-});
-const bridgeBasis = (path) => {
-    const lower = path.toLowerCase();
-    if (lower.includes("react"))
-        return "react-native-convention";
-    if (lower.includes("flutter") || lower.includes("app.framework"))
-        return "flutter-convention";
-    if (lower.includes("unity"))
-        return "unity-convention";
-    return "javascript-and-native-content";
-};
-const projectionLimitations = (complete, roots) => [
-    ...(!complete
-        ? ["Source inventory pages are incomplete; absence is unknown."]
-        : []),
-    ...(roots.length === 0
-        ? [
-            "No Payload/*.app directory was present in the supplied inventory pages.",
-        ]
-        : []),
-    "Bundle identifiers and signing claims require dedicated plist and CMS parsing; this projection reports only exact paths and hashes.",
-    "Bridge candidates are path-based hypotheses, not observed runtime calls.",
-];
-const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
-const digest = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Apple application projection is not canonical JSON");
-    return createHash("sha256").update(encoded).digest("hex");
-};