feat(evm): inspect offline bytecode interfaces through EVMole (#1051)

* feat(evm): inspect offline bytecode interfaces through evmole

* fix(evm): distinguish unsupported bytecode targets

* style(evm): format verifier string-prefix checks
This commit is contained in:
Ysopwnable
2026-10-08 15:32:05 +08:00
committed by GitHub
parent c5d165bd03
commit 7af7bc88ce
62 changed files with 3250 additions and 63 deletions
+9
View File
@@ -31,6 +31,7 @@ type ToolAvailabilityReason = "available" | ToolUnavailabilityReason;
type ProviderDescriptor = ProviderCapability;
export type AvailabilityPolicy = {
readonly evmInterfaceEnabled?: boolean;
readonly processCaptureEnabled: boolean;
readonly optionalProviderLoadFailures?: OptionalProviderLoadFailures;
readonly binaryLayoutEnabled?: boolean;
@@ -289,6 +290,14 @@ const workflowAvailabilityFor = ({
remediation:
"On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.",
};
if (name === "inspect_evm_interface")
return policy.evmInterfaceEnabled === true
? { reason: "available", remediation: null }
: {
reason: "provider_missing",
remediation:
"The bundled offline EVM interface profile is currently real-verified on Linux x64. No active binary target or chain endpoint is required.",
};
if (kind === "firmware-provider") {
const enabled =
name === "inspect_firmware_regions"
+15
View File
@@ -0,0 +1,15 @@
import type {
AnalysisExecution,
ExecutionOptions,
} from "../AnalysisProvider.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { InspectEvmInterfaceInput } from "../../domain/evm/evmInterface.js";
import type { Result } from "../../domain/result.js";
/** Replaceable offline interface-recovery engine, independent of wallets and chain clients. */
export interface EvmInterfacePort {
inspect(
input: InspectEvmInterfaceInput,
options?: ExecutionOptions,
): Promise<Result<AnalysisExecution, AnalysisError>>;
}
@@ -0,0 +1,124 @@
import { expect, it } from "vitest";
import { EvmInterfaceService } from "./EvmInterfaceService.js";
import {
evmInterfaceExecution,
evmInterfaceFixture,
} from "../../../tests/fixtures/evm/interface.js";
import { err, ok } from "../../domain/result.js";
import { parseEvidence } from "../../domain/evidence.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
it("returns full inline inferred Evidence and unmodified upstream representation", async () => {
const value = evmInterfaceFixture();
const service = new EvmInterfaceService({
inspect: () => Promise.resolve(ok(evmInterfaceExecution(value))),
});
const result = await service.inspect({
path: value.artifact.path,
encoding: "hex",
});
if (!result.ok) throw result.error;
const evidence = parseEvidence(result.value);
expect(evidence.normalized_result).toEqual(value);
expect(evidence.raw_result).toEqual({ functions: [] });
expect(evidence.confidence).toBe("inferred");
expect(evidence.subject?.digest.sha256).toBe(value.artifact.sha256);
});
it.each([
{ path: "relative.hex", encoding: "hex" },
{ path: "/selected", encoding: "auto" },
{ path: "/selected" },
{ path: "/selected", encoding: "raw", approval: true },
])("rejects invalid selection before effects: %j", async (input) => {
const service = new EvmInterfaceService({
inspect: () => {
throw new Error("must not start");
},
});
expect(await service.inspect(input)).toMatchObject({
ok: false,
error: { _tag: "AnalysisInputError" },
});
});
it.each(["carrier", "encoding", "digest", "no-subject"])(
"rejects mismatched producer binding: %s",
async (problem) => {
const value = evmInterfaceFixture();
if (problem === "carrier") value.artifact.path = "/other";
if (problem === "encoding") value.artifact.encoding = "raw";
const observed = evmInterfaceExecution(value);
const execution = {
...observed,
subject:
problem === "no-subject"
? null
: {
path: "/artifacts/source-owned.hex",
sha256:
problem === "digest" ? "b".repeat(64) : value.artifact.sha256,
format: "file" as const,
},
};
const service = new EvmInterfaceService({
inspect: () => Promise.resolve(ok(execution)),
});
expect(
await service.inspect({
path: "/artifacts/source-owned.hex",
encoding: "hex",
}),
).toMatchObject({
ok: false,
error: { _tag: "AnalysisOutputError", capturedOutput: value.diagnostics },
});
},
);
it("preserves meaningful provider failure and cancellation before/after execution", async () => {
const failure = new AnalysisCapabilityUnavailableError(
"evm",
"inspect_evm_interface",
"Selected limiter missing",
);
const service = new EvmInterfaceService({
inspect: () => Promise.resolve(err(failure)),
});
expect(await service.inspect({ path: "/code", encoding: "raw" })).toEqual(
err(failure),
);
const controller = new AbortController();
const observed = evmInterfaceFixture();
observed.diagnostics = {
stdout: "selected\u0000",
stderr: "warning",
truncated: true,
};
const cancelled = new EvmInterfaceService({
inspect: () => {
controller.abort();
return Promise.resolve(ok(evmInterfaceExecution(observed)));
},
});
expect(
await cancelled.inspect(
{ path: "/artifacts/source-owned.hex", encoding: "hex" },
{ signal: controller.signal },
),
).toMatchObject({
ok: false,
error: {
_tag: "AnalysisCancelledError",
capturedOutput: observed.diagnostics,
},
});
const untouched = new EvmInterfaceService({
inspect: () => {
throw new Error("must not start");
},
});
expect(
await untouched.inspect(
{ path: "/code", encoding: "raw" },
{ signal: controller.signal },
),
).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });
});
@@ -0,0 +1,92 @@
import { isAbsolute } from "node:path";
import { z } from "zod";
import type { ExecutionOptions } from "../AnalysisProvider.js";
import type { EvmInterfacePort } from "./EvmInterfacePort.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
AnalysisInputError,
AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
import {
inspectEvmInterfaceInputSchema,
evmInterfaceSchema,
} from "../../domain/evm/evmInterface.js";
import { projectInputIssues } from "../../domain/inputIssueProjection.js";
import { err, ok, type Result } from "../../domain/result.js";
const OPERATION = "inspect_evm_interface";
const diagnosticsSchema = z.object({
diagnostics: evmInterfaceSchema.shape.diagnostics,
});
/** Shared carrier validation and typed inline Evidence for CLI/MCP. */
export class EvmInterfaceService {
constructor(readonly provider: EvmInterfacePort) {}
/** Preserve selected byte identity while clearly labeling recovered ABI candidates as inferences. */
async inspect(
rawInput: unknown,
options?: ExecutionOptions,
): Promise<Result<Evidence, AnalysisError>> {
if (options?.signal?.aborted)
return err(new AnalysisCancelledError(OPERATION));
const input = inspectEvmInterfaceInputSchema.safeParse(rawInput);
if (!input.success)
return err(
new AnalysisInputError(
OPERATION,
{ cause: input.error },
projectInputIssues(input.error.issues, rawInput),
),
);
if (!isAbsolute(input.data.path))
return err(
new AnalysisInputError(OPERATION, undefined, [
{
path: ["path"],
reason: "invalid_format",
message: "Expected an absolute filesystem path on this host.",
},
]),
);
const inspected = await this.provider.inspect(input.data, options);
if (!inspected.ok) return inspected;
const diagnostics = diagnosticsSchema.safeParse(inspected.value.result);
const outputOptions = diagnostics.success
? { capturedOutput: diagnostics.data.diagnostics }
: undefined;
if (options?.signal?.aborted)
return err(new AnalysisCancelledError(OPERATION, outputOptions));
const execution = inspected.value;
const report = evmInterfaceSchema.safeParse(execution.result);
if (
!report.success ||
report.data.artifact.path !== input.data.path ||
report.data.artifact.encoding !== input.data.encoding ||
execution.subject?.path !== input.data.path ||
execution.subject.sha256 !== report.data.artifact.sha256
)
return err(
new AnalysisOutputError(
OPERATION,
"Interface adapter returned malformed data or changed the selected carrier identity/encoding.",
outputOptions,
),
);
return ok(
createEvidence(execution.subject, execution.provider, {
operation: OPERATION,
parameters: input.data,
result: report.data,
...(execution.rawResult === null
? {}
: { rawResult: execution.rawResult }),
confidence: "inferred",
locations: execution.locations,
limitations: execution.limitations,
}),
);
}
}