Skip to content

armgit / rea

Public Imported from GitHub
0

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

13.7 KB
Raw Blame
import { z } from "zod";

import type { Evidence } from "../evidence.js";
import {
  createJavaScriptApplicationGraph,
  javascriptApplicationGraphSchema,
} from "../javascript/javascriptApplicationGraph.js";
import type {
  ApplicationEdge,
  ApplicationNode,
} from "../javascript/javascriptApplicationGraphSchemas.js";
import {
  managedArtifactInspectionSchema,
  managedMemberInspectionSchema,
  managedNativeBoundaryInspectionSchema,
  type ManagedArtifactInspection,
  type ManagedMemberInspection,
  type ManagedNativeBoundaryInspection,
} from "./managedArtifact.js";
import { digestCanonicalValue } from "../canonicalDigest.js";
import {
  assessManagedGraphOmissions,
  managedGraphEvidenceCoverage,
  managedGraphResultCoverage,
  type ManagedGraphProjectionOmissions,
} from "./managedApplicationGraphCoverage.js";
import {
  addArtifactNode,
  addArtifactIdentityNodes,
  addBoundaryNodes,
  addMemberNodes,
} from "./managedApplicationGraphNodes.js";
import {
  addMemberRelations,
  relationOmissionLimitations,
} from "./managedApplicationGraphRelations.js";
import { digestSchema } from "../digests.js";
import { prefixedDigestSchema } from "../digests.js";
import { readManagedInspectionEvidence } from "./managedInspectionEvidence.js";
import { AnalysisInputError } from "../analysisErrorCore.js";
import type { EvidenceIntegrityError } from "../evidenceErrors.js";
import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
import { err, ok, type Result } from "../result.js";

const evidenceIdSchema = prefixedDigestSchema("ev");
const textSchema = z.string().min(1);

/** Authenticated managed Evidence records projected into the application graph. */
const managedGraphRequestSchema = z
  .strictObject({
    managed_artifact: z.unknown().optional(),
    managed_members: z.unknown().optional(),
    managed_native_boundaries: z.unknown().optional(),
  })
  .superRefine((input, context) => {
    if (
      input.managed_artifact === undefined &&
      input.managed_members === undefined &&
      input.managed_native_boundaries === undefined
    )
      context.addIssue({
        code: "custom",
        message:
          "At least one managed artifact, member, or native-boundary Evidence record is required",
      });
  });

/** Managed-code projection result containing a validated application graph. */
export const managedApplicationGraphResultSchema = z.strictObject({
  projection_id: prefixedDigestSchema("magp"),
  root_artifact_sha256: digestSchema,
  source_evidence: z.strictObject({
    managed_artifact_evidence_id: evidenceIdSchema.nullable(),
    managed_members_evidence_id: evidenceIdSchema.nullable(),
    managed_native_boundaries_evidence_id: evidenceIdSchema.nullable(),
  }),
  summary: z.strictObject({
    graph_nodes: z.int().min(0),
    graph_edges: z.int().min(0),
    assemblies: z.int().min(0),
    modules: z.int().min(0),
    types: z.int().min(0),
    methods: z.int().min(0),
    fields: z.int().min(0),
    pinvoke_imports: z.int().min(0),
    native_implementations: z.int().min(0),
    // Graphs projected before call and field-access edges existed omit these
    // counters; null means those relations were not projected, not zero.
    calls: z
      .int()
      .min(0)
      .nullable()
      .default(null)
      .describe("calls edges; null for graphs projected before calls edges"),
    field_accesses: z
      .int()
      .min(0)
      .nullable()
      .default(null)
      .describe(
        "accesses edges; null for graphs projected before accesses edges",
      ),
  }),
  graph: javascriptApplicationGraphSchema,
  coverage: z.strictObject({
    status: z.enum(["complete-within-inputs", "partial"]),
  }),
  evidence_links: z.array(evidenceIdSchema).min(1).max(3),
  limitations: z.array(textSchema),
});

export type ManagedApplicationGraphResult = z.infer<
  typeof managedApplicationGraphResultSchema
>;

export interface ParsedManagedGraphInput {
  readonly artifact: {
    readonly evidence: Evidence;
    readonly result: ManagedArtifactInspection;
  } | null;
  readonly members: {
    readonly evidence: Evidence;
    readonly result: ManagedMemberInspection;
  } | null;
  readonly boundaries: {
    readonly evidence: Evidence;
    readonly result: ManagedNativeBoundaryInspection;
  } | null;
}

export interface GraphBuildState {
  readonly nodes: ApplicationNode[];
  readonly edges: ApplicationEdge[];
  readonly artifactSha256: string;
  readonly artifactPath: string;
  readonly evidenceLinks: string[];
  readonly typeNodes: Map<string, ApplicationNode>;
  readonly methodNodes: Map<string, ApplicationNode>;
  readonly fieldNodes: Map<string, ApplicationNode>;
}

export interface ManagedGraphProjection {
  readonly sources: ParsedManagedGraphInput;
  readonly artifact: { readonly sha256: string; readonly path: string };
}

/** Build from authenticated sources whose shared identity has been established. */
export const projectManagedGraph = (
  request: ManagedGraphProjection,
): ManagedApplicationGraphResult => {
  const { sources: parsed, artifact: artifactIdentity } = request;
  const evidenceLinks = [
    parsed.artifact?.evidence.evidence_id,
    parsed.members?.evidence.evidence_id,
    parsed.boundaries?.evidence.evidence_id,
  ].filter((id): id is string => id !== undefined);
  const state: GraphBuildState = {
    nodes: [],
    edges: [],
    artifactSha256: artifactIdentity.sha256,
    artifactPath: artifactIdentity.path,
    evidenceLinks,
    typeNodes: new Map(),
    methodNodes: new Map(),
    fieldNodes: new Map(),
  };
  const artifactNode = addArtifactNode(state);
  addArtifactIdentityNodes(state, artifactNode, parsed);
  addMemberNodes(state, artifactNode, parsed);
  addBoundaryNodes(state, artifactNode, parsed);
  const relations = addMemberRelations(state, parsed);
  const omissions = assessManagedGraphOmissions(
    {
      artifact: parsed.artifact?.result ?? null,
      members: parsed.members?.result ?? null,
      boundaries: parsed.boundaries?.result ?? null,
    },
    relations,
  );
  const limitations = projectionLimitations(parsed, omissions);
  const graph = createJavaScriptApplicationGraph({
    schema: "JavaScriptApplicationGraph",
    root_node_ids: [artifactNode.node_id],
    nodes: state.nodes,
    edges: state.edges,
    coverage: managedGraphEvidenceCoverage(omissions),
    limitations,
  });
  const withoutId = {
    root_artifact_sha256: state.artifactSha256,
    source_evidence: {
      managed_artifact_evidence_id:
        parsed.artifact?.evidence.evidence_id ?? null,
      managed_members_evidence_id: parsed.members?.evidence.evidence_id ?? null,
      managed_native_boundaries_evidence_id:
        parsed.boundaries?.evidence.evidence_id ?? null,
    },
    summary: {
      graph_nodes: graph.nodes.length,
      graph_edges: graph.edges.length,
      assemblies: countNodes(graph.nodes, "managed-assembly"),
      modules: countNodes(graph.nodes, "managed-module"),
      types: countNodes(graph.nodes, "managed-type"),
      methods: countNodes(graph.nodes, "managed-method"),
      fields: countNodes(graph.nodes, "managed-field"),
      pinvoke_imports: countNodes(graph.nodes, "managed-pinvoke-import"),
      native_implementations: countNodes(
        graph.nodes,
        "managed-native-implementation",
      ),
      calls: countEdges(graph.edges, "calls"),
      field_accesses: countEdges(graph.edges, "accesses"),
    },
    graph,
    coverage: managedGraphResultCoverage(omissions),
    evidence_links: evidenceLinks,
    limitations,
  };
  return managedApplicationGraphResultSchema.parse({
    ...withoutId,
    projection_id: `magp_${digestCanonicalValue(
      withoutId,
      "Managed application graph",
    )}`,
  });
};

const countNodes = (
  nodes: readonly ApplicationNode[],
  kind: ApplicationNode["kind"],
): number => nodes.filter((node) => node.kind === kind).length;

const countEdges = (
  edges: readonly ApplicationEdge[],
  relation: ApplicationEdge["relation"],
): number => edges.filter((edge) => edge.relation === relation).length;

/** Authenticate each source once, then establish the shared projection identity. */
export const readManagedGraphProjection = (
  input: unknown,
): Result<
  ManagedGraphProjection,
  AnalysisInputError | EvidenceIntegrityError
> => {
  const frame = managedGraphRequestSchema.safeParse(input);
  if (!frame.success)
    return err(
      analysisInputErrorFromIssues(OPERATION, frame.error.issues, input, {
        cause: frame.error,
      }),
    );
  const { managed_artifact, managed_members, managed_native_boundaries } =
    frame.data;
  const artifact =
    managed_artifact === undefined
      ? ok(null)
      : readManagedInspectionEvidence(
          managed_artifact,
          "inspect_managed_artifact",
          managedArtifactInspectionSchema,
          { operation: OPERATION, path: ["managed_artifact"] },
        );
  if (!artifact.ok) return artifact;
  const members =
    managed_members === undefined
      ? ok(null)
      : readManagedInspectionEvidence(
          managed_members,
          "inspect_managed_members",
          managedMemberInspectionSchema,
          { operation: OPERATION, path: ["managed_members"] },
        );
  if (!members.ok) return members;
  const boundaries =
    managed_native_boundaries === undefined
      ? ok(null)
      : readManagedInspectionEvidence(
          managed_native_boundaries,
          "inspect_managed_native_boundaries",
          managedNativeBoundaryInspectionSchema,
          { operation: OPERATION, path: ["managed_native_boundaries"] },
        );
  if (!boundaries.ok) return boundaries;
  const sources = {
    artifact: artifact.value,
    members: members.value,
    boundaries: boundaries.value,
  };
  const identity = chooseArtifact(sources);
  const mismatch =
    artifactMismatch(sources, identity.sha256) ??
    moduleIdentityMismatch(sources);
  if (mismatch !== null)
    return err(
      new AnalysisInputError(OPERATION, { userMessage: mismatch }, [
        { path: [], reason: "invalid_value", message: mismatch },
      ]),
    );
  return ok({ sources, artifact: identity });
};

const OPERATION = "project_managed_application_graph";

const chooseArtifact = (
  parsed: ParsedManagedGraphInput,
): { readonly sha256: string; readonly path: string } => {
  const result =
    parsed.artifact?.result ??
    parsed.members?.result ??
    parsed.boundaries?.result;
  if (result === undefined)
    throw new Error("Validated managed graph projection has no source");
  return { sha256: result.artifact.sha256, path: result.artifact.path };
};

const artifactMismatch = (
  parsed: ParsedManagedGraphInput,
  sha256Value: string,
): string | null => {
  for (const result of [
    parsed.artifact?.result,
    parsed.members?.result,
    parsed.boundaries?.result,
  ])
    if (result !== undefined && result.artifact.sha256 !== sha256Value)
      return "Managed graph projection inputs must describe the same artifact SHA-256";
  return null;
};

/** Reject contradictory known module identities while leaving null fields unknown. */
const moduleIdentityMismatch = (
  parsed: ParsedManagedGraphInput,
): string | null => {
  const mvidClaims = [
    parsed.artifact?.result.module?.mvid,
    parsed.members?.result.module?.mvid,
    parsed.members?.result.identity_scope.requires_mvid,
    parsed.boundaries?.result.module?.mvid,
    parsed.boundaries?.result.identity_scope.requires_mvid,
  ]
    .filter((mvid): mvid is string => mvid !== undefined && mvid !== null)
    .map((mvid) => mvid.toLowerCase());
  if (new Set(mvidClaims).size > 1)
    return "Managed graph inputs report conflicting known module MVIDs or token scopes";

  const modules = [
    parsed.artifact?.result.module,
    parsed.members?.result.module,
    parsed.boundaries?.result.module,
  ].filter(
    (module): module is NonNullable<ManagedArtifactInspection["module"]> =>
      module !== undefined && module !== null,
  );
  for (const field of ["name", "generation", "token", "row_offset"] as const) {
    const values = new Set(modules.map((module) => module[field]));
    if (values.size > 1)
      return `Managed graph inputs report conflicting module ${field} values`;
  }
  for (const field of ["enc_id", "enc_base_id"] as const) {
    const values = new Set(
      modules
        .map((module) => module[field]?.toLowerCase())
        .filter((value): value is string => value !== undefined),
    );
    if (values.size > 1)
      return `Managed graph inputs report conflicting module ${field} values`;
  }
  return null;
};

const projectionLimitations = (
  parsed: ParsedManagedGraphInput,
  omissions: ManagedGraphProjectionOmissions,
): string[] => [
  "Managed graph projection preserves static metadata observations only; it does not execute managed code, load assemblies, or map managed tokens to native addresses.",
  ...(parsed.members === null
    ? [
        "Managed member Evidence was not supplied; type, method, and field nodes are absent.",
      ]
    : []),
  ...(parsed.artifact === null
    ? [
        "Managed artifact Evidence was not supplied; assembly identity observations are absent.",
      ]
    : []),
  ...(parsed.boundaries === null
    ? [
        "Managed native-boundary Evidence was not supplied; P/Invoke and native-implementation nodes are absent.",
      ]
    : []),
  ...(omissions.partialInput
    ? ["At least one supplied managed Evidence record has partial coverage."]
    : []),
  ...(omissions.selectedTypes === null
    ? []
    : [
        `Managed member Evidence selected only these declaring types: ${omissions.selectedTypes.join(", ")}; type, method, and field nodes of other types are omitted, not absent.`,
      ]),
  ...(omissions.unscopedTokenRelationships
    ? [
        "Managed boundary tokens were not linked to member nodes because matching module MVID scope was not established.",
      ]
    : []),
  ...relationOmissionLimitations(omissions.relations),
];