Skip to content

armgit / rea

Public Imported from GitHub
0

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

12.1 KB
Raw Blame
import { describe, expect, it } from "vitest";
import { createHash } from "node:crypto";
import {
  compareDosFixture,
  fixtureDosLoadImage,
} from "./GhidraLoadImage.fixture.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import {
  nativeLoadImageObservationSchema,
  nativeLoadImageSchema,
} from "../domain/native/nativeLoadImage.js";
import type { NativeLoadImageObservation } from "../domain/native/nativeLoadImage.js";
import { parseGhidraInventoryResult } from "./GhidraInventoryValues.js";
import { prepareGhidraDosLoadImage } from "./GhidraLoadImageValues.js";

it("does not interpret an ambiguous Windows-header candidate as a DOS image", () => {
  const bytes = Buffer.alloc(128);
  bytes.write("MZ", 0, "ascii");
  bytes.writeUInt16LE(128, 2);
  bytes.writeUInt16LE(1, 4);
  bytes.writeUInt16LE(2, 6);
  bytes.writeUInt16LE(4, 8);
  bytes.writeUInt16LE(28, 24);
  bytes.write("ABCD", 60, "ascii");
  expect(prepareGhidraDosLoadImage(bytes, bytes.length)).toEqual({
    ok: false,
    error: "MZ Windows new-header candidate is unresolved",
  });
});

const damage: ReadonlyArray<
  readonly [string, (observation: NativeLoadImageObservation) => void]
> = [
  [
    "memory byte",
    (x) => {
      if (x.mappings[1]) x.mappings[1].sha256 = "f".repeat(64);
    },
  ],
  [
    "header byte",
    (x) => {
      if (x.mappings[0]) x.mappings[0].sha256 = "f".repeat(64);
    },
  ],
  [
    "modified source",
    (x) => {
      x.source_files[0] && (x.source_files[0].modified_sha256 = "f".repeat(64));
    },
  ],
  [
    "original source",
    (x) => {
      x.source_files[0] && (x.source_files[0].original_sha256 = "f".repeat(64));
    },
  ],
  [
    "source length",
    (x) => {
      if (x.source_files[0]) x.source_files[0].size--;
    },
  ],
  [
    "source identity",
    (x) => {
      if (x.mappings[1]) x.mappings[1].source_file_index = 1;
    },
  ],
  [
    "missing mapping",
    (x) => {
      x.mappings.splice(1, 1);
    },
  ],
  [
    "duplicate mapping",
    (x) => {
      if (x.mappings[1]) x.mappings.push(structuredClone(x.mappings[1]));
    },
  ],
  [
    "gap",
    (x) => {
      if (x.mappings[1]) x.mappings[1].file_offset = 33;
    },
  ],
  [
    "overlap",
    (x) => {
      if (x.mappings[1]) x.mappings[1].file_offset = 31;
    },
  ],
  [
    "alias address",
    (x) => {
      if (x.mappings[1]) x.mappings[1].start = "0x10001";
    },
  ],
  [
    "end address",
    (x) => {
      if (x.mappings[1]) x.mappings[1].end = "0x10080";
    },
  ],
  [
    "wrong address space",
    (x) => {
      x.default_address_space = "wrong";
    },
  ],
  [
    "header loaded",
    (x) => {
      if (x.mappings[0]) x.mappings[0].loaded = true;
    },
  ],
  [
    "module overlay",
    (x) => {
      if (x.mappings[1]) x.mappings[1].overlay = true;
    },
  ],
  [
    "uninitialized module",
    (x) => {
      if (x.mappings[1]) x.mappings[1].initialized = false;
    },
  ],
  [
    "complex source mapping",
    (x) => {
      if (x.mappings[1]) x.mappings[1].file_offset = null;
    },
  ],
  [
    "missing relocation",
    (x) => {
      x.relocations = [];
    },
  ],
  [
    "duplicate relocation",
    (x) => {
      if (x.relocations[0])
        x.relocations.push(structuredClone(x.relocations[0]));
    },
  ],
  [
    "relocation word",
    (x) => {
      if (x.relocations[0]) x.relocations[0].memory_bytes_hex = "0400";
    },
  ],
  [
    "relocation metadata",
    (x) => {
      if (x.relocations[0]) x.relocations[0].values = [0, 9, 4];
    },
  ],
  [
    "relocation status",
    (x) => {
      if (x.relocations[0]) x.relocations[0].status = "FAILURE";
    },
  ],
  [
    "relocation segment",
    (x) => {
      if (x.relocations[0]) x.relocations[0].segment = 0;
    },
  ],
  [
    "entry",
    (x) => {
      x.entry_points = ["0x10001"];
    },
  ],
  [
    "extra entry",
    (x) => {
      x.entry_points.push("0x10010");
    },
  ],
  [
    "loader",
    (x) => {
      x.executable_format = "Raw Binary";
    },
  ],
  [
    "language",
    (x) => {
      x.language_id = "x86:LE:32:default";
    },
  ],
  [
    "compiler",
    (x) => {
      x.compiler_spec_id = "windows";
    },
  ],
  [
    "image base",
    (x) => {
      x.image_base = "0x10000";
    },
  ],
  [
    "extra source file",
    (x) => {
      if (x.source_files[0])
        x.source_files.push(structuredClone(x.source_files[0]));
    },
  ],
  [
    "initialized unbacked alias",
    (x) => {
      if (x.mappings[2]) x.mappings[2].initialized = true;
    },
  ],
  [
    "overlay source mapping",
    (x) => {
      const row = x.mappings[1];
      if (row)
        x.mappings.push({
          ...row,
          file_offset: 160,
          length: 23,
          start: "0x10080",
          end: "0x10096",
        });
    },
  ],
];

const malformedCoordinates: ReadonlyArray<
  readonly [string, (observation: NativeLoadImageObservation) => void]
> = [
  ["image base", (value) => (value.image_base = "not-an-address")],
  [
    "mapping start",
    (value) => {
      const mapping = value.mappings[0];
      if (mapping) mapping.start = "not-an-address";
    },
  ],
  [
    "mapping end",
    (value) => {
      const mapping = value.mappings[0];
      if (mapping) mapping.end = "not-an-address";
    },
  ],
  [
    "relocation address",
    (value) => {
      const relocation = value.relocations[0];
      if (relocation) relocation.address = "not-an-address";
    },
  ],
  ["entry point", (value) => (value.entry_points[0] = "not-an-address")],
  [
    "entry context address",
    (value) => {
      value.entry_context.push({ address: "not-an-address", registers: [] });
    },
  ],
];

it.each(malformedCoordinates)(
  "rejects a malformed nonempty %s at both native load-image boundaries",
  (_name, mutate) => {
    const observation = structuredClone(fixtureDosLoadImage().observation);
    mutate(observation);
    expect({
      shared: nativeLoadImageObservationSchema.safeParse(observation).success,
      provider: parseGhidraInventoryResult(
        "inspect_native_load_image",
        jsonValueSchema.parse(observation),
      ).ok,
    }).toEqual({ shared: false, provider: false });
  },
);

it("preserves zero-padded, qualified, and large observation addresses", () => {
  const observation = structuredClone(fixtureDosLoadImage().observation);
  observation.image_base = "0x0000";
  const mapping = observation.mappings[0];
  const relocation = observation.relocations[0];
  if (!mapping || !relocation) throw new Error("Incomplete load-image fixture");
  mapping.start = "ram%2Fbank:0x0000000000000001";
  mapping.end = "ram%2Fbank:0x10000000000000001";
  relocation.address = "0x10000000000000009";
  observation.entry_points[0] = "ram:0x10000000000000001";
  const parsed = parseGhidraInventoryResult(
    "inspect_native_load_image",
    jsonValueSchema.parse(observation),
  );
  expect(parsed.ok).toBe(true);
  if (!parsed.ok) throw parsed.error;
  expect(parsed.value.value).toEqual(observation);
});

it("rejects malformed coordinates in completed load-image checks and entries", () => {
  const fixture = fixtureDosLoadImage();
  const compared = compareDosFixture(
    fixture.bytes,
    fixture.sha256,
    fixture.observation,
  );
  if (!compared.ok || compared.value.status === "unsupported")
    throw new Error("Expected a completed DOS load-image result");
  const malformedResults = [
    {
      ...compared.value,
      entry: { ...compared.value.entry, linear_address: "not-an-address" },
    },
    {
      ...compared.value,
      checks: compared.value.checks.map((check, index) =>
        index === 0 ? { ...check, address: "not-an-address" } : check,
      ),
    },
  ];
  expect(
    malformedResults.map(
      (result) => nativeLoadImageSchema.safeParse(result).success,
    ),
  ).toEqual([false, false]);
});

describe("independent DOS MZ import verification", () => {
  it("verifies every initialized source byte while retaining overlay and BSS scope", () => {
    const fixture = fixtureDosLoadImage();
    const result = compareDosFixture(
      fixture.bytes,
      fixture.sha256,
      fixture.observation,
    );
    expect(result).toMatchObject({
      ok: true,
      value: {
        status: "verified",
        module_bytes: 128,
        header_bytes: 32,
        overlay_bytes: 23,
        entry: { linear_address: "0x10000" },
      },
    });
    if (!result.ok || result.value.status === "unsupported")
      throw new Error("Expected measured MZ checks");
    expect(result.value.checks.every((check) => check.matched)).toBe(true);
    expect(result.value.observations).toEqual(fixture.observation);
    expect(result.value.limitations.join(" ")).toMatch(
      /runtime behavior.*not verified/u,
    );
  });

  it.each(damage)(
    "rejects a %s despite a matching executable digest",
    (_name, mutate) => {
      const fixture = fixtureDosLoadImage();
      mutate(fixture.observation);
      const result = compareDosFixture(
        fixture.bytes,
        fixture.sha256,
        fixture.observation,
      );
      expect(result).toMatchObject({
        ok: true,
        value: { status: "mismatch", observations: fixture.observation },
      });
      if (!result.ok || result.value.status === "unsupported")
        throw new Error("Expected MZ verification checks");
      expect(result.value.checks.some((check) => !check.matched)).toBe(true);
    },
  );

  it("retains source range coordinates when memory evidence disagrees", () => {
    const fixture = fixtureDosLoadImage();
    const mapping = fixture.observation.mappings[1];
    if (mapping === undefined) throw new Error("Missing module mapping");
    mapping.sha256 = "f".repeat(64);
    const result = compareDosFixture(
      fixture.bytes,
      fixture.sha256,
      fixture.observation,
    );
    if (!result.ok || result.value.status === "unsupported")
      throw new Error("Expected MZ verification checks");
    expect(result.value.checks.filter((check) => !check.matched)).toEqual([
      expect.objectContaining({
        name: "mapping[1].memory_sha256",
        file_offset: 32,
        address: "0x10000",
        observed: "f".repeat(64),
      }),
    ]);
  });

  it("is independent of mapping iteration order", () => {
    const fixture = fixtureDosLoadImage();
    fixture.observation.mappings.reverse();
    expect(
      compareDosFixture(fixture.bytes, fixture.sha256, fixture.observation),
    ).toMatchObject({ ok: true, value: { status: "verified" } });
  });

  it("accepts a different segment alias while preserving the observed coordinates and raw table values", () => {
    const fixture = fixtureDosLoadImage();
    const relocation = fixture.observation.relocations[0];
    if (relocation === undefined)
      throw new Error("Missing source-owned relocation");
    relocation.segment = 0x0fff;
    relocation.offset = 25;
    expect(
      compareDosFixture(fixture.bytes, fixture.sha256, fixture.observation),
    ).toMatchObject({
      ok: true,
      value: {
        status: "verified",
        observations: {
          relocations: [
            { segment: 0x0fff, offset: 25, values: [0, 9, 0x1004] },
          ],
        },
      },
    });
  });

  it("rejects a changed snapshot and malformed MZ rather than trusting provider hashes", () => {
    const fixture = fixtureDosLoadImage();
    fixture.bytes[0] = 0;
    expect(
      compareDosFixture(fixture.bytes, fixture.sha256, fixture.observation),
    ).toMatchObject({ ok: false, error: expect.stringContaining("digest") });
    const digest = createHash("sha256").update(fixture.bytes).digest("hex");
    expect(
      compareDosFixture(fixture.bytes, digest, fixture.observation),
    ).toMatchObject({ ok: false, error: expect.stringContaining("MZ header") });
  });

  it("rejects malformed producer digests and unsafe source coordinates", () => {
    const fixture = fixtureDosLoadImage();
    expect(
      nativeLoadImageObservationSchema.safeParse({
        ...fixture.observation,
        source_files: [
          { ...fixture.observation.source_files[0], original_sha256: "bad" },
        ],
      }).success,
    ).toBe(false);
    const mapping = fixture.observation.mappings[0];
    expect(
      nativeLoadImageObservationSchema.safeParse({
        ...fixture.observation,
        mappings: [{ ...mapping, file_offset: Number.MAX_SAFE_INTEGER + 1 }],
      }).success,
    ).toBe(false);
  });
});