Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(artifacts): support MSIX and AppX packages

morluto6e6cce1bf3cb
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<ArtifactEntry>;
open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;
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<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.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<string> => {
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",