Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import {
admitManagedProjection,
managedDecodeBudget,
ManagedRepresentationFailure,
} from "./ManagedDecodeBudget.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import {
managedMemberInspectionSchema,
type ManagedMemberInspection,
type ManagedParseIssue,
} from "../domain/managed/managedArtifact.js";
import {
readManagedPeLayout,
type ManagedPeLayout,
} from "./ManagedPeReader.js";
import {
readManagedResourceDirectory,
readManagedMetadataInventory,
readManagedModuleIdentity,
} from "./ManagedMetadataInventory.js";
import { managedPeInspectionEnvelope } from "./ManagedPeInspectionEnvelope.js";
import { readManagedMetadataLayout } from "./ManagedMetadataLayout.js";
import {
appendManagedParseIssues,
ManagedReaderFailure,
uniqueManagedParseIssues,
} from "./ManagedReaderFailure.js";
import {
parseTypes,
typeRanges,
type TypeRange,
} from "./ManagedMemberInspectorCore.js";
import { edgeTargets } from "./ManagedMethodSpecs.js";
import { managedTypeNameDigests } from "./ManagedTypeNameDigests.js";
import { typeNameLookup } from "./ManagedTypeNames.js";
import { managedTypeReferences } from "./ManagedTypeReferences.js";
import { parseUserStrings } from "./ManagedUserStrings.js";
import { readTypeMemberListFacts } from "./ManagedTypeMemberLists.js";
import { prepareManagedMemberRecovery } from "./ManagedMemberRecovery.js";
import {
edges,
parseExportedTypes,
parseFields,
parseMemberRefs,
parseMethods,
type SelectedTypeTokens,
} from "./ManagedMemberRows.js";
const unavailable = (
target: BinaryTarget,
bytes: Buffer,
issue: ManagedParseIssue | null,
typeNames: readonly string[] | undefined,
): ManagedMemberInspection =>
managedMemberInspectionSchema.parse(
admitManagedProjection({
artifact: {
path: target.path,
sha256: target.sha256,
byte_length: bytes.length,
format: "pe",
},
module: null,
metadata: {
status:
issue === null
? "absent"
: issue.code === "resource-limit"
? "partial"
: "malformed",
version: null,
table_row_counts: {},
},
identity_scope: {
token_identity: "build-local",
requires_artifact_sha256: target.sha256,
requires_mvid: null,
},
types: [],
signature_resolution: "type-names-v1",
nesting_read: false,
exported_types: null,
user_strings: null,
fields: [],
methods: [],
member_refs: [],
call_edges: [],
field_accesses: [],
// Nothing was examined, so no requested name is known to be unmatched.
selection:
typeNames === undefined
? null
: { type_names: [...typeNames], unmatched_type_names: [] },
coverage: {
state: "unavailable",
issues: issue === null ? [] : [issue],
},
limitations: [
issue === null
? "The PE has no admitted CLI metadata; managed member inspection is unavailable."
: "The CLI metadata could not be admitted; managed member inspection is unavailable.",
],
}),
);
const readMemberLayout = (bytes: Buffer, pe: ManagedPeLayout) => {
const cli = pe.cli;
if (cli === null)
throw new TypeError("Managed inventory requires CLI metadata");
const rootOffset = pe.rvaToOffset(
cli.metadata.rva,
cli.metadata.size,
"cli.metadata",
);
const layout = readManagedMetadataLayout(
bytes,
rootOffset,
cli.metadata.size,
);
const memberLists = readTypeMemberListFacts(bytes, layout);
return { layout, memberLists };
};
const selectTypes = (
ranges: readonly TypeRange[],
typeNames: readonly string[] | undefined,
): {
readonly tokens: SelectedTypeTokens;
readonly selection: ManagedMemberInspection["selection"];
readonly unreadableNames: number;
} => {
if (typeNames === undefined)
return { tokens: null, selection: null, unreadableNames: 0 };
const requested = new Set(typeNames);
const tokens = new Set<string>();
const matched = new Set<string>();
for (const range of ranges) {
if (range.fullName === null || !requested.has(range.fullName)) continue;
tokens.add(range.token);
matched.add(range.fullName);
}
return {
tokens,
unreadableNames: ranges.filter(({ fullName }) => fullName === null).length,
selection: {
type_names: [...typeNames],
unmatched_type_names: typeNames.filter((name) => !matched.has(name)),
},
};
};
/**
* Inspect metadata members and method bodies without loading target code.
* Selected type names restrict full decoding to members of those exact types.
* A caller that never reads literals, such as member comparison, can skip
* user strings; they are then reported as not examined.
*/
export const inspectManagedMembersBytes = (
bytes: Buffer,
target: BinaryTarget,
{
typeNames,
methodOffset = 0,
methodLimit = Number.MAX_SAFE_INTEGER,
userStrings: readUserStrings = true,
}: {
readonly typeNames?: readonly string[];
/** Zero-based offset into MethodDef rows. */
readonly methodOffset?: number;
readonly methodLimit?: number;
readonly userStrings?: boolean;
} = {},
): ManagedMemberInspection => {
if (
!Number.isSafeInteger(methodOffset) ||
methodOffset < 0 ||
!Number.isSafeInteger(methodLimit) ||
methodLimit < 0
)
throw new RangeError(
"methodOffset and methodLimit must be non-negative safe integers",
);
const pe = readManagedPeLayout(bytes);
if (pe.cli === null)
return unavailable(target, bytes, pe.cliIssue, typeNames);
const issues: ManagedParseIssue[] = [];
let recover: ReturnType<typeof prepareManagedMemberRecovery> | undefined;
try {
const { layout, memberLists } = readMemberLayout(bytes, pe);
const identity = readManagedModuleIdentity(bytes, layout);
appendManagedParseIssues(issues, identity.issues);
const ranges = typeRanges(bytes, layout, issues, memberLists);
const {
tokens: selected,
selection,
unreadableNames,
} = selectTypes(ranges, typeNames);
const parsedTypes = parseTypes(bytes, layout, ranges);
appendManagedParseIssues(issues, parsedTypes.issues);
const typeReferences = managedTypeReferences(bytes, layout, issues);
const signatureTypeName = managedTypeNameDigests(
layout,
issues,
parsedTypes,
typeReferences,
);
const types = parsedTypes.types
.filter((type) => selected === null || selected.has(type.token))
.map((type) => {
managedDecodeBudget(layout).reserve(512, type.row_offset);
return {
...type,
name_sha256:
signatureTypeName(
Number.parseInt(type.token.slice(4), 16) * 4,
)?.toString("hex") ?? null,
};
});
const envelope = managedPeInspectionEnvelope(
target,
bytes.length,
layout,
identity.module,
issues,
);
const unnamedTypes = types.reduce(
(count, type) => count + Number(type.name_sha256 === null),
0,
);
const typeIdentityLimitations =
unnamedTypes === 0
? []
: [
`${String(unnamedTypes)} returned TypeDef name identity(s) remain unresolved; incomplete, missing, contradictory, cyclic or over-deep enclosing facts cannot be repaired by bare display names.`,
];
const selectionLimitations = [
...(selection === null
? []
: [
"Types, fields, methods, call edges, field accesses, and user strings cover only the selected declaring types; coverage describes that selection. Edge targets outside it keep their names but are not described.",
]),
...(unreadableNames === 0
? []
: [
`${String(unreadableNames)} TypeDef name(s) could not be read; a name in selection.unmatched_type_names may belong to one of them, so its absence is not observed.`,
]),
];
recover = prepareManagedMemberRecovery(
{
...envelope,
types,
nesting_read: parsedTypes.nesting.complete,
selection,
limitations: [...typeIdentityLimitations, ...selectionLimitations],
},
uniqueManagedParseIssues(issues),
managedDecodeBudget(layout),
);
const inventory = readManagedMetadataInventory(
bytes,
layout,
readManagedResourceDirectory(pe, issues),
memberLists,
identity,
);
appendManagedParseIssues(issues, inventory.issues);
const exportedTypes = parseExportedTypes(bytes, layout);
appendManagedParseIssues(issues, exportedTypes.issues);
const fields = parseFields(bytes, layout, ranges, memberLists, {
signatureTypeName,
selected,
});
const memberRefs = parseMemberRefs(
bytes,
layout,
typeNameLookup(bytes, layout, ranges, issues, typeReferences),
signatureTypeName,
);
appendManagedParseIssues(issues, memberRefs.issues);
const methods = parseMethods({
bytes,
layout,
pe,
ranges,
signatureTypeName,
memberRefKinds: new Map(
memberRefs.refs.flatMap((memberRef) =>
memberRef.signature.kind === "field" ||
memberRef.signature.kind === "method"
? [[memberRef.token, memberRef.signature.kind] as const]
: [],
),
),
memberLists,
selected,
methodOffset,
methodLimit,
});
appendManagedParseIssues(issues, fields.issues, methods.issues);
// #US literals sit beside the member inventory and carry their own
// coverage, so their issues never make member facts partial.
const userStrings = readUserStrings
? parseUserStrings(bytes, layout, {
...methods,
unreadableSelectedTypes: unreadableNames,
})
: null;
const targets = edgeTargets(bytes, layout, methods.methods, [
fields.core,
memberRefs.core,
methods.core,
]);
appendManagedParseIssues(issues, targets.issues);
const incompleteMembers =
[...fields.fields, ...memberRefs.refs, ...methods.methods].some(
(member) => member.signature.parse_status !== "decoded",
) ||
methods.methods.some(
(method) =>
method.body.status === "partial" ||
method.body.status === "malformed",
);
const related = edges(
methods.methods,
targets.members,
managedDecodeBudget(layout),
);
const coverageIssues = uniqueManagedParseIssues(issues);
return managedMemberInspectionSchema.parse(
admitManagedProjection(
{
...envelope,
metadata: {
...envelope.metadata,
status: issues.length === 0 ? "complete" : "partial",
},
types,
signature_resolution: "type-names-v1",
nesting_read: parsedTypes.nesting.complete,
exported_types: exportedTypes.exportedTypes,
fields: fields.fields,
methods: methods.methods,
member_refs: memberRefs.refs,
call_edges: related.callEdges,
field_accesses: related.fieldAccesses,
user_strings: userStrings,
selection,
coverage: {
state:
issues.length === 0 && !incompleteMembers
? "complete"
: "partial",
issues: coverageIssues,
},
limitations: [
...typeIdentityLimitations,
"Metadata tokens are build-local coordinates and are only meaningful with the reported artifact SHA-256 and MVID.",
"CIL instruction anchors are decoded from file-backed method bodies only; no target assembly is loaded or executed.",
"Exported types are reported from ExportedType rows as declared; forwarded types are not resolved in their implementing assemblies.",
"User strings are the #US literals loaded by ldstr in the inspected method bodies, with their own coverage; instruction anchors and normalized CIL digests keep their build-local tokens.",
"Member signatures decode ECMA-335 primitive, class, valuetype, generic instantiation, generic variable, pointer, byref, single-dimension and general array, function pointer, custom modifier, and typed reference forms; class and valuetype operands keep their encoded TypeDefOrRefOrSpec values, and unsupported forms such as vararg sentinels retain raw signature hashes.",
...selectionLimitations,
],
},
managedDecodeBudget(layout),
),
);
} catch (cause: unknown) {
if (cause instanceof ManagedReaderFailure) {
if (
recover !== undefined &&
cause instanceof ManagedRepresentationFailure
)
return recover(cause.issue.offset);
return unavailable(target, bytes, cause.issue, typeNames);
}
throw cause;
}
};