Skip to content

armgit / rea

Public Imported from GitHub
0

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

9.5 KB
Raw Blame
import {
  bindArtifactFileCleanup,
  artifactFileCancellationCause,
} from "../../artifacts/ArtifactFileOperation.js";
import { access, mkdir, stat, writeFile } from "node:fs/promises";
import { constants } from "node:fs";
import { randomUUID } from "node:crypto";
import { isAbsolute, join } from "node:path";
import { fileURLToPath } from "node:url";
import { z } from "zod";
import type { ExecutionOptions } from "../../application/AnalysisProvider.js";
import type { AnalysisCapturedOutput } from "../../domain/analysisErrorBase.js";
import {
  AnalysisCancelledError,
  AnalysisCapabilityUnavailableError,
  AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import {
  recordedCrashDebuggerSchema,
  type RecordedCrash,
} from "../../domain/native/recordedCrash.js";
import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
  capturedPwntoolsOutput,
  pwntoolsDecoderFailure,
} from "../pwntools/PwntoolsFailures.js";
import { PWNTOOLS_LIMITS } from "../pwntools/PwntoolsRelease.js";
import { readPwntoolsFailureEvidence } from "../pwntools/PwntoolsResourceLimits.js";
import type { PwntoolsCommand } from "../pwntools/PwntoolsDecoder.js";

const OPERATION = "inspect_recorded_crash";
const replySchema = z.discriminatedUnion("ok", [
  z.strictObject({ ok: z.literal(true), value: recordedCrashDebuggerSchema }),
  z.strictObject({
    ok: z.literal(false),
    reason: z.enum([
      "unavailable",
      "unsupported",
      "decoder",
      "format",
      "output-limit",
    ]),
    message: z.string(),
  }),
]);

/** Add mapping candidates from an owned core-only debugger, using the existing snapshot. */
export const inspectPwndbgCore = async ({
  environment,
  architecture,
  rootPath,
  resources,
  diagnostics,
  options,
  runCommand,
  timeoutMs,
  probePath,
}: {
  readonly environment: Readonly<NodeJS.ProcessEnv>;
  readonly architecture: RecordedCrash["architecture"];
  readonly rootPath: string;
  readonly resources: ArtifactResourceScope;
  readonly diagnostics: AnalysisCapturedOutput;
  readonly options: ExecutionOptions | undefined;
  readonly runCommand: PwntoolsCommand;
  /** Effective `pwntools_timeout_ms` for this debugger command. */
  readonly timeoutMs: number;
  readonly probePath?: (
    path: string,
    kind: "file" | "directory",
    mode: number,
  ) => Promise<void>;
}): Promise<RecordedCrash["debugger"]> => {
  const gdb = environment.REA_PWNDBG_GDB ?? "/usr/bin/gdb";
  const entry = environment.REA_PWNDBG_GDBINIT ?? "";
  const venv = environment.REA_PWNDBG_VENV_PATH ?? "";
  const unavailable = (message: string, cause?: unknown) =>
    new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, message, {
      ...(cause === undefined ? {} : { cause }),
      userMessage: message,
      capturedOutput: diagnostics,
    });
  const checkCancelled = () => {
    if (options?.signal?.aborted)
      throw new AnalysisCancelledError(OPERATION, {
        cause: options.signal.reason,
        capturedOutput: diagnostics,
      });
  };
  checkCancelled();
  for (const [key, path, kind] of [
    ["REA_PWNDBG_GDB", gdb, "file"],
    ["REA_PWNDBG_GDBINIT", entry, "file"],
    ["REA_PWNDBG_VENV_PATH", venv, "directory"],
  ] as const) {
    try {
      checkCancelled();
      if (!isAbsolute(path))
        throw new Error("Expected an absolute caller-supplied path.");
      const mode = key === "REA_PWNDBG_GDB" ? constants.X_OK : constants.R_OK;
      if (probePath !== undefined) {
        await probePath(path, kind, mode);
      } else {
        await access(path, mode);
        checkCancelled();
        const information = await stat(path);
        checkCancelled();
        if (
          kind === "file" ? !information.isFile() : !information.isDirectory()
        )
          throw new Error(`Expected a ${kind}.`);
      }
      checkCancelled();
    } catch (cause: unknown) {
      if (cause instanceof AnalysisCancelledError) throw cause;
      throw unavailable(
        `${key} is unavailable at ${path}: ${cause instanceof Error ? cause.message : String(cause)}. Configure the requested core-only context, or omit include_debugger_context for basic recorded evidence.`,
        cause,
      );
    }
  }
  checkCancelled();
  const stage = join(rootPath, "debugger");
  await mkdir(stage, { mode: 0o700 });
  const requestPath = join(stage, "request.json");
  const replyPath = join(stage, "reply.json");
  await writeFile(
    requestPath,
    JSON.stringify({
      snapshot_path: join(rootPath, "object.snapshot"),
      reply_path: replyPath,
      gdb,
      architecture,
      gdbinit: entry,
      venv,
    }),
    { flag: "wx", mode: 0o600 },
  );
  let output: AnalysisCapturedOutput | undefined;
  const failureContext = {
    operation: OPERATION,
    providerId: "pwndbg-core",
    precedingOutput: diagnostics,
    timeoutMs,
  };
  const failure = (cause: unknown) =>
    pwntoolsDecoderFailure(
      cause,
      "debugger",
      gdb,
      environment.REA_PWNTOOLS_PYTHON ?? "",
      {},
      failureContext,
    );
  try {
    checkCancelled();
    const execution = await runCommand(
      {
        command: environment.REA_PWNTOOLS_PYTHON ?? "",
        arguments: [
          "-I",
          fileURLToPath(
            new URL("../../../bridge/pwndbg/launch.py", import.meta.url),
          ),
          join(stage, "resource.failure"),
          requestPath,
        ],
        cwd: stage,
        runId: `rea-recorded-core-debugger-${randomUUID()}`,
        hostEnvironment: {
          ...environment,
          PWNDBG_NO_AUTOUPDATE: "1",
          PWNDBG_VENV_PATH: venv,
          PWNLIB_NOTERM: "1",
          TERM: "dumb",
          HOME: stage,
          XDG_CACHE_HOME: join(stage, "cache"),
          XDG_CONFIG_HOME: join(stage, "config"),
          PYTHONNOUSERSITE: "1",
          OPENBLAS_NUM_THREADS: "1",
          OMP_NUM_THREADS: "1",
        },
      },
      failure,
    );
    output = capturedPwntoolsOutput(execution);
    let reply: z.output<typeof replySchema>;
    try {
      const raw = await readStableArtifact(
        replyPath,
        PWNTOOLS_LIMITS.outputBytes,
        options?.signal,
        undefined,
        resources,
      );
      reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8")));
    } catch (cause: unknown) {
      if (
        cause instanceof ArtifactReaderFailure &&
        cause.reason === "cancelled"
      ) {
        const error = new AnalysisCancelledError(OPERATION, {
          cause: artifactFileCancellationCause(cause),
          capturedOutput: recordedCrashStageOutput(diagnostics, output),
          ...(cause instanceof ArtifactReaderFailure &&
          cause.cleanup !== undefined
            ? { cleanup: cause.cleanup }
            : {}),
        });
        bindArtifactFileCleanup(cause, error);
        throw error;
      }
      const error = new AnalysisOutputError(
        OPERATION,
        `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`,
        {
          cause,
          ...(cause instanceof ArtifactReaderFailure
            ? { cleanup: cause.cleanup }
            : {}),
          capturedOutput: recordedCrashStageOutput(diagnostics, output),
        },
      );
      bindArtifactFileCleanup(cause, error);
      throw error;
    }
    if (!reply.ok) {
      if (reply.reason === "unavailable" || reply.reason === "unsupported")
        throw new AnalysisCapabilityUnavailableError(
          "pwndbg-core",
          OPERATION,
          reply.message,
          {
            userMessage: reply.message,
            capturedOutput: recordedCrashStageOutput(diagnostics, output),
          },
        );
      if (reply.reason === "format" || reply.reason === "output-limit")
        throw new AnalysisOutputError(OPERATION, reply.message, {
          capturedOutput: recordedCrashStageOutput(diagnostics, output),
        });
      throw new ProviderAdapterError("pwndbg-core", OPERATION, {
        diagnostics: {
          stage: "debugger",
          reason: reply.message,
          captured_output: { ...recordedCrashStageOutput(diagnostics, output) },
        },
      });
    }
    if (reply.value.status !== "available")
      throw new AnalysisOutputError(
        OPERATION,
        "Requested debugger context returned no core evidence.",
        { capturedOutput: recordedCrashStageOutput(diagnostics, output) },
      );
    return { ...reply.value, diagnostics: output };
  } catch (cause: unknown) {
    if (cause instanceof AnalysisError && cause.cleanupIncomplete) throw cause;
    const primary = pwntoolsDecoderFailure(
      cause,
      "debugger",
      gdb,
      environment.REA_PWNTOOLS_PYTHON ?? "",
      await readPwntoolsFailureEvidence(cause, stage, resources),
      failureContext,
    );
    throw primary;
  }
};

/** Preserve both stages' exact text and their independently observed truncation state. */
export const recordedCrashStageOutput = (
  basic: AnalysisCapturedOutput,
  debuggerOutput?: AnalysisCapturedOutput,
): AnalysisCapturedOutput =>
  debuggerOutput === undefined
    ? basic
    : {
        stdout: `[core decoder]\n${basic.stdout}\n[debugger]\n${debuggerOutput.stdout}`,
        stderr: `[core decoder]\n${basic.stderr}\n[debugger]\n${debuggerOutput.stderr}`,
        truncated: basic.truncated || debuggerOutput.truncated,
      };