Skip to content

armgit / rea

Public Imported from GitHub
0

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

11.7 KB
Raw Blame
import { functionStructuralCandidate } from "./functionStructuralCandidate.js";
import { z } from "zod";
import type { Evidence } from "../evidence.js";
import { EvidenceIntegrityError } from "../evidenceErrors.js";
import { readEvidencePayload } from "../evidenceValidation.js";
import { digestCanonicalValue } from "../canonicalDigest.js";
import {
  functionBodySchema,
  functionBodyEntryAgrees,
  functionDossierSchema,
} from "../hopperValues.js";
import { isAutoName } from "../functionComparisonNormalization.js";
import {
  addressedValueSchema,
  nativeInventoryRowsSchemas,
} from "./nativeInventory.js";
import { nativeAddressInputSchema } from "./nativeAddress.js";
import { nativeByteReadSchema } from "./nativeByteRead.js";
import { procedureInfoSchema } from "./procedureInfo.js";
import type { NativeFunctionMatchMember } from "./functionMatching.js";
import {
  FunctionByteCoverage,
  type NativeMatchingCheckpoint,
} from "./functionByteCoverage.js";

const matchingRowsSchema = nativeInventoryRowsSchemas.names.element
  .extend({ address: nativeAddressInputSchema })
  .array();
const availableBodySchema = functionBodySchema.options[1];
const matchingBodySchema = z.discriminatedUnion("available", [
  functionBodySchema.options[0],
  availableBodySchema.safeExtend({
    ranges: availableBodySchema.shape.ranges.element
      .extend({
        start: nativeAddressInputSchema,
        end: nativeAddressInputSchema,
      })
      .array(),
  }),
]);
const matchingProcedureInfoSchema = procedureInfoSchema
  .safeExtend({
    entrypoint: nativeAddressInputSchema,
    body: matchingBodySchema,
  })
  .transform(({ entrypoint, body }) => ({ address: entrypoint, body }));
const matchingFunctionDossierSchema = functionDossierSchema.safeExtend({
  procedure: functionDossierSchema.shape.procedure.safeExtend({
    address: nativeAddressInputSchema,
    body: matchingBodySchema,
  }),
});
const sourcePayload = <Output>(
  schema: z.ZodType<Output>,
  input: unknown,
): Output => {
  const result = readEvidencePayload(schema, input);
  if (!result.ok) throw result.error;
  return result.value;
};

type Body = z.infer<typeof functionBodySchema>;
type AddressedValue = z.infer<typeof addressedValueSchema>;

export interface MatchingFunction {
  readonly member: NativeFunctionMatchMember;
  readonly symbol: string | null;
  readonly fingerprint: string | null;
}
interface Detail {
  body: Body;
  dossier?: string | null;
  candidate?: string | null;
  conflict: boolean;
  readonly links: string[];
}
interface Symbols {
  readonly values: AddressedValue[];
  readonly links: Set<string>;
}
interface Facts {
  readonly details: Map<string, Detail>;
  readonly symbols: Map<string, Symbols>;
  readonly bytes: FunctionByteCoverage;
}

/** Supplementary observations must belong to this exact provider/target/profile/document. */
const requireContext = (inventory: Evidence, observation: Evidence): void => {
  if (
    observation.predicate_type !== "rea.analysis" ||
    digestCanonicalValue(observation.subject) !==
      digestCanonicalValue(inventory.subject) ||
    digestCanonicalValue(observation.provider) !==
      digestCanonicalValue(inventory.provider) ||
    digestCanonicalValue(observation.analysis_profile) !==
      digestCanonicalValue(inventory.analysis_profile) ||
    (observation.parameters.document ?? null) !==
      (inventory.parameters.document ?? null)
  )
    throw new EvidenceIntegrityError(
      "Function observation does not belong to its selected inventory context",
    );
};
const addBody = (observation: Evidence, details: Facts["details"]): void => {
  const dossier =
    observation.operation === "analyze_function"
      ? sourcePayload(
          matchingFunctionDossierSchema,
          observation.normalized_result,
        )
      : undefined;
  const procedure =
    dossier?.procedure ??
    sourcePayload(matchingProcedureInfoSchema, observation.normalized_result);
  const address = procedure.address;
  if (!functionBodyEntryAgrees(procedure.body, address))
    throw new EvidenceIntegrityError(
      "Procedure body entry membership contradicts its address",
    );
  let detail = details.get(address);
  if (detail === undefined) {
    details.set(
      address,
      (detail = { body: procedure.body, conflict: false, links: [] }),
    );
  } else if (
    digestCanonicalValue(detail.body) !== digestCanonicalValue(procedure.body)
  ) {
    detail.conflict = true;
  }
  detail.body = procedure.body;
  if (observation.operation === "analyze_function") {
    const candidate = functionStructuralCandidate(observation, dossier!);
    if (detail.dossier === undefined) {
      detail.dossier = observation.evidence_id;
      detail.candidate = candidate;
    } else {
      // Request identity and dossier selection are independent of body agreement.
      if (detail.dossier !== observation.evidence_id) detail.dossier = null;
      if (detail.candidate !== candidate) detail.candidate = null;
    }
  }
  detail.links.push(observation.evidence_id);
};
const addNames = async (
  observation: Evidence,
  symbols: Facts["symbols"],
  checkpoint: NativeMatchingCheckpoint,
): Promise<void> => {
  for (const symbol of sourcePayload(
    matchingRowsSchema,
    observation.normalized_result,
  )) {
    await checkpoint(128 + symbol.value.length * 2);
    const address = symbol.address;
    let group = symbols.get(address);
    if (group === undefined)
      symbols.set(address, (group = { values: [], links: new Set() }));
    group.values.push(symbol);
    group.links.add(observation.evidence_id);
  }
};
const addBytes = async (
  observation: Evidence,
  bytes: FunctionByteCoverage,
): Promise<void> => {
  const parsed = sourcePayload(
    nativeByteReadSchema,
    observation.normalized_result,
  );
  const requestAddress =
    typeof observation.parameters.address === "string"
      ? sourcePayload(nativeAddressInputSchema, observation.parameters.address)
      : undefined;
  const read = {
    ...parsed,
    address:
      requestAddress !== undefined || parsed.returned_bytes > 0
        ? sourcePayload(nativeAddressInputSchema, parsed.address)
        : parsed.address,
  };
  if (
    (requestAddress !== undefined && requestAddress !== read.address) ||
    (typeof observation.parameters.length === "number" &&
      observation.parameters.length !== read.requested_bytes)
  )
    throw new EvidenceIntegrityError(
      "Read-byte coordinates contradict the selected request",
    );
  await bytes.add(read, observation.evidence_id);
};
const reportedSymbol = (
  row: AddressedValue,
  known: Symbols | undefined,
): {
  readonly value: string | null;
  readonly origin: "known" | "unknown" | "conflicting";
} => {
  const names = [
    ...(row.symbol === undefined ? [] : [row]),
    ...(known?.values.filter((symbol) => symbol.value === row.value) ?? []),
  ];
  const generated = names.some(
    (symbol) =>
      symbol.symbol?.dynamic === true || symbol.symbol?.source === "default",
  );
  const named = names.some(
    (symbol) =>
      symbol.symbol?.dynamic === false && symbol.symbol.source !== "default",
  );
  return {
    value:
      row.value.length === 0 || generated || (!named && isAutoName(row.value))
        ? null
        : row.value,
    origin:
      generated && named
        ? "conflicting"
        : names.some((symbol) => symbol.symbol !== undefined)
          ? "known"
          : "unknown",
  };
};
const functionFact = async (
  {
    inventory,
    row,
    sourceIndex,
  }: { inventory: Evidence; row: AddressedValue; sourceIndex: number },
  facts: Facts,
  checkpoint: NativeMatchingCheckpoint,
): Promise<MatchingFunction> => {
  const address = row.address,
    detail = facts.details.get(address),
    symbols = facts.symbols.get(address);
  // Bound expansion before creating per-occurrence sets, arrays and subsequent
  // schema/Evidence serialization copies. Same-address aliases repeat these links.
  for (const link of detail?.links ?? [])
    await checkpoint(256 + 8 * link.length);
  for (const link of symbols?.links ?? [])
    await checkpoint(256 + 8 * link.length);
  await checkpoint(256 + 8 * inventory.evidence_id.length);
  const links = new Set([inventory.evidence_id]);
  for (const link of detail?.links ?? []) links.add(link);
  for (const link of symbols?.links ?? []) links.add(link);
  const body = detail?.conflict ? undefined : detail?.body;
  const fingerprint = await facts.bytes.fingerprint(body);
  for (const link of fingerprint?.links ?? []) {
    await checkpoint(256 + 8 * link.length);
    links.add(link);
  }
  const limitations: string[] = [];
  const symbol = reportedSymbol(row, symbols);
  if (fingerprint === null)
    limitations.push(
      detail?.conflict
        ? "Conflicting procedure observations; body and dossier remain unknown."
        : "No complete unambiguous bytes for the observed function body.",
    );
  if (symbol.origin === "unknown")
    limitations.push(
      "Symbol origin unavailable; exact-name matching uses the reported name and the existing automatic-name exclusion rule.",
    );
  if (symbol.origin === "conflicting")
    limitations.push(
      "Conflicting generated and named symbol-origin observations; exact-name matching is unavailable. Independent complete body bytes remain eligible.",
    );
  if (detail?.dossier === null)
    limitations.push(
      "Multiple supplied dossiers describe this address; no dossier is selected automatically. Agreed body bytes and structural facts remain usable.",
    );
  return {
    member: {
      function_id: `${inventory.evidence_id}/${sourceIndex}`,
      inventory_evidence_id: inventory.evidence_id,
      source_index: sourceIndex,
      address,
      name: row.value,
      body_sha256: fingerprint?.sha256 ?? null,
      structural_candidate_sha256: detail?.conflict
        ? null
        : (detail?.candidate ?? null),
      body_bytes: body?.available ? body.total_bytes : null,
      dossier_evidence_id: detail?.conflict ? null : (detail?.dossier ?? null),
      evidence_links: [...links].sort(),
      limitations,
    },
    symbol: symbol.value,
    fingerprint: fingerprint?.key ?? null,
  };
};

/** Consume normalized producer facts once; never infer body extents from neighbor entries. */
export const readFunctionInventory = async (
  inventory: Evidence,
  observations: readonly Evidence[],
  checkpoint: NativeMatchingCheckpoint,
): Promise<MatchingFunction[]> => {
  if (
    inventory.operation !== "list_procedures" ||
    inventory.predicate_type !== "rea.analysis" ||
    inventory.subject === null
  )
    throw new EvidenceIntegrityError(
      "Expected artifact-bound list_procedures Evidence",
    );
  const rows = sourcePayload(matchingRowsSchema, inventory.normalized_result);
  const facts: Facts = {
    details: new Map(),
    symbols: new Map(),
    bytes: new FunctionByteCoverage(checkpoint),
  };
  for (const observation of observations) {
    await checkpoint();
    requireContext(inventory, observation);
    switch (observation.operation) {
      case "list_names":
        await addNames(observation, facts.symbols, checkpoint);
        break;
      case "read_bytes":
        await addBytes(observation, facts.bytes);
        break;
      case "procedure_info":
      case "analyze_function":
        addBody(observation, facts.details);
        break;
      default:
        throw new EvidenceIntegrityError(
          "Function matching observations must be list_names, procedure_info, read_bytes or analyze_function Evidence",
        );
    }
  }
  const functions: MatchingFunction[] = [];
  for (let sourceIndex = 0; sourceIndex < rows.length; sourceIndex++) {
    const row = rows[sourceIndex]!;
    await checkpoint(1024 + 4 * (row.address.length + row.value.length));
    functions.push(
      await functionFact({ inventory, row, sourceIndex }, facts, checkpoint),
    );
  }
  return functions;
};