rea-agents 4.0.0 → 4.1.0

package/dist/firmware/FirmwarePublication.js

@@ -0,0 +1,84 @@
+import { createReadStream } from "node:fs";
+import { join } from "node:path";
+import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { firmwareResultSchemas } from "../domain/firmwareAnalysis.js";
+import { hashFirmwareFile } from "./FirmwareFiles.js";
+/** Publish verified regular files, preserving links as metadata and rolling back failed writes. */
+export const publishFirmwareExtraction = async (context) => {
+    let tree;
+    try {
+        const materialized = new Set(context.entries
+            .filter((entry) => entry.kind === "file")
+            .map((entry) => `$output/${entry.relativePath}`));
+        for (const path of context.normalized.files.keys()) {
+            if (path !== "$input" && !materialized.has(path))
+                throw new AnalysisOutputError("extract_firmware", `Reported regular file is absent from materialized output: ${path}`);
+        }
+        const files = [];
+        const unpublished = [];
+        tree = await SafeOutputTree.create(context.outputDirectory);
+        for (const entry of context.entries) {
+            if (entry.kind !== "file") {
+                unpublished.push({
+                    relative_path: entry.relativePath,
+                    kind: entry.kind,
+                    link_target: entry.linkTarget,
+                });
+                continue;
+            }
+            const logicalPath = `$output/${entry.relativePath}`;
+            const reported = context.normalized.files.get(logicalPath);
+            const sha256 = await hashFirmwareFile(entry.path, context.signal);
+            if ((reported?.sha256 !== null &&
+                reported?.sha256 !== undefined &&
+                reported.sha256 !== sha256) ||
+                (context.normalized.sizes.has(logicalPath) &&
+                    context.normalized.sizes.get(logicalPath) !== entry.size))
+                throw new AnalysisOutputError("extract_firmware", `Extracted bytes disagree with provider report: ${entry.relativePath}`);
+            await tree.write(entry.relativePath, createReadStream(entry.path), sha256, context.signal);
+            files.push({
+                relative_path: entry.relativePath,
+                path: join(tree.outputRoot, entry.relativePath),
+                size: entry.size,
+                sha256,
+                reported_sha256: reported?.sha256 ?? null,
+                mime_type: reported?.mimeType ?? null,
+                analysis_depth: reported?.depth ?? null,
+                runtime_address: null,
+                original_file_range: null,
+            });
+        }
+        const result = firmwareResultSchemas.extract_firmware.parse({
+            engine: context.engine,
+            selection: context.selection,
+            output_directory: tree.outputRoot,
+            coverage: unpublished.length > 0 ? "partial" : context.normalized.coverage,
+            files,
+            unpublished_entries: unpublished,
+            chunks: context.normalized.chunks,
+            derivations: context.normalized.derivations,
+            depth_limited_paths: context.normalized.depth_limited_paths,
+            diagnostics: context.normalized.diagnostics,
+            published_bytes: files.reduce((sum, file) => sum + file.size, 0),
+        });
+        context.signal.throwIfAborted();
+        await tree.commit();
+        return result;
+    }
+    catch (cause) {
+        try {
+            await tree?.rollback();
+        }
+        catch (cleanupCause) {
+            throw new ProviderCleanupError("unblob", [context.outputDirectory], {
+                reason: cleanupCause instanceof Error
+                    ? cleanupCause.message
+                    : String(cleanupCause),
+                previous_error: cause instanceof Error ? cause.message : String(cause),
+            }, { cause: cleanupCause });
+        }
+        throw cause;
+    }
+};

package/dist/firmware/FirmwareRelease.js

@@ -0,0 +1,32 @@
+/** Audited upstream sources; installed tool bytes are fingerprinted separately. */
+export const FIRMWARE_RELEASES = {
+    binwalk: {
+        version: "3.1.0",
+        revision: "4fdab3d464d97b68e0af9088df3f9e2e1545b21c",
+        repository: "https://github.com/ReFirmLabs/binwalk",
+    },
+    unblob: {
+        version: "26.6.4",
+        revision: "1fcc7a0a584a70a96c31f5a276c20944d199a089",
+        repository: "https://github.com/onekey-sec/unblob",
+    },
+};
+/** Catalog identities; Evidence uses the version observed from the executed tool. */
+export const BINWALK_PROVIDER_IDENTITY = {
+    id: "binwalk",
+    name: "Binwalk",
+    version: FIRMWARE_RELEASES.binwalk.version,
+};
+/** Catalog identity for explicit firmware extraction. */
+export const UNBLOB_PROVIDER_IDENTITY = {
+    id: "unblob",
+    name: "Unblob",
+    version: FIRMWARE_RELEASES.unblob.version,
+};
+/** Resource policy for this Linux integration, not a claim of aggregate containment. */
+export const FIRMWARE_LIMITS = {
+    inputBytes: 128 * 1024 * 1024,
+    reportBytes: 8 * 1024 * 1024,
+    addressSpaceBytes: 1024 * 1024 * 1024,
+    timeoutMs: 120_000,
+};

package/dist/firmware/FirmwareReports.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { digestSchema } from "../domain/digests.js";
+import { firmwareLogicalPath } from "./FirmwareFiles.js";
+const integer = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const signature = z.object({
+    id: z.string().min(1),
+    offset: integer,
+    size: integer,
+    name: z.string(),
+    description: z.string(),
+    confidence: z.number().int().min(0).max(255),
+    always_display: z.boolean(),
+    extraction_declined: z.boolean(),
+});
+const scan = z.array(z.object({
+    Analysis: z.object({
+        file_path: z.string(),
+        file_map: z.array(signature),
+        extractions: z.record(z.string(), jsonValueSchema),
+    }),
+}));
+const report = z.object({ __typename__: z.string() }).catchall(jsonValueSchema);
+const task = z.object({
+    path: z.string(),
+    depth: integer,
+    blob_id: z.string(),
+    is_multi_file: z.boolean(),
+});
+const extraction = z.array(z.object({ task, reports: z.array(report), subtasks: z.array(task) }));
+const stat = z.object({
+    __typename__: z.literal("StatReport"),
+    path: z.string(),
+    size: integer,
+    is_dir: z.boolean(),
+    is_file: z.boolean(),
+    is_link: z.boolean(),
+    link_target: z.string().nullable(),
+});
+const hashes = z.object({ sha256: digestSchema });
+const region = z.object({
+    id: z.string(),
+    start_offset: integer,
+    end_offset: integer,
+    size: integer,
+});
+const known = new Set([
+    "StatReport",
+    "HashReport",
+    "FileMagicReport",
+    "RandomnessReport",
+    "ChunkReport",
+    "UnknownChunkReport",
+    "CarveDirectoryReport",
+    "MultiFileReport",
+]);
+/** Interpret the pinned Binwalk report without inventing validated region lengths. */
+export const normalizeBinwalkReport = (raw, inputPath, size) => {
+    const records = scan.parse(raw);
+    const analysis = records[0]?.Analysis;
+    if (records.length !== 1 ||
+        analysis?.file_path !== inputPath ||
+        Object.keys(analysis.extractions).length !== 0)
+        throw new AnalysisOutputError("inspect_firmware_regions", "Expected one inspection-only report for the selected immutable input");
+    return analysis.file_map.map((hit) => {
+        if (hit.offset >= size || hit.size > size - hit.offset)
+            throw new AnalysisOutputError("inspect_firmware_regions", "Reported region lies outside the selected file");
+        return {
+            provider_id: hit.id,
+            offset: hit.offset,
+            reported_size: hit.size,
+            signature: hit.name,
+            description: hit.description,
+            reported_confidence: hit.confidence,
+            size_basis: "provider_reported_validation_unknown",
+        };
+    });
+};
+/** Normalize Unblob's unordered task graph, retaining unknown and failed analyses. */
+export const normalizeUnblobReport = (raw, context) => {
+    const records = extraction.parse(raw);
+    const logical = (path) => firmwareLogicalPath(path, context.inputPath, context.outputRoot);
+    const roots = records.filter(({ task: item }) => item.path === context.inputPath && item.depth === 0);
+    if (roots.length !== 1)
+        throw new AnalysisOutputError("extract_firmware", "Expected exactly one selected input task");
+    const rootHash = roots[0]?.reports.find((r) => r.__typename__ === "HashReport");
+    if (rootHash === undefined ||
+        hashes.parse(rootHash).sha256 !== context.sha256)
+        throw new AnalysisOutputError("extract_firmware", "Unblob input hash disagrees with selected snapshot");
+    const files = new Map();
+    const sizes = new Map();
+    const depths = [];
+    const diagnostics = [];
+    const chunks = [];
+    const seen = new Set();
+    for (const record of records) {
+        const path = logical(record.task.path);
+        if (seen.has(path))
+            throw new AnalysisOutputError("extract_firmware", `Duplicate analysis task: ${path}`);
+        seen.add(path);
+        if (record.task.depth >= context.maxDepth)
+            depths.push(path);
+        const metadata = record.reports.find((r) => r.__typename__ === "StatReport");
+        if (metadata === undefined)
+            throw new AnalysisOutputError("extract_firmware", `Missing StatReport: ${path}`);
+        const parsedStat = stat.parse(metadata);
+        if (parsedStat.path !== record.task.path)
+            throw new AnalysisOutputError("extract_firmware", `StatReport is bound to another task: ${path}`);
+        if (path === "$input" && parsedStat.size !== context.length)
+            throw new AnalysisOutputError("extract_firmware", "Unblob input size disagrees with selected snapshot");
+        if (path === "$input" &&
+            (!parsedStat.is_file || parsedStat.is_link || parsedStat.is_dir))
+            throw new AnalysisOutputError("extract_firmware", "Selected input was not reported as a regular file");
+        sizes.set(path, parsedStat.size);
+        const hash = record.reports.find((r) => r.__typename__ === "HashReport");
+        const magic = record.reports.find((r) => r.__typename__ === "FileMagicReport");
+        if (parsedStat.is_file && !parsedStat.is_link)
+            files.set(path, {
+                sha256: hash === undefined ? null : hashes.parse(hash).sha256,
+                mimeType: magic === undefined
+                    ? null
+                    : z.object({ mime_type: z.string() }).parse(magic).mime_type,
+                depth: record.task.depth,
+            });
+        for (const item of record.reports) {
+            if (!known.has(item.__typename__))
+                diagnostics.push(jsonValueSchema.parse({ input_path: path, report: item }));
+            if (item.__typename__ === "ChunkReport" ||
+                item.__typename__ === "UnknownChunkReport") {
+                const parsed = region.parse(item);
+                if (parsed.end_offset <= parsed.start_offset ||
+                    parsed.end_offset > parsedStat.size ||
+                    parsed.size !== parsed.end_offset - parsed.start_offset)
+                    throw new AnalysisOutputError("extract_firmware", `Invalid chunk bounds for ${path}`);
+                const detail = item.__typename__ === "ChunkReport"
+                    ? z
+                        .object({
+                        handler_name: z.string(),
+                        is_encrypted: z.boolean(),
+                        extraction_reports: z.array(jsonValueSchema),
+                    })
+                        .parse(item)
+                    : null;
+                if (detail !== null)
+                    for (const problem of detail.extraction_reports)
+                        diagnostics.push({ input_path: path, report: problem });
+                chunks.push({
+                    input_path: path,
+                    provider_id: parsed.id,
+                    range: { offset: parsed.start_offset, length: parsed.size },
+                    handler: detail?.handler_name ?? null,
+                    encrypted: detail?.is_encrypted ?? null,
+                    root_file_range: path === "$input"
+                        ? {
+                            offset: context.offset + parsed.start_offset,
+                            length: parsed.size,
+                        }
+                        : null,
+                });
+            }
+        }
+    }
+    const recordsByPath = new Map(records.map((record) => [record.task.path, record.task]));
+    const chunksByOrigin = new Map();
+    for (const item of chunks) {
+        const key = JSON.stringify([item.input_path, item.provider_id]);
+        if (chunksByOrigin.has(key))
+            throw new AnalysisOutputError("extract_firmware", `Duplicate chunk identity in ${item.input_path}`);
+        chunksByOrigin.set(key, item);
+    }
+    const derivations = records.flatMap((record) => record.subtasks.map((child) => {
+        const parentPath = logical(record.task.path);
+        const childPath = logical(child.path);
+        if (!seen.has(childPath))
+            throw new AnalysisOutputError("extract_firmware", `Missing child task: ${childPath}`);
+        const reportedChild = recordsByPath.get(child.path);
+        if (reportedChild?.depth !== child.depth ||
+            reportedChild.blob_id !== child.blob_id ||
+            reportedChild.is_multi_file !== child.is_multi_file)
+            throw new AnalysisOutputError("extract_firmware", `Child task identity disagrees with its analysis: ${childPath}`);
+        const origin = chunksByOrigin.get(JSON.stringify([parentPath, child.blob_id]));
+        return {
+            parent_path: parentPath,
+            child_path: childPath,
+            provider_blob_id: child.blob_id,
+            handler: origin?.handler ?? null,
+            parent_file_range: origin?.range ?? null,
+        };
+    }));
+    const reachable = new Set(["$input"]);
+    const pending = ["$input"];
+    const childrenByParent = new Map();
+    for (const edge of derivations) {
+        const children = childrenByParent.get(edge.parent_path) ?? [];
+        children.push(edge.child_path);
+        childrenByParent.set(edge.parent_path, children);
+    }
+    while (pending.length > 0) {
+        const parent = pending.pop();
+        for (const child of childrenByParent.get(parent ?? "") ?? []) {
+            if (reachable.has(child))
+                continue;
+            reachable.add(child);
+            pending.push(child);
+        }
+    }
+    if (reachable.size !== seen.size)
+        throw new AnalysisOutputError("extract_firmware", "Report contains tasks disconnected from the selected input");
+    return {
+        files,
+        sizes,
+        chunks,
+        derivations,
+        depth_limited_paths: depths.sort(),
+        diagnostics,
+        coverage: depths.length > 0 ||
+            diagnostics.length > 0 ||
+            chunks.some((c) => c.handler === null || c.encrypted === true)
+            ? "partial"
+            : "complete",
+    };
+};