diff --git a/README.md b/README.md index 3641c45ca..dc8cd7d1f 100644 --- a/README.md +++ b/README.md @@ -376,7 +376,7 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its | Native inspection | 33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations | | Investigation workflows | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery | | Native macOS utilities | 5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing | -| Artifact graph | 2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree | +| Artifact graph | 2 | deterministic directory, ZIP/APK/IPA/MSIX/AppX, and ASAR inventory; explicitly selected extraction into an absent owned tree | | Managed PE/CLI | 8 | PE/CLI identity, metadata members, CIL hashes, P/Invoke/native-boundary declarations and verification, application-graph projection, decompiler reconstruction import, token remapping, runtime-correlation plans, and version comparison | | Browser observation | 8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence | | Electron analysis | 4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation | diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md index 0958d96de..157b8fd88 100644 --- a/skills/reverse-engineer-anything/SKILL.md +++ b/skills/reverse-engineer-anything/SKILL.md @@ -22,7 +22,8 @@ Choose the first tool from the target the user supplied. Do not call - ASAR or extracted JavaScript/Electron tree: `analyze_javascript_application`. -- Archive, application package, ZIP/APK/IPA, or DMG: `inventory_artifact`. +- Archive, application package, ZIP/APK/IPA/MSIX/AppX, or DMG: + `inventory_artifact`. - Managed PE/CLI assembly: `inspect_managed_artifact`. - User-owned browser page already open: `list_browser_targets`. - User-owned Electron runtime already open: `list_electron_targets`. diff --git a/skills/reverse-engineer-anything/references/native-and-artifacts.md b/skills/reverse-engineer-anything/references/native-and-artifacts.md index 952ee6ef7..a98ea81c2 100644 --- a/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -24,8 +24,8 @@ parser and must not become an implicit setup dependency. ## Packages and extraction Call `inventory_artifact` before extraction for application bundles, archives, -ZIP/APK/IPA, ASAR, or DMG inputs. Continue deterministic occurrence pages from -the returned offset only when needed. Cite graph manifest IDs. +ZIP/APK/IPA/MSIX/AppX, ASAR, or DMG inputs. Continue deterministic occurrence +pages from the returned offset only when needed. Cite graph manifest IDs. `extract_artifact` requires explicit approval, an absent absolute output root, and selected occurrence IDs. Never extract every entry implicitly. Symlinks and diff --git a/src/application/ArtifactExtraction.ts b/src/application/ArtifactExtraction.ts index ad8170363..bd6e33845 100644 --- a/src/application/ArtifactExtraction.ts +++ b/src/application/ArtifactExtraction.ts @@ -269,7 +269,13 @@ const createReader = async ( if ((await lstat(path)).isDirectory()) return new DirectoryArtifactReader(path); if (format === "asar") return new AsarArtifactReader(path); - if (format === "ipa" || format === "apk" || format === "zip") + if ( + format === "ipa" || + format === "apk" || + format === "msix" || + format === "appx" || + format === "zip" + ) return new ZipArtifactReader(path, format); if (format === "mach-o") return new MachOSliceArtifactReader(path); throw new ArtifactReaderFailure( diff --git a/src/application/ArtifactGraphConstruction.ts b/src/application/ArtifactGraphConstruction.ts index fd7afe0dc..c96647d1f 100644 --- a/src/application/ArtifactGraphConstruction.ts +++ b/src/application/ArtifactGraphConstruction.ts @@ -1,5 +1,4 @@ import { createHash } from "node:crypto"; -import { extname } from "node:path"; import canonicalize from "canonicalize"; @@ -13,6 +12,7 @@ import type { ArtifactNode, ArtifactOccurrence, } from "../domain/artifactGraph.js"; +import { zipPackageFormatForPath } from "../domain/zipPackageFormat.js"; /** Mutable internal occurrence used until root-bound IDs are known. */ export interface MutableOccurrence { @@ -130,7 +130,9 @@ export const createRootNode = (input: { size: input.digest?.bytes ?? 0, kind: input.directory || - ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(input.format) + ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes( + input.format, + ) ? "container" : classifyArtifactPath(input.path).kind, format: input.format, @@ -264,7 +266,7 @@ export const classifyArtifactPath = ( if (/\.(?:m?js|cjs)$/u.test(lower)) return { kind: "javascript", format: "javascript-bundle" }; if (lower.endsWith(".asar")) return { kind: "container", format: "asar" }; - const archiveFormat = archiveFormatForExtension(extname(lower)); + const archiveFormat = zipPackageFormatForPath(lower); if (archiveFormat !== undefined) return { kind: "container", format: archiveFormat }; if (/\.framework(?:\/|$)/u.test(lower)) @@ -351,19 +353,4 @@ const relationFor = (path: string): ArtifactEdge["relation"] => { return "contains"; }; -const archiveFormatForExtension = ( - extension: string, -): "zip" | "ipa" | "apk" | undefined => { - switch (extension) { - case ".zip": - return "zip"; - case ".ipa": - return "ipa"; - case ".apk": - return "apk"; - default: - return undefined; - } -}; - const depth = (path: string): number => path.split("/").length; diff --git a/src/application/ArtifactInventory/classify.ts b/src/application/ArtifactInventory/classify.ts index bf36c9a65..975d9f52d 100644 --- a/src/application/ArtifactInventory/classify.ts +++ b/src/application/ArtifactInventory/classify.ts @@ -2,12 +2,15 @@ import { open } from "node:fs/promises"; import { classifyArtifactPath } from "../ArtifactGraphConstruction.js"; import type { ArtifactNode } from "../../domain/artifactGraph.js"; +import { zipPackageFormatForPath } from "../../domain/zipPackageFormat.js"; const classifyContainerExtension = ( path: string, ): ArtifactNode["format"] | undefined => { const lower = path.toLowerCase(); - for (const format of ["asar", "ipa", "apk", "zip", "dmg", "pkg"] as const) + const zipPackage = zipPackageFormatForPath(lower); + if (zipPackage !== undefined) return zipPackage; + for (const format of ["asar", "dmg", "pkg"] as const) if (lower.endsWith(`.${format}`)) return format; return undefined; }; diff --git a/src/application/ArtifactInventory/reader.ts b/src/application/ArtifactInventory/reader.ts index 09f5986b3..c1630c756 100644 --- a/src/application/ArtifactInventory/reader.ts +++ b/src/application/ArtifactInventory/reader.ts @@ -22,6 +22,8 @@ export const createReader = async ( case "zip": case "ipa": case "apk": + case "msix": + case "appx": return new ZipArtifactReader(path, format); case "asar": return new AsarArtifactReader(path); diff --git a/src/artifacts/ArtifactReader.ts b/src/artifacts/ArtifactReader.ts index 3c9790d58..ff85c614f 100644 --- a/src/artifacts/ArtifactReader.ts +++ b/src/artifacts/ArtifactReader.ts @@ -1,5 +1,6 @@ import type { Readable } from "node:stream"; import type { ArtifactCommand } from "../domain/artifactGraph.js"; +import type { ZipPackageFormat } from "../domain/zipPackageFormat.js"; /** Archive-neutral entry metadata. Reader adapters never choose output paths. */ export interface ArtifactEntry { @@ -23,7 +24,7 @@ export interface ArtifactEntry { /** Read-only adapter over one directory, archive, or virtual container. */ export interface ArtifactReader { - readonly format: "directory" | "zip" | "ipa" | "apk" | "asar" | "file"; + readonly format: "directory" | ZipPackageFormat | "asar" | "file"; entries(signal?: AbortSignal): AsyncIterable; open(entry: ArtifactEntry, signal?: AbortSignal): Promise; provenance(): readonly ArtifactCommand[]; diff --git a/src/artifacts/ZipArtifactReader.ts b/src/artifacts/ZipArtifactReader.ts index c01813303..ae1bb7710 100644 --- a/src/artifacts/ZipArtifactReader.ts +++ b/src/artifacts/ZipArtifactReader.ts @@ -9,6 +9,7 @@ import { type ArtifactEntry, type ArtifactReader, } from "./ArtifactReader.js"; +import type { ZipPackageFormat } from "../domain/zipPackageFormat.js"; class NodeFileReader extends Reader { #handle: FileHandle | undefined; @@ -41,12 +42,12 @@ class NodeFileReader extends Reader { /** Lazy Zip64-capable reader with CRC and overlap verification on every read. */ export class ZipArtifactReader implements ArtifactReader { - readonly format: "zip" | "ipa" | "apk"; + readonly format: ZipPackageFormat; readonly #source: NodeFileReader; readonly #reader: ZipReader; readonly #entries = new Map(); - constructor(path: string, format: "zip" | "ipa" | "apk") { + constructor(path: string, format: ZipPackageFormat) { this.format = format; this.#source = new NodeFileReader(path); this.#reader = new ZipReader(this.#source, { diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.ts index 79b5e0f71..640b3bc2d 100644 --- a/src/contracts/toolOutputSchemaPrimitives.ts +++ b/src/contracts/toolOutputSchemaPrimitives.ts @@ -45,6 +45,8 @@ export const targetFormatSchema = z.enum([ "zip", "ipa", "apk", + "msix", + "appx", "asar", "dmg", "pkg", diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts index 94d891150..526e5f364 100644 --- a/src/domain/analysisSnapshot.ts +++ b/src/domain/analysisSnapshot.ts @@ -37,6 +37,8 @@ const formatSchema = z.enum([ "zip", "ipa", "apk", + "msix", + "appx", "asar", "dmg", "pkg", diff --git a/src/domain/artifactGraph.ts b/src/domain/artifactGraph.ts index 74abb2288..487b29ff1 100644 --- a/src/domain/artifactGraph.ts +++ b/src/domain/artifactGraph.ts @@ -52,6 +52,8 @@ const artifactFormatSchema = z.enum([ "analysis-database", "ipa", "apk", + "msix", + "appx", "plist", "entitlements", "directory", diff --git a/src/domain/binaryTarget.ts b/src/domain/binaryTarget.ts index 85ba4a8c9..da2363340 100644 --- a/src/domain/binaryTarget.ts +++ b/src/domain/binaryTarget.ts @@ -14,6 +14,7 @@ import { promisify } from "node:util"; import { BinaryTargetError } from "./errors.js"; import { err, ok, type Result } from "./result.js"; +import { zipPackageFormatForPath } from "./zipPackageFormat.js"; const execFileAsync = promisify(execFile); @@ -36,6 +37,8 @@ export interface BinaryTarget { | "zip" | "ipa" | "apk" + | "msix" + | "appx" | "asar" | "dmg" | "pkg" @@ -131,11 +134,7 @@ const detectArtifactFormat = async ( [0x03, 0x05, 0x07].includes(magic[2] ?? -1) && [0x04, 0x06, 0x08].includes(magic[3] ?? -1) ) { - return lower.endsWith(".ipa") - ? "ipa" - : lower.endsWith(".apk") - ? "apk" - : "zip"; + return zipPackageFormatForPath(lower) ?? "zip"; } const named = namedArtifactFormat(lower); if (named !== undefined) return named; @@ -167,7 +166,7 @@ const namedArtifactFormat = ( }; const isArchiveFormat = (format: BinaryTarget["format"]): boolean => - ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(format); + ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format); const sha256Handle = async (handle: FileHandle): Promise => { const hash = createHash("sha256"); diff --git a/src/domain/evidence.ts b/src/domain/evidence.ts index d4e10248e..0fdd892b4 100644 --- a/src/domain/evidence.ts +++ b/src/domain/evidence.ts @@ -29,6 +29,8 @@ const subjectSchema = z.object({ "zip", "ipa", "apk", + "msix", + "appx", "asar", "dmg", "pkg", diff --git a/src/domain/zipPackageFormat.ts b/src/domain/zipPackageFormat.ts new file mode 100644 index 000000000..0ff8edca4 --- /dev/null +++ b/src/domain/zipPackageFormat.ts @@ -0,0 +1,20 @@ +/** ZIP-backed application package families that share the hardened archive reader. */ +export type ZipPackageFormat = "zip" | "ipa" | "apk" | "msix" | "appx"; + +/** + * Classify a ZIP-backed package by its complete lower-cased path suffix. + * + * This is deliberately extension-only. Callers must separately verify ZIP + * magic before trusting the classification for a root input. + */ +export const zipPackageFormatForPath = ( + path: string, +): ZipPackageFormat | undefined => { + const lower = path.toLowerCase(); + if (lower.endsWith(".zip")) return "zip"; + if (lower.endsWith(".ipa")) return "ipa"; + if (lower.endsWith(".apk") || lower.endsWith(".aab")) return "apk"; + if (lower.endsWith(".msix") || lower.endsWith(".msixbundle")) return "msix"; + if (lower.endsWith(".appx") || lower.endsWith(".appxbundle")) return "appx"; + return undefined; +}; diff --git a/tests/artifactProvider.test.ts b/tests/artifactProvider.test.ts index f8b083e33..0a72c5307 100644 --- a/tests/artifactProvider.test.ts +++ b/tests/artifactProvider.test.ts @@ -179,6 +179,71 @@ describe("artifact graph provider", () => { }); }); + it.each([ + ["fixture.msix", "msix"], + ["fixture.appxbundle", "appx"], + ] as const)( + "reuses the hardened ZIP reader for %s package inventory", + async (name, format) => { + const root = await createTestTempDirectory("rea-windows-package-"); + const path = join(root, name); + const writer = new ZipWriter(new Uint8ArrayWriter()); + await writer.add( + "Assets/main.js", + new TextReader("export default 'windows';"), + ); + await writer.add( + "VFS/ProgramFilesX64/App/addon.node", + new TextReader("native"), + ); + await writeFile(path, await writer.close()); + + const parsed = await parseBinaryTarget(path); + expect(parsed.ok && parsed.value).toMatchObject({ + kind: "archive", + format, + }); + if (!parsed.ok) return; + const result = await inventory(parsed.value); + expect(result.manifest.root_format).toBe(format); + expect(result.nodes.items.map(({ kind }) => kind)).toEqual( + expect.arrayContaining(["javascript", "native-addon"]), + ); + const selected = result.occurrences.items.find( + ({ logical_path: logicalPath }) => logicalPath === "Assets/main.js", + ); + expect(selected).toBeDefined(); + if (selected === undefined) return; + const output = join(root, "output"); + const extracted = await new ArtifactProvider() + .createClient(parsed.value) + .execute( + "extract_artifact", + artifactExtractionInputSchema.parse({ + approved: true, + output_root: output, + occurrence_ids: [selected.occurrence_id], + }), + ); + expect(extracted.ok).toBe(true); + expect(await readFile(join(output, "Assets", "main.js"), "utf8")).toBe( + "export default 'windows';", + ); + expect( + parseEvidence( + await runProviderAnalysis(path, "inventory_artifact", { + node_limit: 10, + occurrence_limit: 10, + edge_limit: 10, + }), + ), + ).toMatchObject({ + operation: "inventory_artifact", + subject: { format }, + }); + }, + ); + it("rejects unsafe, colliding, and over-ratio entries", async () => { expect(() => normalizeArtifactPath("../escape", limits())).toThrow( /normalized/u, diff --git a/tests/binaryTarget.test.ts b/tests/binaryTarget.test.ts index 9e1017ae4..88504b060 100644 --- a/tests/binaryTarget.test.ts +++ b/tests/binaryTarget.test.ts @@ -95,18 +95,35 @@ describe("executable header parsing", () => { }); describe("binary target I/O", () => { - it("classifies ZIP profiles and text artifacts without Hopper", async () => { + it("classifies ZIP package families and text artifacts without Hopper", async () => { const directory = await createTestTempDirectory("rea-artifact-target-"); const zip = join(directory, "fixture.apk"); + const msix = join(directory, "fixture.msixbundle"); + const appx = join(directory, "fixture.appx"); const script = join(directory, "bundle.js"); - await writeFile(zip, Buffer.from([0x50, 0x4b, 0x05, 0x06, 0, 0, 0, 0])); + const emptyZip = Buffer.from([0x50, 0x4b, 0x05, 0x06, 0, 0, 0, 0]); + await Promise.all([ + writeFile(zip, emptyZip), + writeFile(msix, emptyZip), + writeFile(appx, emptyZip), + ]); await writeFile(script, "export default 1;\n"); const archive = await parseBinaryTarget(zip); + const msixArchive = await parseBinaryTarget(msix); + const appxArchive = await parseBinaryTarget(appx); const javascript = await parseBinaryTarget(script); expect(archive.ok && archive.value).toMatchObject({ kind: "archive", format: "apk", }); + expect(msixArchive.ok && msixArchive.value).toMatchObject({ + kind: "archive", + format: "msix", + }); + expect(appxArchive.ok && appxArchive.value).toMatchObject({ + kind: "archive", + format: "appx", + }); expect(javascript.ok && javascript.value).toMatchObject({ kind: "artifact", format: "javascript",