Merge remote-tracking branch 'origin/main' into codex/audit-continuation-20261020-refresh20
This commit is contained in:
commit
0dbc046ca6
22 files changed
+1974
-93
No files matched your search
@@ -8,7 +8,7 @@ import {
|
||||
environmentManifestCaptureFixture,
|
||||
environmentStateCaptureFixture,
|
||||
} from "../../../tests/fixtures/analysisView.js";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";
|
||||
import { createEvidence, parseEvidence } from "../../domain/evidence.js";
|
||||
@@ -38,11 +38,8 @@ import {
|
||||
scenarioCaptureEvidence,
|
||||
scenarioCaptureFixture,
|
||||
} from "../../../tests/fixtures/browserScenarioCapture.js";
|
||||
import { readEvidenceFileSource } from "./evidenceFileSource.js";
|
||||
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
|
||||
|
||||
vi.mock("./evidenceFileSource.js", { spy: true });
|
||||
|
||||
it.each(["layout", "javascript"])(
|
||||
"carries the retained %s source snapshot into repeatable shared views",
|
||||
(kind) => {
|
||||
@@ -1077,7 +1074,7 @@ describe("inspectAnalysisViewWithFiles", () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe("inspectAnalysisViewWithFiles scenario parents and cancellation", () => {
|
||||
describe("inspectAnalysisViewWithFiles scenario parents", () => {
|
||||
const view = manifestView;
|
||||
|
||||
it("accepts from a file a scenario capture whose response bodies exceed the inline budget", async () => {
|
||||
@@ -1109,33 +1106,4 @@ describe("inspectAnalysisViewWithFiles scenario parents and cancellation", () =>
|
||||
parent_evidence_id: parent.evidence_id,
|
||||
});
|
||||
});
|
||||
|
||||
it("reports cancellation rather than the authentication failure of a file aborted while it is authenticated", async () => {
|
||||
const controller = new AbortController();
|
||||
const parent = analysisViewCaptureEvidence(
|
||||
environmentManifestCaptureFixture(),
|
||||
);
|
||||
const path = await writeEvidenceFile({
|
||||
...parent,
|
||||
evidence_id: `ev_${"0".repeat(64)}`,
|
||||
});
|
||||
const { readEvidenceFileSource: read } = await vi.importActual<
|
||||
typeof import("./evidenceFileSource.js")
|
||||
>("./evidenceFileSource.js");
|
||||
// The abort arrives once the read has finished, while the stale ID is being authenticated.
|
||||
vi.mocked(readEvidenceFileSource).mockImplementationOnce(
|
||||
async (...args) => {
|
||||
const loaded = await read(...args);
|
||||
controller.abort();
|
||||
return loaded;
|
||||
},
|
||||
);
|
||||
expect(
|
||||
await inspectAnalysisViewWithFiles(
|
||||
{ source: { kind: "evidence-file", path }, view },
|
||||
undefined,
|
||||
{ signal: controller.signal },
|
||||
),
|
||||
).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });
|
||||
});
|
||||
});
|
||||
@@ -12,6 +12,8 @@ import {
|
||||
AnalysisCapabilityUnavailableError,
|
||||
AnalysisInputError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import type { Evidence } from "../../domain/evidence.js";
|
||||
import { ok } from "../../domain/result.js";
|
||||
|
||||
const createSession = () => ({
|
||||
sessionId: "00000000-0000-4000-8000-000000000001",
|
||||
@@ -65,6 +67,109 @@ const createProvider = (
|
||||
...overrides,
|
||||
});
|
||||
|
||||
it("keeps default Frida status identity and messages and refreshes every summary", () => {
|
||||
let reads = 0;
|
||||
const provider = createProvider({
|
||||
status() {
|
||||
reads++;
|
||||
return {
|
||||
...createSession(),
|
||||
state: reads === 1 ? "paused" : "detached",
|
||||
targetResumeObserved: false,
|
||||
scripts: [],
|
||||
messages: [{ observed: reads }],
|
||||
messagesTruncated: reads > 1,
|
||||
};
|
||||
},
|
||||
});
|
||||
const service = new FridaInstrumentationService(provider);
|
||||
const records = new Map<string, Evidence>();
|
||||
const retention = {
|
||||
evidenceById: (id: string) => records.get(id),
|
||||
recordEvidence(evidence: Evidence) {
|
||||
records.set(evidence.evidence_id, evidence);
|
||||
return ok("added" as const);
|
||||
},
|
||||
};
|
||||
const input = { session_id: createSession().sessionId };
|
||||
const complete = service.inspectStatus(input);
|
||||
if (!complete.ok) throw complete.error;
|
||||
expect(complete.value.normalized_result).toMatchObject({
|
||||
state: "paused",
|
||||
messages: [{ observed: 1 }],
|
||||
messages_truncated: false,
|
||||
});
|
||||
const summary = service.inspectStatus(
|
||||
{ ...input, detail: "summary" },
|
||||
retention,
|
||||
);
|
||||
if (!summary.ok) throw summary.error;
|
||||
expect(summary.value.normalized_result).toMatchObject({
|
||||
parent_operation: "frida_session_status",
|
||||
artifact: null,
|
||||
source_provider: complete.value.provider,
|
||||
source_parameters: input,
|
||||
summary: {
|
||||
state: "detached",
|
||||
messages_retained: 1,
|
||||
messages_truncated: true,
|
||||
},
|
||||
});
|
||||
expect(JSON.stringify(summary.value)).not.toContain('"messages":');
|
||||
expect(reads).toBe(2);
|
||||
const parent = [...records.values()][0];
|
||||
expect(parent?.normalized_result).toMatchObject({
|
||||
messages: [{ observed: 2 }],
|
||||
});
|
||||
expect(parent?.authority).toBe("external-service");
|
||||
expect(parent?.environment).toBeNull();
|
||||
expect(parent?.raw_result).toBeNull();
|
||||
});
|
||||
|
||||
it.each([
|
||||
undefined,
|
||||
{ recordEvidence: undefined, evidenceById: () => undefined },
|
||||
{ recordEvidence: () => ok("added" as const), evidenceById: undefined },
|
||||
])(
|
||||
"rejects missing Frida summary retention before reading live state: %j",
|
||||
(retention) => {
|
||||
let reads = 0;
|
||||
const service = new FridaInstrumentationService(
|
||||
createProvider({
|
||||
status() {
|
||||
reads++;
|
||||
return undefined;
|
||||
},
|
||||
}),
|
||||
);
|
||||
const result = service.inspectStatus(
|
||||
{ session_id: createSession().sessionId, detail: "summary" },
|
||||
retention,
|
||||
);
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok)
|
||||
expect(result.error._tag).toBe("AnalysisCapabilityUnavailableError");
|
||||
expect(reads).toBe(0);
|
||||
},
|
||||
);
|
||||
|
||||
it("rejects malformed Frida status selections and preserves unknown-session errors", () => {
|
||||
const service = new FridaInstrumentationService(createProvider());
|
||||
for (const input of [
|
||||
{ session_id: "invalid" },
|
||||
{ session_id: createSession().sessionId, detail: "messages" },
|
||||
]) {
|
||||
const result = service.inspectStatus(input);
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok) expect(result.error._tag).toBe("AnalysisInputError");
|
||||
}
|
||||
const unknown = service.inspectStatus({
|
||||
session_id: createSession().sessionId,
|
||||
});
|
||||
expect(unknown.ok).toBe(false);
|
||||
if (!unknown.ok) expect(unknown.error._tag).toBe("AnalysisInputError");
|
||||
});
|
||||
|
||||
it.each(["startSession", "instrument"] as const)(
|
||||
"does not start Frida when %s receives an already-cancelled signal",
|
||||
async (method) => {
|
||||
|
||||
@@ -14,6 +14,14 @@ import {
|
||||
AnalysisInputError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import { err, ok, type Result } from "../../domain/result.js";
|
||||
import { fridaSessionStatusInputSchema } from "../../domain/fridaSessionStatus.js";
|
||||
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
|
||||
import {
|
||||
requireAnalysisViewRetention,
|
||||
summarizeRetainedAnalysis,
|
||||
type AnalysisViewRetention,
|
||||
} from "../analysisView/AnalysisViewService.js";
|
||||
import { unknownFridaSession } from "./fridaInputErrors.js";
|
||||
import { FridaScriptLoadCancelledError } from "./FridaInstrumentationPort.js";
|
||||
import type {
|
||||
FridaDeviceSelector,
|
||||
@@ -237,13 +245,45 @@ export class FridaInstrumentationService {
|
||||
return this.#provider.status(sessionId);
|
||||
}
|
||||
|
||||
statusEvidence(sessionId: string): Evidence | undefined {
|
||||
const status = this.#provider.status(sessionId);
|
||||
return status === undefined
|
||||
? undefined
|
||||
: fridaEvidence("frida_session_status", sessionStatusOutput(status), {
|
||||
session_id: sessionId,
|
||||
});
|
||||
inspectStatus(
|
||||
rawInput: unknown,
|
||||
retention: AnalysisViewRetention = {
|
||||
recordEvidence: undefined,
|
||||
evidenceById: undefined,
|
||||
},
|
||||
): Result<Evidence, AnalysisError> {
|
||||
const input = fridaSessionStatusInputSchema.safeParse(rawInput);
|
||||
if (!input.success)
|
||||
return err(
|
||||
analysisInputErrorFromIssues(
|
||||
"frida_session_status",
|
||||
input.error.issues,
|
||||
rawInput,
|
||||
{ cause: input.error },
|
||||
),
|
||||
);
|
||||
if (input.data.detail === "summary") {
|
||||
const ready = requireAnalysisViewRetention(
|
||||
"frida_session_status",
|
||||
retention,
|
||||
);
|
||||
if (!ready.ok) return ready;
|
||||
}
|
||||
const status = this.#provider.status(input.data.session_id);
|
||||
if (status === undefined)
|
||||
return err(
|
||||
unknownFridaSession("frida_session_status", input.data.session_id),
|
||||
);
|
||||
const evidence = fridaEvidence(
|
||||
"frida_session_status",
|
||||
sessionStatusOutput(status),
|
||||
{
|
||||
session_id: input.data.session_id,
|
||||
},
|
||||
);
|
||||
return input.data.detail === "summary"
|
||||
? summarizeRetainedAnalysis(evidence, retention)
|
||||
: ok(evidence);
|
||||
}
|
||||
|
||||
async instrument(
|
||||
|
||||
@@ -17,7 +17,7 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
|
||||
...toolContractMetadata("inspect_analysis_view"),
|
||||
kind: "application",
|
||||
description:
|
||||
'Inspect selected views of completed GDB/objdump command observations, Go build metadata, binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_macho, decode_interface_builder, inspect_evm_interface, inspect_managed_artifact, inspect_managed_members, inspect_android_package, inspect_dart_aot, inspect_il2cpp_metadata, inspect_model_artifact or inspect_web_network_capture Evidence without repeating analysis. Command summary views preserve ordered GDB records or opaque objdump stdout/stderr once, source parameters, completion facts and parent identity. They do not establish current target state. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Go metadata uses kind go, collection dependencies/settings, exact paths/keys or indices, fields and pagination. Row index refers to the original collection; empty selections return no rows, and dependency coverage remains unknown. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. The environment-manifest view projects the same HAR requests on the primary origin (most JSON-like records) into a replayable tool surface: view {kind: "environment-manifest", template_rules: ["after-uid-literal", "opaque-token", "sibling-variance"], include_query_parameter_names: true}. Each tool has a deterministic name, a path template and parameters from the four format rules plus the selected opt-in rules, observed query parameter names, a value-free body shape for POST/PUT/PATCH, status and content-type sets and record ordinals; records are pointers into the parent, excluded groups carry a reason and three fixed unknowns are always stated. Templates, parameters and names are inferences; the view copies no header, cookie or body values and refuses parents inspected with sensitive values. A capture_browser_scenario parent that selected response bodies or header values projects the same way, one record per network transaction in request order; it relies on capture-time redaction of declared secrets instead of that refusal, and a transaction whose URL was redacted is left unrepresented. The environment-state view extracts, from the same parents, the initial state the recorded reads observed: view {kind: "environment-state", template_rules: [...]} with the rules of the manifest it accompanies. It reads response bodies recorded before the first related write and reports entity types with an identity field (proved by a path parameter or inferred from a field name), entities in collection order with per-view values where views differ, documents for non-parameterized non-entity paths written by POST/PUT/PATCH (item-shaped and delete-only paths stay recorded), and a render plan per read tool: item and list views reproduce their latest recordings from the state, and every other read tool is a recorded view with a reason. Types and identity are inferences; values are recorded data, so it refuses parents inspected with sensitive values, and a scenario parent must have selected response bodies; its values keep the capture redaction markers, and a write whose URL it redacted ends the state of every type. For a retained record use source: {kind: "retained-evidence", evidence_id: "<parent_evidence_id>"}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: <complete Evidence>}. A completed Evidence JSON file on this host uses {kind: "evidence-file", path: "<absolute path>"}: REA reads and authenticates it, then projects it like retained Evidence, so a large capture is bounded by the file reader rather than by inline-input accounting. For layout, JavaScript, inventory, WASM, Mach-O, Interface BLine truncated
|
||||
'Inspect selected views of completed Frida session status, GDB/objdump command observations, Go build metadata, binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_macho, decode_interface_builder, inspect_evm_interface, inspect_managed_artifact, inspect_managed_members, inspect_android_package, inspect_dart_aot, inspect_il2cpp_metadata, inspect_model_artifact or inspect_web_network_capture Evidence without repeating analysis. Command summary views preserve ordered GDB records or opaque objdump stdout/stderr once, source parameters, completion facts and parent identity. They do not establish current target state. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Go metadata uses kind go, collection dependencies/settings, exact paths/keys or indices, fields and pagination. Row index refers to the original collection; empty selections return no rows, and dependency coverage remains unknown. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. The environment-manifest view projects the same HAR requests on the primary origin (most JSON-like records) into a replayable tool surface: view {kind: "environment-manifest", template_rules: ["after-uid-literal", "opaque-token", "sibling-variance"], include_query_parameter_names: true}. Each tool has a deterministic name, a path template and parameters from the four format rules plus the selected opt-in rules, observed query parameter names, a value-free body shape for POST/PUT/PATCH, status and content-type sets and record ordinals; records are pointers into the parent, excluded groups carry a reason and three fixed unknowns are always stated. Templates, parameters and names are inferences; the view copies no header, cookie or body values and refuses parents inspected with sensitive values. A capture_browser_scenario parent that selected response bodies or header values projects the same way, one record per network transaction in request order; it relies on capture-time redaction of declared secrets instead of that refusal, and a transaction whose URL was redacted is left unrepresented. The environment-state view extracts, from the same parents, the initial state the recorded reads observed: view {kind: "environment-state", template_rules: [...]} with the rules of the manifest it accompanies. It reads response bodies recorded before the first related write and reports entity types with an identity field (proved by a path parameter or inferred from a field name), entities in collection order with per-view values where views differ, documents for non-parameterized non-entity paths written by POST/PUT/PATCH (item-shaped and delete-only paths stay recorded), and a render plan per read tool: item and list views reproduce their latest recordings from the state, and every other read tool is a recorded view with a reason. Types and identity are inferences; values are recorded data, so it refuses parents inspected with sensitive values, and a scenario parent must have selected response bodies; its values keep the capture redaction markers, and a write whose URL it redacted ends the state of every type. For a retained record use source: {kind: "retained-evidence", evidence_id: "<parent_evidence_id>"}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: <complete Evidence>}. A completed Evidence JSON file on this host uses {kind: "evidence-file", path: "<absolute path>"}: REA reads and authenticates it, then projects it like retained Evidence, so a large capture is bounded by the file reader rather than by inline-input accounting. For layout, JavaScript, inventory, WASLine truncated
|
||||
inputSchema: inspectAnalysisViewInputSchema,
|
||||
outputSchema: evidenceResultOf(analysisViewResultSchema),
|
||||
examples: [
|
||||
|
||||
@@ -3,8 +3,15 @@ import { z } from "zod";
|
||||
import { localPathStringSchema } from "../domain/localPath.js";
|
||||
import type { ToolContract } from "./toolContractTypes.js";
|
||||
import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
|
||||
import { analysisDetailOutputSchemaOf } from "./analysisDetail.js";
|
||||
import { toolContractMetadata } from "./toolEffects.js";
|
||||
import { isValidFridaRemoteAddress } from "./fridaRemoteAddress.js";
|
||||
import {
|
||||
fridaSessionObservationSchema,
|
||||
fridaSessionStatusInputSchema,
|
||||
fridaSessionStatusSchema,
|
||||
} from "../domain/fridaSessionStatus.js";
|
||||
import { fridaSessionStatusSummaryViewResultSchema } from "../domain/analysisView/analysisView.js";
|
||||
|
||||
export const FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION =
|
||||
"Remote keepalive interval in seconds";
|
||||
@@ -45,15 +52,6 @@ const exclusiveDeviceSelector = <Schema extends z.ZodTypeAny>(schema: Schema) =>
|
||||
|
||||
const sessionId = z.string().uuid();
|
||||
|
||||
const sessionOutput = z.strictObject({
|
||||
session_id: sessionId,
|
||||
device_id: z.string(),
|
||||
target: z.string(),
|
||||
pid: z.number().int().nonnegative(),
|
||||
mode: z.enum(["attach", "spawn"]),
|
||||
state: z.enum(["paused", "running", "detached"]),
|
||||
});
|
||||
|
||||
const scriptOutput = z.strictObject({
|
||||
script_id: z.string().uuid(),
|
||||
source_kind: z.enum(["inline", "file"]),
|
||||
@@ -142,7 +140,7 @@ export const FRIDA_TOOL_CONTRACTS = [
|
||||
!(value.device_id !== undefined && value.remote !== undefined),
|
||||
"Select one device; attach requires pid; spawn requires program and rejects pid",
|
||||
),
|
||||
outputSchema: sessionOutput,
|
||||
outputSchema: fridaSessionObservationSchema,
|
||||
examples: [
|
||||
{
|
||||
title: "Attach to a process",
|
||||
@@ -226,22 +224,11 @@ export const FRIDA_TOOL_CONTRACTS = [
|
||||
...toolContractMetadata("frida_session_status"),
|
||||
kind: "native-provider",
|
||||
description:
|
||||
"Return observed Frida session state and queued script messages. Message history is bounded by the provider capture budget and reports truncation.",
|
||||
inputSchema: z.strictObject({ session_id: sessionId }),
|
||||
outputSchema: evidenceResultOf(
|
||||
z.strictObject({
|
||||
session_id: sessionId,
|
||||
device_id: z.string(),
|
||||
state: z.enum(["paused", "running", "detached"]),
|
||||
target: z.string(),
|
||||
pid: z.number().int().nonnegative(),
|
||||
mode: z.enum(["attach", "spawn"]),
|
||||
scripts: z.array(
|
||||
z.strictObject({ script_id: z.string().uuid(), name: z.string() }),
|
||||
),
|
||||
messages: z.array(z.unknown()),
|
||||
messages_truncated: z.boolean(),
|
||||
}),
|
||||
"Read observed Frida session state on each call. Default detail=complete returns queued script messages and capture truncation. detail=summary retains the complete observation in this session and returns identity, state, scripts, retained message count and truncation without payloads. Export the complete parent with export_evidence_bundle; retained summaries are historical and never refresh live state.",
|
||||
inputSchema: fridaSessionStatusInputSchema,
|
||||
outputSchema: analysisDetailOutputSchemaOf(
|
||||
fridaSessionStatusSchema,
|
||||
fridaSessionStatusSummaryViewResultSchema,
|
||||
),
|
||||
examples: [
|
||||
{
|
||||
@@ -302,13 +289,7 @@ export const FRIDA_TOOL_CONTRACTS = [
|
||||
"Select one device and provide fields matching the mode and source_kind",
|
||||
),
|
||||
outputSchema: evidenceResultOf(
|
||||
z.strictObject({
|
||||
...sessionOutput.shape,
|
||||
scripts: z.array(
|
||||
z.strictObject({ script_id: sessionId, name: z.string() }),
|
||||
),
|
||||
messages: z.array(z.unknown()),
|
||||
messages_truncated: z.boolean(),
|
||||
fridaSessionStatusSchema.extend({
|
||||
source_kind: z.enum(["inline", "file"]),
|
||||
source_path: z.string().nullable(),
|
||||
source_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
|
||||
@@ -10,6 +10,11 @@ import {
|
||||
gdbCommandSummarySchema,
|
||||
projectCommandObservationView,
|
||||
} from "./commandObservationView.js";
|
||||
import {
|
||||
fridaSessionStatusSummarySchema,
|
||||
fridaSessionStatusViewContext,
|
||||
projectFridaSessionStatusView,
|
||||
} from "./fridaSessionStatusView.js";
|
||||
import { commandObservationSchema } from "../commandObservation.js";
|
||||
import {
|
||||
goBinarySummarySchema,
|
||||
@@ -385,6 +390,7 @@ const viewResultBase = {
|
||||
"inspect_binary_layout",
|
||||
"inspect_go_binary",
|
||||
"gdb_console",
|
||||
"frida_session_status",
|
||||
"inspect_with_objdump",
|
||||
"inspect_desktop_application",
|
||||
"analyze_javascript_application",
|
||||
@@ -437,6 +443,14 @@ export const objdumpSummaryViewResultSchema = z.strictObject({
|
||||
summary: commandObservationSchema,
|
||||
});
|
||||
|
||||
export const fridaSessionStatusSummaryViewResultSchema = z.strictObject({
|
||||
...summaryViewResultBase,
|
||||
...fridaSessionStatusViewContext,
|
||||
parent_operation: z.literal("frida_session_status"),
|
||||
artifact: artifactSchema.nullable(),
|
||||
summary: fridaSessionStatusSummarySchema,
|
||||
});
|
||||
|
||||
/** Opt-in Go delivery retains original bytes and exposes build identity/counts. */
|
||||
export const goBinarySummaryViewResultSchema = z.strictObject({
|
||||
...summaryViewResultBase,
|
||||
@@ -645,6 +659,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
|
||||
z.discriminatedUnion("parent_operation", [
|
||||
gdbCommandSummaryViewResultSchema,
|
||||
objdumpSummaryViewResultSchema,
|
||||
fridaSessionStatusSummaryViewResultSchema,
|
||||
goBinarySummaryViewResultSchema,
|
||||
binaryLayoutSummaryViewResultSchema,
|
||||
desktopApplicationSummaryViewResultSchema,
|
||||
@@ -930,6 +945,7 @@ const parentArtifactPath = (parent: AnalysisViewParent): string => {
|
||||
|
||||
/** Named source owners for views that need no extra decoder or accumulator. */
|
||||
const retainedViewProjectors = new Map<string, typeof projectWasmArtifactView>([
|
||||
["frida_session_status", projectFridaSessionStatusView],
|
||||
["gdb_console", projectCommandObservationView],
|
||||
["inspect_with_objdump", projectCommandObservationView],
|
||||
["inspect_go_binary", projectGoBinaryView],
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
import { z } from "zod";
|
||||
import type { AnalysisError } from "../analysisErrorBase.js";
|
||||
import { providerSchema } from "../evidence.js";
|
||||
import { fridaSessionStatusSchema } from "../fridaSessionStatus.js";
|
||||
import { err, ok, type Result } from "../result.js";
|
||||
import type {
|
||||
AnalysisViewParent,
|
||||
AnalysisViewRequest,
|
||||
UnsignedAnalysisView,
|
||||
} from "./analysisView.js";
|
||||
import {
|
||||
boundedViewMessages,
|
||||
completeWithinViewCoverage,
|
||||
} from "./analysisViewCoverage.js";
|
||||
import { analysisViewInputError } from "./analysisViewErrors.js";
|
||||
import { parseAnalysisViewResult } from "./analysisViewParent.js";
|
||||
|
||||
export const fridaSessionStatusSummarySchema = fridaSessionStatusSchema
|
||||
.omit({ messages: true })
|
||||
.extend({ messages_retained: z.number().int().nonnegative() });
|
||||
|
||||
export const fridaSessionStatusViewContext = {
|
||||
source_provider: providerSchema.nullable(),
|
||||
source_parameters: z.strictObject({ session_id: z.string().uuid() }),
|
||||
};
|
||||
|
||||
/** Summarize captured facts without interpreting caller-authored message payloads. */
|
||||
export const projectFridaSessionStatusView = (
|
||||
parent: AnalysisViewParent,
|
||||
view: AnalysisViewRequest,
|
||||
): Result<UnsignedAnalysisView, AnalysisError> => {
|
||||
if (view.kind !== "summary")
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["view"],
|
||||
reason: "invalid_value",
|
||||
message: "Frida session status supports summary views.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
const report = parseAnalysisViewResult(fridaSessionStatusSchema, parent);
|
||||
if (!report.ok) return report;
|
||||
const parameters = fridaSessionStatusViewContext.source_parameters.safeParse(
|
||||
parent.parameters,
|
||||
);
|
||||
if (
|
||||
!parameters.success ||
|
||||
parameters.data.session_id !== report.value.session_id
|
||||
)
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["source", "parameters", "session_id"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
"The Frida status must identify the session selected by its source parameters.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
const { messages, ...status } = report.value;
|
||||
return ok({
|
||||
kind: "summary",
|
||||
view,
|
||||
parent_evidence_id: parent.evidenceId,
|
||||
parent_digest: parent.evidenceId.slice(3),
|
||||
parent_operation: "frida_session_status",
|
||||
artifact: null,
|
||||
source_provider: parent.provider ?? null,
|
||||
source_parameters: parameters.data,
|
||||
summary: { ...status, messages_retained: messages.length },
|
||||
coverage: completeWithinViewCoverage(1, 1),
|
||||
limitations: boundedViewMessages(
|
||||
[
|
||||
...parent.limitations,
|
||||
`Message payloads remain in complete parent Evidence ${parent.evidenceId}; export_evidence_bundle preserves them.`,
|
||||
],
|
||||
parent.evidenceId,
|
||||
"limitations",
|
||||
),
|
||||
unknowns: [
|
||||
"This is a captured session observation; querying retained Evidence does not refresh live state or establish target process identity after exit or reuse.",
|
||||
"messages_retained counts queued messages, not all target events. messages_truncated preserves the provider's capture limitation; payload meanings and global event coverage are unknown.",
|
||||
],
|
||||
});
|
||||
};
|
||||
@@ -0,0 +1,27 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** Delivery selection is separate from the provider's live session lookup. */
|
||||
export const fridaSessionStatusInputSchema = z.strictObject({
|
||||
session_id: z.string().uuid(),
|
||||
detail: z.enum(["complete", "summary"]).optional(),
|
||||
});
|
||||
|
||||
/** Session identity and state shared by start, status and one-shot observations. */
|
||||
export const fridaSessionObservationSchema = z.strictObject({
|
||||
session_id: z.string().uuid(),
|
||||
device_id: z.string(),
|
||||
state: z.enum(["paused", "running", "detached"]),
|
||||
target: z.string(),
|
||||
pid: z.number().int().nonnegative(),
|
||||
mode: z.enum(["attach", "spawn"]),
|
||||
});
|
||||
|
||||
/** Canonical captured facts; message payload meanings remain caller-defined. */
|
||||
export const fridaSessionStatusSchema = fridaSessionObservationSchema.extend({
|
||||
scripts: z.array(
|
||||
z.strictObject({ script_id: z.string().uuid(), name: z.string() }),
|
||||
),
|
||||
// Evidence validates JSON payloads; status views validate only this envelope.
|
||||
messages: z.array(z.unknown()),
|
||||
messages_truncated: z.boolean(),
|
||||
});
|
||||
@@ -535,6 +535,7 @@ export const createServer = (
|
||||
session === undefined
|
||||
? undefined
|
||||
: (evidence) => session.recordEvidence(evidence),
|
||||
evidenceById,
|
||||
);
|
||||
registerCutterTools(
|
||||
server,
|
||||
|
||||
@@ -2,6 +2,7 @@ import type { McpServer, ServerContext } from "@modelcontextprotocol/server";
|
||||
import type { Logger } from "pino";
|
||||
|
||||
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
|
||||
import type { EvidenceLookup } from "../application/EvidenceInputResolver.js";
|
||||
import { FridaInstrumentationService } from "../application/frida/FridaInstrumentationService.js";
|
||||
import type { FridaInstrumentationPort } from "../application/frida/FridaInstrumentationPort.js";
|
||||
import type { FridaRemoteConnection } from "../application/frida/FridaInstrumentationPort.js";
|
||||
@@ -14,7 +15,6 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { logToolExecution } from "./toolLogging.js";
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
import type { ToolResultDelivery } from "./toolResult.js";
|
||||
import { unknownFridaSession } from "../application/frida/fridaInputErrors.js";
|
||||
|
||||
/** Register Frida device discovery and persistent instrumentation operations. */
|
||||
export const registerFridaTools = (
|
||||
@@ -23,6 +23,7 @@ export const registerFridaTools = (
|
||||
logger: Logger,
|
||||
delivery: ToolResultDelivery,
|
||||
recordEvidence?: EvidenceWriter["recordEvidence"],
|
||||
evidenceById?: EvidenceLookup,
|
||||
): void => {
|
||||
const service = new FridaInstrumentationService(provider);
|
||||
const listDevices = toolContract("list_frida_devices");
|
||||
@@ -193,19 +194,15 @@ export const registerFridaTools = (
|
||||
status.name,
|
||||
toolRegistrationOptions(status),
|
||||
async (input) => {
|
||||
const evidence = service.statusEvidence(input.session_id);
|
||||
if (evidence === undefined)
|
||||
return delivery.toCallToolResult(
|
||||
{
|
||||
ok: false as const,
|
||||
error: unknownFridaSession(status.name, input.session_id),
|
||||
},
|
||||
status,
|
||||
);
|
||||
const result = service.inspectStatus(input, {
|
||||
recordEvidence,
|
||||
evidenceById,
|
||||
});
|
||||
if (!result.ok) return delivery.toCallToolResult(result, status);
|
||||
return delivery.toEvidenceToolResult(
|
||||
evidence,
|
||||
result.value,
|
||||
status,
|
||||
recordEvidence?.(evidence),
|
||||
recordEvidence?.(result.value),
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
Reference in new issue
Block a user