Skip to content

armgit / rea

Public Imported from GitHub
0

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

feat(target): classify Windows PE admission metadata

N0zoM1z024274fe6b694
diff --git a/src/domain/binaryTarget.ts b/src/domain/binaryTarget.ts
index 9672da877..85ba4a8c9 100644
--- a/src/domain/binaryTarget.ts
+++ b/src/domain/binaryTarget.ts
@@ -1,5 +1,4 @@
import { constants } from "node:fs";
-import { createReadStream } from "node:fs";
import { createHash } from "node:crypto";
import {
access,
@@ -45,6 +44,10 @@ export interface BinaryTarget {
| "source-map";
readonly architecture?: BinaryArchitecture;
readonly availableArchitectures?: readonly BinaryArchitecture[];
+ /** Provider-neutral PE image role observed from COFF characteristics. */
+ readonly executableRole?: "application" | "shared-library" | "non-executable";
+ /** Whether a PE declares a non-empty CLI header data-directory entry. */
+ readonly managed?: boolean;
}
/**
@@ -65,43 +68,42 @@ export const parseBinaryTarget = async (
const resolved = await resolveAppBundle(canonical);
if (!resolved.ok) return err(resolved.error);
const path = resolved.value;
- if (!(await stat(path)).isFile())
- return err(new BinaryTargetError(path, "target is not a regular file"));
- if (
- targetKind === "database" ||
- (targetKind === undefined && path.toLowerCase().endsWith(".hop"))
- )
- return ok({
- path,
- sourcePath: canonical,
- sha256: await sha256File(path),
- kind: "database",
- format: "analysis-database",
- });
const handle = await open(path, "r");
- let detected: Result<ExecutableMetadata, string>;
try {
+ if (!(await handle.stat()).isFile())
+ return err(new BinaryTargetError(path, "target is not a regular file"));
+ if (
+ targetKind === "database" ||
+ (targetKind === undefined && path.toLowerCase().endsWith(".hop"))
+ )
+ return ok({
+ path,
+ sourcePath: canonical,
+ sha256: await sha256Handle(handle),
+ kind: "database",
+ format: "analysis-database",
+ });
const artifactFormat = await detectArtifactFormat(path, handle);
if (artifactFormat !== undefined)
return ok({
path,
sourcePath: canonical,
- sha256: await sha256File(path),
+ sha256: await sha256Handle(handle),
kind: isArchiveFormat(artifactFormat) ? "archive" : "artifact",
format: artifactFormat,
});
- detected = await readExecutableMetadata(handle, hostArchitecture);
+ const detected = await readExecutableMetadata(handle, hostArchitecture);
+ if (!detected.ok) return err(new BinaryTargetError(path, detected.error));
+ return ok({
+ path,
+ sourcePath: canonical,
+ sha256: await sha256Handle(handle),
+ kind: "executable",
+ ...detected.value,
+ });
} finally {
await handle.close();
}
- if (!detected.ok) return err(new BinaryTargetError(path, detected.error));
- return ok({
- path,
- sourcePath: canonical,
- sha256: await sha256File(path),
- kind: "executable",
- ...detected.value,
- });
} catch (cause: unknown) {
return err(
new BinaryTargetError(candidate, "path is not readable", { cause }),
@@ -167,9 +169,16 @@ const namedArtifactFormat = (
const isArchiveFormat = (format: BinaryTarget["format"]): boolean =>
["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(format);
-const sha256File = async (path: string): Promise<string> => {
+const sha256Handle = async (handle: FileHandle): Promise<string> => {
const hash = createHash("sha256");
- for await (const chunk of createReadStream(path)) hash.update(chunk);
+ const chunk = Buffer.allocUnsafe(64 * 1024);
+ let position = 0;
+ while (true) {
+ const observed = await handle.read(chunk, 0, chunk.length, position);
+ if (observed.bytesRead === 0) break;
+ hash.update(chunk.subarray(0, observed.bytesRead));
+ position += observed.bytesRead;
+ }
return hash.digest("hex");
};
@@ -262,7 +271,11 @@ const decodeXml = (value: string): string =>
type ExecutableMetadata = Pick<
BinaryTarget,
- "format" | "architecture" | "availableArchitectures"
+ | "format"
+ | "architecture"
+ | "availableArchitectures"
+ | "executableRole"
+ | "managed"
>;
const readExecutableMetadata = async (
@@ -274,13 +287,7 @@ const readExecutableMetadata = async (
const bytes = prefix.subarray(0, prefixRead.bytesRead);
if (bytes.length >= 64 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
const offset = bytes.readUInt32LE(0x3c);
- if (offset > bytes.length - 6) {
- const record = Buffer.alloc(6);
- const recordRead = await handle.read(record, 0, record.length, offset);
- return recordRead.bytesRead === record.length
- ? parsePeRecord(record)
- : err("invalid or truncated PE header");
- }
+ return readPeMetadata(handle, offset);
}
if (bytes.length >= 8) {
const magic = bytes.readUInt32BE(0);
@@ -301,6 +308,28 @@ const readExecutableMetadata = async (
return parseExecutableHeader(bytes, hostArchitecture);
};
+const readPeMetadata = async (
+ handle: FileHandle,
+ offset: number,
+): Promise<Result<ExecutableMetadata, string>> => {
+ const fileHeader = Buffer.alloc(24);
+ const fileHeaderRead = await handle.read(
+ fileHeader,
+ 0,
+ fileHeader.length,
+ offset,
+ );
+ if (fileHeaderRead.bytesRead !== fileHeader.length)
+ return err("invalid or truncated PE header");
+ const optionalHeaderSize = fileHeader.readUInt16LE(20);
+ if (optionalHeaderSize > 4096) return err("invalid PE optional header size");
+ const record = Buffer.alloc(24 + optionalHeaderSize);
+ const recordRead = await handle.read(record, 0, record.length, offset);
+ return recordRead.bytesRead === record.length
+ ? parsePeRecord(record)
+ : err("invalid or truncated PE header");
+};
+
/**
* Parse supported executable headers without I/O. The caller supplies the host
* architecture used for deterministic FAT Mach-O slice selection.
@@ -399,22 +428,68 @@ const parseElf = (bytes: Buffer): Result<ExecutableMetadata, string> => {
const parsePe = (bytes: Buffer): Result<ExecutableMetadata, string> => {
if (bytes.length < 64) return err("truncated PE DOS header");
const offset = bytes.readUInt32LE(0x3c);
- if (offset > bytes.length - 6) return err("invalid or truncated PE header");
- return parsePeRecord(bytes.subarray(offset, offset + 6));
+ if (offset > bytes.length - 24) return err("invalid or truncated PE header");
+ return parsePeRecord(bytes.subarray(offset));
};
const parsePeRecord = (record: Buffer): Result<ExecutableMetadata, string> => {
- if (record.length < 6 || record.toString("binary", 0, 4) !== "PE\u0000\u0000")
+ if (
+ record.length < 24 ||
+ record.toString("binary", 0, 4) !== "PE\u0000\u0000"
+ )
return err("invalid or truncated PE header");
const architecture = peArchitecture(record.readUInt16LE(4));
if (architecture === undefined) return err("unsupported PE architecture");
+ const optionalHeaderSize = record.readUInt16LE(20);
+ if (optionalHeaderSize > 4096 || record.length < 24 + optionalHeaderSize)
+ return err("invalid or truncated PE optional header");
+ const optionalHeader = record.subarray(24, 24 + optionalHeaderSize);
+ const managed = peManagedStatus(optionalHeader, architecture);
+ if (!managed.ok) return managed;
+ const characteristics = record.readUInt16LE(22);
return ok({
format: "pe",
architecture,
availableArchitectures: [architecture],
+ executableRole:
+ (characteristics & 0x0002) === 0
+ ? "non-executable"
+ : (characteristics & 0x2000) === 0
+ ? "application"
+ : "shared-library",
+ managed: managed.value,
});
};
+const peManagedStatus = (
+ optionalHeader: Buffer,
+ architecture: BinaryArchitecture,
+): Result<boolean, string> => {
+ if (optionalHeader.length < 2) return err("truncated PE optional header");
+ const magic = optionalHeader.readUInt16LE(0);
+ const expectedMagic =
+ architecture === "x86_64" || architecture === "arm64" ? 0x20b : 0x10b;
+ if (magic !== expectedMagic)
+ return err("PE optional-header magic does not match its architecture");
+ const directoryOffset = magic === 0x20b ? 112 : 96;
+ const directoryCountOffset = directoryOffset - 4;
+ if (optionalHeader.length < directoryCountOffset + 4)
+ return err("truncated PE optional header");
+ const directoryCount = optionalHeader.readUInt32LE(directoryCountOffset);
+ const requiredBytes = directoryOffset + directoryCount * 8;
+ if (
+ !Number.isSafeInteger(requiredBytes) ||
+ requiredBytes > optionalHeader.length
+ )
+ return err("truncated PE data-directory table");
+ if (directoryCount <= 14) return ok(false);
+ const cliDirectory = directoryOffset + 14 * 8;
+ return ok(
+ optionalHeader.readUInt32LE(cliDirectory) !== 0 ||
+ optionalHeader.readUInt32LE(cliDirectory + 4) !== 0,
+ );
+};
+
const machArchitecture = (cpu: number): BinaryArchitecture | undefined => {
switch (cpu) {
case 7:
diff --git a/tests/binaryTarget.test.ts b/tests/binaryTarget.test.ts
index a1ae0d675..aaa1dd1ee 100644
--- a/tests/binaryTarget.test.ts
+++ b/tests/binaryTarget.test.ts
@@ -35,6 +35,30 @@ describe("executable header parsing", () => {
expect(result.ok && result.value).toMatchObject({ format, architecture });
});
+ it("distinguishes native PE applications, DLLs, and managed assemblies", () => {
+ const application = parseExecutableHeader(pe(0x8664), "x64");
+ const library = parseExecutableHeader(pe(0x8664, 64, 0x2002), "x64");
+ const managed = parseExecutableHeader(pe(0x8664, 64, 0x0002, true), "x64");
+ const nonExecutable = parseExecutableHeader(pe(0x8664, 64, 0), "x64");
+
+ expect(application.ok && application.value).toMatchObject({
+ executableRole: "application",
+ managed: false,
+ });
+ expect(library.ok && library.value).toMatchObject({
+ executableRole: "shared-library",
+ managed: false,
+ });
+ expect(managed.ok && managed.value).toMatchObject({
+ executableRole: "application",
+ managed: true,
+ });
+ expect(nonExecutable.ok && nonExecutable.value).toMatchObject({
+ executableRole: "non-executable",
+ managed: false,
+ });
+ });
+
it("selects the host architecture from a FAT table", () => {
const bytes = fat([0x01000007, 0x0100000c]);
const arm = parseExecutableHeader(bytes, "arm64");
@@ -63,6 +87,17 @@ describe("executable header parsing", () => {
])("rejects malformed, truncated, or unsupported metadata", (bytes) => {
expect(parseExecutableHeader(bytes, "arm64").ok).toBe(false);
});
+
+ it("rejects malformed PE optional-header commitments", () => {
+ const wrongMagic = pe(0x8664);
+ wrongMagic.writeUInt16LE(0x10b, 64 + 24);
+ const truncatedDirectories = pe(0x8664);
+ truncatedDirectories.writeUInt16LE(112, 64 + 20);
+ truncatedDirectories.writeUInt32LE(16, 64 + 24 + 108);
+
+ expect(parseExecutableHeader(wrongMagic, "x64").ok).toBe(false);
+ expect(parseExecutableHeader(truncatedDirectories, "x64").ok).toBe(false);
+ });
});
describe("binary target I/O", () => {
@@ -218,11 +253,29 @@ const fat = (cpus: readonly number[], declared = cpus.length): Buffer => {
cpus.forEach((cpu, index) => bytes.writeUInt32BE(cpu, 8 + index * 20));
return bytes;
};
-const pe = (machine: number, offset = 64): Buffer => {
- const bytes = Buffer.alloc(Math.max(128, offset + 6));
+const pe = (
+ machine: number,
+ offset = 64,
+ characteristics = 0x0002,
+ managed = false,
+): Buffer => {
+ const optionalHeaderSize =
+ machine === 0x014c || machine === 0x01c0 ? 224 : 240;
+ const bytes = Buffer.alloc(Math.max(512, offset + 24 + optionalHeaderSize));
bytes.write("MZ", 0, "ascii");
bytes.writeUInt32LE(offset, 0x3c);
bytes.write("PE\0\0", offset, "binary");
bytes.writeUInt16LE(machine, offset + 4);
+ bytes.writeUInt16LE(optionalHeaderSize, offset + 20);
+ bytes.writeUInt16LE(characteristics, offset + 22);
+ const optionalHeader = offset + 24;
+ const pe32 = machine === 0x014c || machine === 0x01c0;
+ bytes.writeUInt16LE(pe32 ? 0x10b : 0x20b, optionalHeader);
+ const directoryOffset = pe32 ? 96 : 112;
+ bytes.writeUInt32LE(16, optionalHeader + directoryOffset - 4);
+ if (managed) {
+ bytes.writeUInt32LE(0x2000, optionalHeader + directoryOffset + 14 * 8);
+ bytes.writeUInt32LE(72, optionalHeader + directoryOffset + 14 * 8 + 4);
+ }
return bytes;
};