Skip to content

armgit / rea

Public Imported from GitHub
0

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

9.7 KB
Raw Blame
import type { BigIntStats } from "node:fs";
import { lstat, readlink, realpath } from "node:fs/promises";
import { isAbsolute, join, relative, sep } from "node:path";

import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { resolveTreePath } from "../../domain/apple/dyldPaths.js";
import {
  dylibResolutionInputSchema,
  dylibResolutionResultSchema,
  traceDylibLoading,
  type DylibResolutionResult,
  type DylibTreeEntry,
  type DylibTreeView,
  type MachoImageFacts,
} from "../../domain/apple/dylibResolution.js";
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
import { ArtifactReaderFailure } from "../ArtifactReader.js";
import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
import { consumeWithOrderedReads } from "../OrderedReads.js";
import {
  DylibFileAccess,
  classifyDylibReadFailure,
} from "./DylibFileAccess.js";
import { ArtifactResourceScope } from "../ArtifactResourceScope.js";
import { assertArtifactReadActive } from "../ArtifactFileOperation.js";

const OPERATION = "trace_dylib_resolution";
/** Concurrent four-byte magic reads while enumerating bundle roots. */
const MAGIC_READ_CONCURRENCY = 8;

/** Lazily probed, symlink-preserving view of one analyzed directory. */
class FilesystemTreeView implements DylibTreeView {
  readonly #entries = new Map<string, Promise<DylibTreeEntry | undefined>>();
  readonly #images = new Map<string, Promise<MachoImageFacts>>();
  readonly #identities = new Map<string, BigIntStats>();

  constructor(
    private readonly root: string,
    private readonly sourceRoot: string,
    private readonly files: DylibFileAccess,
    private readonly signal?: AbortSignal,
  ) {}

  rootRelativePath(absolutePath: string): string | undefined {
    const roots = isAbsolute(this.sourceRoot)
      ? [this.root, this.sourceRoot]
      : [this.root];
    for (let root of roots) {
      while (root.length > 1 && root.endsWith(sep)) root = root.slice(0, -1);
      if (absolutePath === root) return "";
      const prefix = root === sep ? sep : `${root}${sep}`;
      if (absolutePath.startsWith(prefix))
        return absolutePath.slice(prefix.length).split(sep).join("/");
    }
    return undefined;
  }

  entry(path: string): Promise<DylibTreeEntry | undefined> {
    const cached = this.#entries.get(path);
    if (cached !== undefined) return cached;
    const pending = this.#readEntry(path);
    this.#entries.set(path, pending);
    return pending;
  }

  image(path: string): Promise<MachoImageFacts> {
    const cached = this.#images.get(path);
    if (cached !== undefined) return cached;
    const pending = this.files
      .image(join(this.root, path))
      .then(({ facts, identity }) => {
        this.#identities.set(path, identity);
        return facts;
      });
    this.#images.set(path, pending);
    return pending;
  }

  /** Identity of the file whose header bytes `image()` parsed. */
  identity(path: string): BigIntStats | undefined {
    return this.#identities.get(path);
  }

  async #readEntry(path: string): Promise<DylibTreeEntry | undefined> {
    assertArtifactReadActive(this.signal);
    const absolute = join(this.root, path);
    try {
      const metadata = await lstat(absolute);
      if (metadata.isSymbolicLink())
        return { kind: "symlink", target: await readlink(absolute) };
      if (metadata.isDirectory()) return { kind: "directory" };
      return metadata.isFile() ? { kind: "file" } : undefined;
    } catch (cause: unknown) {
      if (missing(cause)) return undefined;
      throw cause;
    }
  }
}

/** Resolve dyld load paths for the active Mach-O or every executable in its bundle. */
export const traceDylibResolution = async (options: {
  readonly rootPath: string;
  readonly targetPath: string;
  readonly targetSha256: string;
  readonly enumerateRoots: boolean;
  readonly parameters: unknown;
  readonly resourceScope?: ArtifactResourceScope;
  readonly signal?: AbortSignal;
}): Promise<DylibResolutionResult> => {
  const parsed = dylibResolutionInputSchema.safeParse(options.parameters);
  if (!parsed.success)
    throw analysisInputErrorFromIssues(
      OPERATION,
      parsed.error.issues,
      options.parameters,
      { cause: parsed.error },
    );
  const resources = options.resourceScope ?? new ArtifactResourceScope();
  return await resources.run(async () => {
    // Canonicalization is inside the translated region: a revoked permission
    // keeps its reason and path.
    let root = options.rootPath;
    try {
      assertArtifactReadActive(options.signal);
      root = await realpath(options.rootPath);
      assertArtifactReadActive(options.signal);
      const files = new DylibFileAccess(resources, root, options.signal);
      const target = relative(root, await realpath(options.targetPath))
        .split(sep)
        .join("/");
      assertArtifactReadActive(options.signal);
      const view = new FilesystemTreeView(
        root,
        options.rootPath,
        files,
        options.signal,
      );
      const { roots: requested, unclassified } =
        parsed.data.roots !== undefined
          ? { roots: parsed.data.roots, unclassified: [] }
          : options.enumerateRoots
            ? await executableRoots(root, view, files, options.signal)
            : { roots: [target], unclassified: [] };
      const roots = await requireMachoRoots(
        view,
        requested,
        parsed.data.roots !== undefined,
      );
      const trace = await traceDylibLoading(view, {
        roots,
        unclassified,
        ...(parsed.data.architecture === undefined
          ? {}
          : { architecture: parsed.data.architecture }),
        ...(options.signal === undefined ? {} : { signal: options.signal }),
      });
      // Each digest must describe the same file whose headers were parsed.
      const digests = new Map<string, string>();
      for (const { path } of trace.images)
        digests.set(
          path,
          await files.sha256(join(root, path), view.identity(path)),
        );
      const targetDigest =
        digests.get(target) ??
        (await files.sha256(join(root, target), undefined));
      if (targetDigest !== options.targetSha256)
        throw new ArtifactReaderFailure(
          "integrity",
          `Active target digest changed: expected ${options.targetSha256}, observed ${targetDigest}`,
        );
      assertArtifactReadActive(options.signal);
      return dylibResolutionResultSchema.parse({
        ...trace,
        root_path: options.rootPath,
        target_sha256: options.targetSha256,
        images: trace.images.map((image) => ({
          ...image,
          sha256: digests.get(image.path),
        })),
      });
    } catch (cause: unknown) {
      throw classifyDylibReadFailure(root, cause);
    }
  });
};

/**
 * Every Mach-O in the bundle with an executable slice is its own process root.
 * Mach-O files that do not parse are returned separately: whether they are
 * executables is unknown, so they make coverage partial instead of vanishing.
 */
const executableRoots = async (
  root: string,
  view: FilesystemTreeView,
  files: DylibFileAccess,
  signal?: AbortSignal,
): Promise<{ readonly roots: string[]; readonly unclassified: string[] }> => {
  const roots: string[] = [];
  const unclassified: string[] = [];
  // Bundles hold tens of thousands of files and few Mach-O images, so the
  // magic reads overlap the walk while results are classified in walk order.
  await consumeWithOrderedReads(
    new DirectoryArtifactReader(root).entries(signal),
    MAGIC_READ_CONCURRENCY,
    (entry) =>
      entry.kind === "file" ? files.startsWithMachoMagic(entry) : undefined,
    async (entry, macho) => {
      if (!macho) return;
      const facts = await view.image(entry.path);
      if (facts.status === "malformed" || facts.status === "unsupported")
        unclassified.push(entry.path);
      else if (
        facts.status === "parsed" &&
        facts.slices.some(({ file_type: type }) => type === "execute")
      )
        roots.push(entry.path);
    },
  );
  return {
    roots: roots.sort(compare),
    unclassified: unclassified.sort(compare),
  };
};

const compare = (left: string, right: string): number =>
  left < right ? -1 : left > right ? 1 : 0;

/**
 * Resolve each root segment by segment, as dependency candidates are, so a
 * symlink in an intermediate directory cannot lead outside the analyzed root.
 * A root the caller selected that fails is an input error on that root; a
 * root REA derived itself keeps reporting an artifact failure.
 */
const requireMachoRoots = async (
  view: FilesystemTreeView,
  roots: readonly string[],
  callerSelected: boolean,
): Promise<string[]> => {
  const resolved: string[] = [];
  for (const [index, path] of roots.entries()) {
    const reject = (
      reason: "path" | "format",
      message: string,
    ): AnalysisInputError | ArtifactReaderFailure =>
      callerSelected
        ? new AnalysisInputError(OPERATION, undefined, [
            { path: ["roots", index], reason: "invalid_value", message },
          ])
        : new ArtifactReaderFailure(reason, message);
    const lookup = await resolveTreePath(view, path);
    if (lookup.kind === "escapes")
      throw reject("path", `Root ${path} resolves outside the analyzed root`);
    if (lookup.kind !== "file")
      throw reject(
        "path",
        `Root ${path} is not a regular file in the analyzed root`,
      );
    if ((await view.image(lookup.path)).status === "not-mach-o")
      throw reject("format", `Root ${path} is not a Mach-O image`);
    if (!resolved.includes(lookup.path)) resolved.push(lookup.path);
  }
  return resolved;
};

const missing = (cause: unknown): boolean =>
  cause instanceof Error &&
  "code" in cause &&
  (cause.code === "ENOENT" || cause.code === "ENOTDIR");