Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(artifacts): support MSIX and AppX packages
morluto6e6cce1bf3cb
diff --git a/README.md b/README.mdindex 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.mdindex 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.mdindex 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 extractionCall `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 anddiff --git a/src/application/ArtifactExtraction.ts b/src/application/ArtifactExtraction.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<ArtifactEntry>;open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;provenance(): readonly ArtifactCommand[];diff --git a/src/artifacts/ZipArtifactReader.ts b/src/artifacts/ZipArtifactReader.tsindex 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<string> {#handle: FileHandle | undefined;@@ -41,12 +42,12 @@ class NodeFileReader extends Reader<string> {/** 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<string>;readonly #entries = new Map<string, Entry>();- 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<string> => {const hash = createHash("sha256");diff --git a/src/domain/evidence.ts b/src/domain/evidence.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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",