Skip to content

armgit / rea

Public Imported from GitHub
0

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

11.4 KB
Raw Blame
import { z } from "zod";
import { digestSchema } from "../digests.js";
import {
  absoluteLocalPathStringSchema,
  localPathStringSchema,
} from "../localPath.js";
import { BINARY_ARCHITECTURES } from "../binaryTargetTypes.js";
import {
  machoSelectionContainsRange,
  selectedSliceAgreesWithReport,
  machoSliceArchitectureSchema,
  machoTargetSelectionSchema,
} from "../apple/machoTargetSelection.js";

/** Preserve the format owner's architecture spelling separately from Evidence vocabulary. */
export const rustArchitectureForSubject = (architecture: string) => {
  switch (architecture) {
    case "386":
      return "x86";
    case "amd64":
      return "x86_64";
    default:
      return BINARY_ARCHITECTURES.find(
        (supported) => supported === architecture,
      );
  }
};

/** Known revisions used to interpret compatible cargo-auditable documents. */
export const RUST_AUDITABLE_FORMAT_VERSIONS = [0, 1, 8] as const;

const index = z.int().nonnegative();
const rustcHash = z.string().regex(/^[0-9a-f]{40}$/u);
export const rustPackageFeaturesSchema = z.array(z.string().min(1)).nullable();

/** One embedded package, with omitted kind and root preserved as null and false. */
export const rustPackageSchema = z.strictObject({
  name: z.string().min(1),
  version: z.string().min(1),
  source: z.string().min(1),
  kind: z.enum(["runtime", "build"]).nullable(),
  dependencies: z.array(index),
  features: rustPackageFeaturesSchema.default(null),
  root: z.boolean(),
});

const dependencyEdgeSchema = z.strictObject({
  from_index: index,
  to_index: index,
});

/** zlib JSON from one `.dep-v0` section, in the section's package order. */
export const rustAuditableMetadataSchema = z.strictObject({
  section_name: z.enum([".dep-v0", "__DATA,.dep-v0"]),
  file_offset: index,
  section_bytes: z.int().positive(),
  compressed_bytes: z.int().positive(),
  uncompressed_bytes: z.int().positive(),
  /** Original embedded revision; null means the source omitted the field. */
  format_version: z.int().nonnegative().max(0xffff_ffff).nullable(),
  packages: z.array(rustPackageSchema),
  root_package_index: index.nullable(),
  dependency_edges: z.array(dependencyEdgeSchema),
  cyclic_dependency_indices: z.array(index),
});

/** Inferred compiler id from read-only `/rustc/<40-hex>/` paths. */
export const rustcCommitSchema = z.strictObject({
  evidence_kind: z.literal("inferred"),
  hashes: z
    .array(
      z.strictObject({
        hash: rustcHash,
        file_offset: index,
      }),
    )
    .min(1),
});

/** One explicit local executable or library, independent of a disassembler target. */
export const inspectRustBinaryInputSchema = z.strictObject({
  path: absoluteLocalPathStringSchema.describe(
    "Absolute filesystem path to the selected executable or library",
  ),
  architecture: machoSliceArchitectureSchema.exactOptional(),
});

/** Bounded cargo-auditable observation. A missing section is null, not an empty dependency list. */
export const rustBinarySchema = z
  .strictObject({
    artifact: z.strictObject({
      path: localPathStringSchema,
      sha256: digestSchema,
      bytes: index,
    }),
    format: z.enum(["elf", "pe", "macho"]),
    architecture: z.string(),
    bits: z.union([z.literal(32), z.literal(64)]),
    byte_order: z.enum(["little", "big"]),
    /** The universal slice that was read; file offsets stay inside it. */
    selected_slice: machoTargetSelectionSchema.exactOptional(),
    auditable_metadata: rustAuditableMetadataSchema.nullable(),
    rustc_commit: rustcCommitSchema.nullable(),
    limitations: z.array(z.string()),
  })
  .superRefine((report, context) => {
    const metadata = report.auditable_metadata;
    if (metadata !== null) {
      checkSection(report.artifact.bytes, metadata, context);
      checkPackages(metadata, context);
    }
    checkRustc(report.artifact.bytes, report.rustc_commit, context);
    checkSlice(report, context);
  });

export type RustPackage = z.infer<typeof rustPackageSchema>;
export type RustAuditableMetadata = z.infer<typeof rustAuditableMetadataSchema>;
export type RustBinary = z.infer<typeof rustBinarySchema>;
export type InspectRustBinaryInput = z.infer<
  typeof inspectRustBinaryInputSchema
>;

const issue = (
  context: z.RefinementCtx,
  path: (string | number)[],
  message: string,
): void => {
  context.addIssue({ code: "custom", path, message });
};

const inside = (fileBytes: number, offset: number, size: number): boolean =>
  offset <= fileBytes && size <= fileBytes - offset;

const checkSection = (
  fileBytes: number,
  metadata: RustAuditableMetadata,
  context: z.RefinementCtx,
): void => {
  if (
    !inside(fileBytes, metadata.file_offset, metadata.section_bytes) ||
    metadata.compressed_bytes !== metadata.section_bytes
  )
    issue(
      context,
      ["auditable_metadata", "file_offset"],
      "Dependency section range is outside the selected artifact or disagrees with its compressed size.",
    );
};

const checkPackages = (
  metadata: RustAuditableMetadata,
  context: z.RefinementCtx,
): void => {
  const roots: number[] = [];
  const edgesByPackage = new Map<
    number,
    z.infer<typeof dependencyEdgeSchema>[]
  >();
  for (const [position, edge] of metadata.dependency_edges.entries()) {
    if (
      edge.from_index >= metadata.packages.length ||
      edge.to_index >= metadata.packages.length
    ) {
      issue(
        context,
        ["auditable_metadata", "dependency_edges", position],
        "Dependency edge index is outside the package list.",
      );
      continue;
    }
    const grouped = edgesByPackage.get(edge.from_index);
    if (grouped === undefined) edgesByPackage.set(edge.from_index, [edge]);
    else grouped.push(edge);
  }
  for (const [packageIndex, pkg] of metadata.packages.entries()) {
    if (pkg.root) roots.push(packageIndex);
    const edges = edgesByPackage.get(packageIndex) ?? [];
    if (
      edges.length !== pkg.dependencies.length ||
      edges.some((edge, index) => edge.to_index !== pkg.dependencies[index])
    )
      issue(
        context,
        ["auditable_metadata", "dependency_edges"],
        "Dependency edges do not match package dependency indices.",
      );
    if (pkg.dependencies.some((target) => target >= metadata.packages.length))
      issue(
        context,
        ["auditable_metadata", "packages", packageIndex, "dependencies"],
        "Dependency index is outside the package list.",
      );
  }
  const root = metadata.root_package_index;
  if (
    root === null ? roots.length !== 0 : roots.length !== 1 || roots[0] !== root
  )
    issue(
      context,
      ["auditable_metadata", "root_package_index"],
      "Root package index does not match packages marked root.",
    );
  const cycles = cyclicDependencyIndices(metadata.packages);
  if (
    cycles.length !== metadata.cyclic_dependency_indices.length ||
    cycles.some(
      (index, position) =>
        metadata.cyclic_dependency_indices[position] !== index,
    )
  )
    issue(
      context,
      ["auditable_metadata", "cyclic_dependency_indices"],
      "Cyclic dependency indices do not match the cycles in package dependencies.",
    );
};

/** Package indices that participate in a dependency cycle, in ascending order. */
export const cyclicDependencyIndices = (
  packages: readonly { readonly dependencies: readonly number[] }[],
): number[] => {
  const edges = packages.map((pkg) => pkg.dependencies);
  const order = dependencyPostorder(edges);
  const reversed = reversedDependencyEdges(edges);
  const seen = new Uint8Array(edges.length);
  const cyclic = new Set<number>();
  for (let cursor = order.length - 1; cursor >= 0; cursor -= 1) {
    const start = order[cursor];
    if (start === undefined || seen[start] === 1) continue;
    const component = dependencyComponent(start, reversed, seen);
    if (dependencyComponentInCycle(component, edges))
      for (const index of component) cyclic.add(index);
  }
  return [...cyclic].sort((left, right) => left - right);
};

interface DependencyWalkFrame {
  readonly index: number;
  edge: number;
}

const dependencyPostorder = (
  edges: readonly (readonly number[])[],
): number[] => {
  const seen = new Uint8Array(edges.length);
  const order: number[] = [];
  for (let start = 0; start < edges.length; start += 1) {
    if (seen[start] === 1) continue;
    const stack: DependencyWalkFrame[] = [{ index: start, edge: 0 }];
    seen[start] = 1;
    while (stack.length > 0) {
      const frame = stack[stack.length - 1];
      if (frame === undefined) break;
      const next = edges[frame.index]?.[frame.edge];
      if (next === undefined) {
        stack.pop();
        order.push(frame.index);
        continue;
      }
      frame.edge += 1;
      if (seen[next] === 0) {
        seen[next] = 1;
        stack.push({ index: next, edge: 0 });
      }
    }
  }
  return order;
};

const reversedDependencyEdges = (
  edges: readonly (readonly number[])[],
): number[][] => {
  const reversed = Array.from({ length: edges.length }, () => [] as number[]);
  for (let from = 0; from < edges.length; from += 1)
    for (const to of edges[from] ?? []) reversed[to]?.push(from);
  return reversed;
};

const dependencyComponent = (
  start: number,
  reversed: readonly (readonly number[])[],
  seen: Uint8Array,
): number[] => {
  const component: number[] = [];
  const stack = [start];
  seen[start] = 1;
  while (stack.length > 0) {
    const index = stack.pop();
    if (index === undefined) break;
    component.push(index);
    for (const next of reversed[index] ?? []) {
      if (seen[next] === 0) {
        seen[next] = 1;
        stack.push(next);
      }
    }
  }
  return component;
};

const dependencyComponentInCycle = (
  component: readonly number[],
  edges: readonly (readonly number[])[],
): boolean => {
  if (component.length > 1) return true;
  const only = component[0];
  return only !== undefined && (edges[only]?.includes(only) ?? false);
};

const checkSlice = (report: RustBinary, context: z.RefinementCtx): void => {
  const slice = report.selected_slice;
  if (slice === undefined) return;
  const ranges = [
    { offset: slice.offset, bytes: 0 },
    ...(report.auditable_metadata === null
      ? []
      : [
          {
            offset: report.auditable_metadata.file_offset,
            bytes: report.auditable_metadata.section_bytes,
          },
        ]),
    ...(report.rustc_commit?.hashes.map(({ file_offset: offset }) => ({
      offset,
      bytes: 48,
    })) ?? []),
  ];
  if (
    !selectedSliceAgreesWithReport(
      slice,
      report.format,
      rustArchitectureForSubject(report.architecture),
    ) ||
    ranges.some(
      ({ offset, bytes }) =>
        !machoSelectionContainsRange(
          slice,
          report.artifact.bytes,
          offset,
          bytes,
        ),
    )
  )
    issue(
      context,
      ["selected_slice"],
      "Selected universal slice must be a FAT slice of the artifact whose CPU matches the report's Mach-O architecture and that contains the reported file offsets.",
    );
};

const checkRustc = (
  fileBytes: number,
  commit: RustBinary["rustc_commit"],
  context: z.RefinementCtx,
): void => {
  if (commit === null) return;
  const seen = new Set<string>();
  for (const [position, entry] of commit.hashes.entries()) {
    if (seen.has(entry.hash) || !inside(fileBytes, entry.file_offset, 48))
      issue(
        context,
        ["rustc_commit", "hashes", position],
        "rustc path hash is duplicated or its file offset is outside the artifact.",
      );
    seen.add(entry.hash);
  }
};