Skip to content

armgit / rea

Public Imported from GitHub
0

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

6.5 KB
Raw Blame
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { AnalysisOperation } from "../application/AnalysisProvider.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import {
  nativeLoadImageSchema,
  type NativeLoadImage,
  type NativeLoadImageObservation,
} from "../domain/native/nativeLoadImage.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { err, ok, type Result } from "../domain/result.js";
import {
  attestGhidraDosComLoadImage,
  attestGhidraRawBinaryLoadImage,
} from "./GhidraLoadImageValues.js";
import type { NativeAotPeResult } from "../domain/native/nativeAotPe.js";
import type { GhidraClient } from "./GhidraClient.js";
import type { GhidraSessionError } from "./GhidraSessionError.js";

type NativeLoadImageAttestationInput = {
  readonly target: BinaryTarget;
  readonly operation: AnalysisOperation;
  readonly measured: NativeLoadImageObservation;
  readonly client: Partial<
    Pick<
      GhidraClient,
      "hashTargetSnapshot" | "readTargetSnapshot" | "attestDosTargetSnapshot"
    >
  >;
  readonly mapSessionError: (failure: GhidraSessionError) => AnalysisError;
  readonly nativeAotResult?: NativeAotPeResult | undefined;
  readonly signal?: AbortSignal | undefined;
};

/** Consume one typed comparison, retaining completed facts after the last awaited work. */
export const attestGhidraNativeLoadImage = async (
  input: NativeLoadImageAttestationInput,
): Promise<Result<NativeLoadImage, AnalysisError>> => {
  const result = await compareLoadImage(input);
  if (!result.ok) return result;
  return input.signal?.aborted
    ? err(
        new AnalysisCancelledError(input.operation, {
          cause: input.signal.reason,
          partialObservation: {
            kind: "native-load-image",
            stage: "completed",
            result: result.value,
          },
        }),
      )
    : result;
};

const comparisonFailure = (
  input: NativeLoadImageAttestationInput,
  reason: string,
  cause?: unknown,
): AnalysisError =>
  new ProviderAdapterError("ghidra", input.operation, {
    diagnostics: { reason },
    ...(cause === undefined ? {} : { cause }),
    partialObservation: {
      kind: "native-load-image",
      stage: "measured",
      observations: input.measured,
    },
  });

const compareLoadImage = async (
  input: NativeLoadImageAttestationInput,
): Promise<Result<NativeLoadImage, AnalysisError>> => {
  const {
    target,
    operation,
    measured: observations,
    client,
    mapSessionError,
    nativeAotResult,
    signal,
  } = input;
  // These formats have no additional source work; retain already-derived PE facts.
  if (
    target.format === "pe" ||
    !["dos-mz", "dos-com", "raw-binary"].includes(target.format)
  ) {
    if (target.format === "pe" && nativeAotResult === undefined)
      return err(
        comparisonFailure(
          input,
          "The Ghidra provider did not produce read-only NativeAOT metadata for this admitted PE snapshot.",
        ),
      );
    const represented = nativeLoadImageSchema.safeParse({
      status: "unsupported",
      reason:
        "Independent load-image verification currently supports DOS MZ, explicit DOS COM, and caller-supplied raw-binary targets only.",
      observations:
        target.format !== "pe" || nativeAotResult === undefined
          ? observations
          : {
              ...observations,
              metadata_recovery: [
                ...(observations.metadata_recovery ?? []),
                nativeAotResult.summary,
              ],
            },
      limitations: [
        target.format === "pe"
          ? "Load-image verification is not performed for PE targets; NativeAOT metadata observations are derived separately from the exact admitted snapshot."
          : "Other formats expose measured mappings and source identities; no format-specific verification was performed.",
      ],
    });
    return represented.success
      ? ok(represented.data)
      : err(
          comparisonFailure(
            input,
            "Load-image observations could not be represented in the result",
            represented.error,
          ),
        );
  }
  if (signal?.aborted)
    return err(
      new AnalysisCancelledError(operation, {
        cause: signal.reason,
        partialObservation: {
          kind: "native-load-image",
          stage: "measured",
          observations,
        },
      }),
    );
  const sourceFailure = (failure: GhidraSessionError): AnalysisError =>
    mapSessionError(
      failure.withDiagnostics({
        ...failure.diagnostics,
        load_image_observations: jsonValueSchema.parse(observations),
      }),
    );
  if (target.format === "raw-binary") {
    if (client.hashTargetSnapshot === undefined)
      return err(
        comparisonFailure(
          input,
          "The Ghidra client does not expose its immutable target snapshot identity for independent raw-binary load-image verification.",
        ),
      );
    const snapshot = await client.hashTargetSnapshot(signal);
    if (!snapshot.ok) return err(sourceFailure(snapshot.error));
    const attested = attestGhidraRawBinaryLoadImage(
      snapshot.value,
      target,
      observations,
    );
    return attested.ok
      ? attested
      : err(comparisonFailure(input, attested.error));
  }
  if (target.format === "dos-mz") {
    if (client.attestDosTargetSnapshot === undefined)
      return err(
        comparisonFailure(
          input,
          "The Ghidra client does not expose its bounded DOS target snapshot comparison.",
        ),
      );
    const compared = await client.attestDosTargetSnapshot(observations, signal);
    return compared.ok ? compared : err(sourceFailure(compared.error));
  }
  if (client.readTargetSnapshot === undefined)
    return err(
      comparisonFailure(
        input,
        "The Ghidra client does not expose its immutable target snapshot for independent load-image verification.",
      ),
    );
  const snapshot = await client.readTargetSnapshot(undefined, signal);
  if (!snapshot.ok) return err(sourceFailure(snapshot.error));
  if (snapshot.value.kind !== "captured")
    return err(
      comparisonFailure(
        input,
        "The uncapped load-image snapshot was unexpectedly not captured.",
      ),
    );
  const attested = attestGhidraDosComLoadImage(
    snapshot.value.bytes,
    target.sha256,
    observations,
  );
  return attested.ok ? attested : err(comparisonFailure(input, attested.error));
};