feat(artifacts): support MSIX and AppX packages

This commit is contained in:
morluto
2026-07-23 07:09:04 +00:00
parent 69761e95b6
commit 6e6cce1bf3
17 changed files with 145 additions and 35 deletions
+1 -1
View File
@@ -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 |
+2 -1
View File
@@ -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`.
@@ -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
+7 -1
View File
@@ -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(
+5 -18
View File
@@ -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;
@@ -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;
};
@@ -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);
+2 -1
View File
@@ -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[];
+3 -2
View File
@@ -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, {
@@ -45,6 +45,8 @@ export const targetFormatSchema = z.enum([
"zip",
"ipa",
"apk",
"msix",
"appx",
"asar",
"dmg",
"pkg",
+2
View File
@@ -37,6 +37,8 @@ const formatSchema = z.enum([
"zip",
"ipa",
"apk",
"msix",
"appx",
"asar",
"dmg",
"pkg",
+2
View File
@@ -52,6 +52,8 @@ const artifactFormatSchema = z.enum([
"analysis-database",
"ipa",
"apk",
"msix",
"appx",
"plist",
"entitlements",
"directory",
+5 -6
View File
@@ -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");
+2
View File
@@ -29,6 +29,8 @@ const subjectSchema = z.object({
"zip",
"ipa",
"apk",
"msix",
"appx",
"asar",
"dmg",
"pkg",
+20
View File
@@ -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;
};
+65
View File
@@ -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,
+19 -2
View File
@@ -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",