@remnux/mcp-server 0.1.54 → 0.1.56

package/dist/analysis/behavior-prerequisites.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Static behavior-prerequisite analysis.
+ *
+ * Answers "can this binary even call the APIs that behavior X requires?" from
+ * the static import table. This is a deliberate GATE against the most common
+ * triage error — claiming a behavior on artifact evidence alone — by forcing an
+ * explicit "are the prerequisite APIs accessible?" check.
+ *
+ * Design constraints (from the project's design review):
+ *  - It reports a STATIC-capability assessment, never a behavioral verdict. The
+ *    field is `static_capability` (not `verdict`) and every value is suffixed
+ *    with the basis (`_statically`) so it cannot be misread as "the sample does
+ *    X". Static capability is necessary, not sufficient, for the behavior.
+ *  - It never emits a clean "incapable" on a packed/obscured binary — the
+ *    import table is unreliable there, so it returns `analysis_incomplete`
+ *    ("unpack first") rather than a false negative.
+ *  - When the required APIs are absent but GetProcAddress + a library loader are
+ *    present, it returns `possibly_via_dynamic_resolution` — it cannot prove
+ *    those resolvers are NOT used to reach the missing APIs without xref /
+ *    dynamic analysis, so it does not claim `incapable_statically`.
+ *  - The behavior→API table is generic malware-analysis knowledge, not tuned to
+ *    any specific sample.
+ */
+export type StaticCapability = "capable_statically" | "incapable_statically" | "possibly_via_dynamic_resolution" | "analysis_incomplete" | "not_applicable";
+export interface BehaviorDef {
+    /** Human-readable description of the behavior. */
+    description: string;
+    /** Required API base names (no ANSI/Unicode suffix). */
+    apis: string[];
+    /** How many of `apis` must be present to call the binary statically capable. */
+    minMatch: number;
+}
+/**
+ * Behavior → prerequisite APIs. Base names only (apiPresent handles A/W). The
+ * minMatch threshold tolerates that a behavior rarely needs its entire API set
+ * and that import names vary, while still requiring a meaningful signature.
+ */
+export declare const BEHAVIOR_PREREQUISITES: Record<string, BehaviorDef>;
+export interface PrerequisiteResult {
+    behavior: string;
+    description: string;
+    required_apis: string[];
+    apis_present: string[];
+    apis_missing: string[];
+    dynamic_resolution_present: boolean;
+    static_capability: StaticCapability;
+    rationale: string;
+    recommended_followup: string;
+}
+/** Context derived from the binary (packer detection, whether imports parsed). */
+export interface PrerequisiteContext {
+    /** A packer/protector was detected, or the import table is unreadable/empty. */
+    obscured: boolean;
+    /** readpe produced a usable import table. */
+    importsParsed: boolean;
+    /** Managed/.NET assembly — native imports don't reflect managed-code capability. */
+    managed?: boolean;
+}
+/** Detect the GetProcAddress + library-loader pair that enables runtime resolution. */
+export declare function hasDynamicResolution(functionSet: Set<string>): boolean;
+/**
+ * Classify one behavior against an import set + context. Pure and deterministic.
+ */
+export declare function classifyPrerequisite(behaviorKey: string, def: BehaviorDef, functionSet: Set<string>, ctx: PrerequisiteContext): PrerequisiteResult;
+//# sourceMappingURL=behavior-prerequisites.d.ts.map

package/dist/analysis/behavior-prerequisites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-prerequisites.d.ts","sourceRoot":"","sources":["../../src/analysis/behavior-prerequisites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,sBAAsB,GACtB,iCAAiC,GACjC,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAkE9D,CAAC;AAMF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0BAA0B,EAAE,OAAO,CAAC;IACpC,iBAAiB,EAAE,gBAAgB,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,aAAa,EAAE,OAAO,CAAC;IACvB,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAiBD,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAKtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,GAAG,EAAE,mBAAmB,GACvB,kBAAkB,CA8DpB"}

package/dist/analysis/behavior-prerequisites.js

@@ -0,0 +1,186 @@
+/**
+ * Static behavior-prerequisite analysis.
+ *
+ * Answers "can this binary even call the APIs that behavior X requires?" from
+ * the static import table. This is a deliberate GATE against the most common
+ * triage error — claiming a behavior on artifact evidence alone — by forcing an
+ * explicit "are the prerequisite APIs accessible?" check.
+ *
+ * Design constraints (from the project's design review):
+ *  - It reports a STATIC-capability assessment, never a behavioral verdict. The
+ *    field is `static_capability` (not `verdict`) and every value is suffixed
+ *    with the basis (`_statically`) so it cannot be misread as "the sample does
+ *    X". Static capability is necessary, not sufficient, for the behavior.
+ *  - It never emits a clean "incapable" on a packed/obscured binary — the
+ *    import table is unreliable there, so it returns `analysis_incomplete`
+ *    ("unpack first") rather than a false negative.
+ *  - When the required APIs are absent but GetProcAddress + a library loader are
+ *    present, it returns `possibly_via_dynamic_resolution` — it cannot prove
+ *    those resolvers are NOT used to reach the missing APIs without xref /
+ *    dynamic analysis, so it does not claim `incapable_statically`.
+ *  - The behavior→API table is generic malware-analysis knowledge, not tuned to
+ *    any specific sample.
+ */
+import { apiPresent } from "../parsers/imports.js";
+/**
+ * Behavior → prerequisite APIs. Base names only (apiPresent handles A/W). The
+ * minMatch threshold tolerates that a behavior rarely needs its entire API set
+ * and that import names vary, while still requiring a meaningful signature.
+ */
+export const BEHAVIOR_PREREQUISITES = {
+    clipboard_hijacking: {
+        description: "Read and/or replace clipboard contents (e.g. a crypto clipper).",
+        apis: ["OpenClipboard", "GetClipboardData", "SetClipboardData", "EmptyClipboard"],
+        minMatch: 2,
+    },
+    http_c2_wininet: {
+        description: "HTTP(S) command-and-control or download via the WinINet API.",
+        apis: ["InternetOpen", "InternetConnect", "InternetOpenUrl", "HttpOpenRequest", "HttpSendRequest", "HttpQueryInfo", "InternetReadFile"],
+        minMatch: 2,
+    },
+    winhttp_c2: {
+        description: "HTTP(S) command-and-control or download via the WinHTTP API.",
+        apis: ["WinHttpOpen", "WinHttpConnect", "WinHttpOpenRequest", "WinHttpSendRequest", "WinHttpReceiveResponse", "WinHttpReadData"],
+        minMatch: 2,
+    },
+    socket_c2: {
+        description: "Raw-socket network communication (Winsock).",
+        apis: ["WSAStartup", "socket", "connect", "send", "recv", "WSASend", "WSARecv"],
+        minMatch: 3,
+    },
+    process_injection_remote: {
+        description: "Inject code into another process (remote injection).",
+        apis: ["OpenProcess", "VirtualAllocEx", "WriteProcessMemory", "CreateRemoteThread", "NtCreateThreadEx", "QueueUserAPC", "NtMapViewOfSection", "NtWriteVirtualMemory"],
+        minMatch: 3,
+    },
+    process_injection_self: {
+        description: "Allocate, write, and execute code in the binary's own process.",
+        apis: ["VirtualAlloc", "VirtualProtect", "WriteProcessMemory", "NtProtectVirtualMemory"],
+        minMatch: 2,
+    },
+    registry_persistence_run: {
+        description: "Persist via a registry Run key (or similar).",
+        apis: ["RegOpenKeyEx", "RegCreateKeyEx", "RegSetValueEx"],
+        minMatch: 2,
+    },
+    lnk_persistence: {
+        description: "Create a shortcut (.lnk) for persistence via IShellLink (COM).",
+        apis: ["CoCreateInstance", "CoInitialize", "CoInitializeEx"],
+        minMatch: 1,
+    },
+    browser_credential_theft: {
+        description: "Decrypt DPAPI-protected secrets (browser logins, wallets).",
+        apis: ["CryptUnprotectData"],
+        minMatch: 1,
+    },
+    screen_capture: {
+        description: "Capture the screen via GDI.",
+        apis: ["GetDC", "GetDesktopWindow", "CreateCompatibleDC", "CreateCompatibleBitmap", "BitBlt", "GetDIBits"],
+        minMatch: 3,
+    },
+    keylog_polling: {
+        description: "Log keystrokes by polling key state.",
+        apis: ["GetAsyncKeyState", "GetKeyState", "GetKeyboardState"],
+        minMatch: 1,
+    },
+    keylog_hook: {
+        description: "Log keystrokes via a Windows hook.",
+        apis: ["SetWindowsHookEx"],
+        minMatch: 1,
+    },
+    network_share_enum: {
+        description: "Enumerate network shares / servers.",
+        apis: ["NetShareEnum", "NetServerEnum", "WNetEnumResource", "WNetOpenEnum"],
+        minMatch: 1,
+    },
+};
+/** Primitives that allow resolving APIs at runtime instead of importing them. */
+const DYNAMIC_RESOLVERS = ["GetProcAddress"];
+const LIBRARY_LOADERS = ["LoadLibrary", "LoadLibraryEx", "LdrLoadDll", "LdrGetProcedureAddress"];
+function followupFor(verdict) {
+    switch (verdict) {
+        case "capable_statically":
+            return "Static capability only. Confirm the behavior at runtime (speakeasy emulation or sandbox detonation) and verify the imported APIs are called from reachable code.";
+        case "possibly_via_dynamic_resolution":
+            return "Cannot rule out runtime API resolution. Xref the GetProcAddress calls or detonate dynamically to see which APIs are actually resolved.";
+        case "incapable_statically":
+            return "No static support found. If you still suspect this behavior, the sample may resolve APIs in a way static imports miss — detonate dynamically to be sure (static analysis cannot prove a negative under obfuscation).";
+        case "analysis_incomplete":
+            return "Unpack the sample (e.g. 'upx -d', or dump it from a sandbox) and re-run this check on the unpacked binary; the visible import table is not the real one.";
+        case "not_applicable":
+            return "This check applies to Windows PE files. Use the analysis tools appropriate for this file type.";
+    }
+}
+/** Detect the GetProcAddress + library-loader pair that enables runtime resolution. */
+export function hasDynamicResolution(functionSet) {
+    return (DYNAMIC_RESOLVERS.some((a) => apiPresent(a, functionSet)) &&
+        LIBRARY_LOADERS.some((a) => apiPresent(a, functionSet)));
+}
+/**
+ * Classify one behavior against an import set + context. Pure and deterministic.
+ */
+export function classifyPrerequisite(behaviorKey, def, functionSet, ctx) {
+    const present = def.apis.filter((a) => apiPresent(a, functionSet));
+    const missing = def.apis.filter((a) => !apiPresent(a, functionSet));
+    const dynamicResolutionPresent = hasDynamicResolution(functionSet);
+    let static_capability;
+    let rationale;
+    let recommended_followup;
+    if (present.length >= def.minMatch) {
+        static_capability = "capable_statically";
+        rationale =
+            `${present.length} of ${def.apis.length} prerequisite APIs are statically imported ` +
+                `(${present.join(", ")}). The binary CAN make these calls; this is not evidence the behavior ` +
+                `executes at runtime.`;
+        recommended_followup = followupFor(static_capability);
+    }
+    else if (ctx.managed) {
+        // A .NET/managed binary calls the framework, not native APIs — the native
+        // import table can't establish capability, so don't emit a false negative.
+        static_capability = "analysis_incomplete";
+        rationale =
+            "This is a managed/.NET assembly; native API imports do not reflect managed-code capability (a .NET " +
+                "program calls the framework, e.g. System.Windows.Forms.Clipboard, rather than importing native APIs). " +
+                "A clean negative cannot be given from the native import table.";
+        recommended_followup =
+            "Analyze as .NET: decompile with ilspycmd or dnSpy and look for the relevant framework calls " +
+                "(e.g. System.Windows.Forms.Clipboard, System.Net.Http, Microsoft.Win32.Registry).";
+    }
+    else if (ctx.obscured || !ctx.importsParsed) {
+        static_capability = "analysis_incomplete";
+        rationale = ctx.importsParsed
+            ? "The binary appears packed/obscured, so the import table does not reflect its real API surface. A clean negative cannot be given until it is unpacked."
+            : "The PE import table could not be read, so static capability cannot be assessed.";
+        recommended_followup =
+            "Unpack the sample (e.g. 'upx -d', or dump it from a sandbox) and re-run this check on the unpacked " +
+                "binary; the visible import table is not the real one.";
+    }
+    else if (dynamicResolutionPresent) {
+        static_capability = "possibly_via_dynamic_resolution";
+        rationale =
+            "The prerequisite APIs are not statically imported, but GetProcAddress and a library loader are present, " +
+                "so the APIs could be resolved at runtime. Static imports alone cannot rule this out — proving which APIs " +
+                "are resolved requires cross-reference or dynamic analysis.";
+        recommended_followup = followupFor(static_capability);
+    }
+    else {
+        static_capability = "incapable_statically";
+        rationale =
+            "The prerequisite APIs are not imported and no runtime-resolution primitives (GetProcAddress + a library " +
+                "loader) are present, so the behavior is not statically supported. Note: static analysis cannot prove a " +
+                "negative under obfuscation.";
+        recommended_followup = followupFor(static_capability);
+    }
+    return {
+        behavior: behaviorKey,
+        description: def.description,
+        required_apis: def.apis,
+        apis_present: present,
+        apis_missing: missing,
+        dynamic_resolution_present: dynamicResolutionPresent,
+        static_capability,
+        rationale,
+        recommended_followup,
+    };
+}
+//# sourceMappingURL=behavior-prerequisites.js.map

package/dist/analysis/behavior-prerequisites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-prerequisites.js","sourceRoot":"","sources":["../../src/analysis/behavior-prerequisites.ts"],"names":[],"mappings":"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"}

package/dist/analysis/file-diff.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure structured diff between two related samples (e.g. loader vs unpacked
+ * payload). Operates on already-extracted metadata so it is fully unit-testable
+ * with synthetic inputs; the handler does the tool runs and feeds this.
+ */
+export interface FileMeta {
+    file: string;
+    file_type: string;
+    sha256: string;
+    size_bytes: number;
+    arch?: string;
+    entropy?: number;
+    compiler?: string;
+    packer?: string;
+    /** Imported function names. */
+    imports: string[];
+    import_count: number;
+    /** capa capability names (empty when capa was not run). */
+    capabilities: string[];
+    /** Whether capa was actually run on this file (depth gate). */
+    capa_run: boolean;
+    /** Section names. */
+    sections: string[];
+}
+export interface SetDiff {
+    added: string[];
+    removed: string[];
+    common_count: number;
+}
+export interface FileDiff {
+    file_a: {
+        file: string;
+        sha256: string;
+    };
+    file_b: {
+        file: string;
+        sha256: string;
+    };
+    size_delta: number;
+    entropy_delta?: number;
+    architecture?: {
+        a?: string;
+        b?: string;
+    };
+    compiler?: {
+        a?: string;
+        b?: string;
+    };
+    packer?: {
+        a?: string;
+        b?: string;
+    };
+    imports: SetDiff;
+    capabilities?: SetDiff;
+    sections: SetDiff;
+    notes: string[];
+}
+export declare function diffFileMeta(a: FileMeta, b: FileMeta): FileDiff;
+//# sourceMappingURL=file-diff.d.ts.map

package/dist/analysis/file-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-diff.d.ts","sourceRoot":"","sources":["../../src/analysis/file-diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,QAAQ,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,MAAM,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAoBD,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAiC/D"}

package/dist/analysis/file-diff.js

@@ -0,0 +1,55 @@
+/**
+ * Pure structured diff between two related samples (e.g. loader vs unpacked
+ * payload). Operates on already-extracted metadata so it is fully unit-testable
+ * with synthetic inputs; the handler does the tool runs and feeds this.
+ */
+const CAP = 100;
+/** Diff two string sets (case-insensitive de-dupe, original casing preserved). */
+function setDiff(a, b) {
+    const aSet = new Set(a.map((x) => x.toLowerCase()));
+    const bSet = new Set(b.map((x) => x.toLowerCase()));
+    const added = [...new Set(b)].filter((x) => !aSet.has(x.toLowerCase()));
+    const removed = [...new Set(a)].filter((x) => !bSet.has(x.toLowerCase()));
+    let common = 0;
+    for (const x of aSet)
+        if (bSet.has(x))
+            common++;
+    const cap = (xs) => (xs.length > CAP ? [...xs.slice(0, CAP), `… and ${xs.length - CAP} more`] : xs);
+    return { added: cap(added), removed: cap(removed), common_count: common };
+}
+function changed(a, b) {
+    return a !== b ? { a, b } : undefined;
+}
+export function diffFileMeta(a, b) {
+    const notes = [];
+    const arch = changed(a.arch, b.arch);
+    if (arch)
+        notes.push(`Architecture changed ${a.arch ?? "?"} → ${b.arch ?? "?"} — a different build/stage.`);
+    const compiler = changed(a.compiler, b.compiler);
+    if (compiler)
+        notes.push(`Compiler/toolchain changed ${a.compiler ?? "?"} → ${b.compiler ?? "?"} (a toolchain mix is a strong multi-author/stage signal).`);
+    const packer = changed(a.packer, b.packer);
+    const imports = setDiff(a.imports, b.imports);
+    const sections = setDiff(a.sections, b.sections);
+    const bothCapa = a.capa_run && b.capa_run;
+    const capabilities = bothCapa ? setDiff(a.capabilities, b.capabilities) : undefined;
+    if (!bothCapa)
+        notes.push("Capability (capa) diff omitted — run with depth='standard' on both files for it.");
+    const entropy_delta = a.entropy !== undefined && b.entropy !== undefined ? Math.round((b.entropy - a.entropy) * 1000) / 1000 : undefined;
+    if (packer)
+        notes.push(`Packer differs (${a.packer ?? "none"} → ${b.packer ?? "none"}); compare on the unpacked stages for a meaningful import/capability diff.`);
+    return {
+        file_a: { file: a.file, sha256: a.sha256 },
+        file_b: { file: b.file, sha256: b.sha256 },
+        size_delta: b.size_bytes - a.size_bytes,
+        ...(entropy_delta !== undefined ? { entropy_delta } : {}),
+        ...(arch ? { architecture: arch } : {}),
+        ...(compiler ? { compiler } : {}),
+        ...(packer ? { packer } : {}),
+        imports,
+        ...(capabilities ? { capabilities } : {}),
+        sections,
+        notes,
+    };
+}
+//# sourceMappingURL=file-diff.js.map

package/dist/analysis/file-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-diff.js","sourceRoot":"","sources":["../../src/analysis/file-diff.ts"],"names":[],"mappings":"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"}

package/dist/analysis/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Analysis utilities for REMnux MCP server.
  */
-export { shouldSummarize, extractKeyLines, generateSummary, type ToolSummary, type AnalysisSummary, type ActionRequired, } from "./summarizer.js";
+export { shouldSummarize, extractKeyLines, generateSummary, summarizeCapabilityEvidence, type ToolSummary, type AnalysisSummary, type ActionRequired, type CapabilityEvidence, } from "./summarizer.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/analysis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC"}

package/dist/analysis/index.js

@@ -1,5 +1,5 @@
 /**
  * Analysis utilities for REMnux MCP server.
  */
-export { shouldSummarize, extractKeyLines, generateSummary, } from "./summarizer.js";
+export { shouldSummarize, extractKeyLines, generateSummary, summarizeCapabilityEvidence, } from "./summarizer.js";
 //# sourceMappingURL=index.js.map

package/dist/analysis/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,GAIhB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,2BAA2B,GAK5B,MAAM,iBAAiB,CAAC"}

package/dist/analysis/string-usage.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure classifier for verify_string_usage: given the strings/sections/xrefs
+ * radare2 reported for a queried value, decide whether the string is referenced
+ * by code — WITHOUT ever claiming it is "unused".
+ *
+ * The load-bearing rule (the "negative-only-when-complete" invariant): a
+ * `no_code_xrefs_detected` result is emitted ONLY when analysis was provably
+ * complete and well-formed. If the radare2 version/schema is unknown, the
+ * binary is packed/under-analyzed, output was truncated, or a non-empty xref
+ * blob failed to parse, the result is `unknown` — NEVER a negative. This mirrors
+ * the check_behavior_prerequisites packed-guard: it refuses to manufacture a
+ * confident "no xref" on exactly the obscured samples where static analysis is
+ * unreliable.
+ */
+import type { R2String, R2Section, R2Xref } from "../parsers/r2.js";
+export type XrefStatus = "referenced_from_code" | "no_code_xrefs_detected" | "data_only" | "unknown";
+export interface MatchGroup {
+    value: string;
+    /** value === query (vs a substring hit). */
+    exact: boolean;
+    vaddrs: Array<{
+        vaddr: number;
+        section: string;
+    }>;
+}
+export interface MatchResult {
+    value: string;
+    exact: boolean;
+    found_at: Array<{
+        vaddr: string;
+        section: string;
+    }>;
+    xref_status: XrefStatus;
+    xref_count: number;
+    data_pointer_found?: boolean;
+    xref_sources?: Array<{
+        from: string;
+        fcn?: string;
+        opcode?: string;
+    }>;
+    note: string;
+    recommended_followup: string;
+}
+export interface ClassifyContext {
+    isCodeFile: boolean;
+    fileType: string;
+    /** `r2 -v` was parsed, so xref fields are read against a known schema. */
+    schemaKnown: boolean;
+    /** Analysis ran to completion, not truncated, no parse anomaly, entry resolved. */
+    analysisComplete: boolean;
+    /** The binary looks packed/obscured (import table / r2 coverage unreliable). */
+    obscured: boolean;
+}
+/** Group string hits by distinct value (exact matches first), capped. */
+export declare function selectMatches(strings: R2String[], query: string, maxMatches?: number): {
+    groups: MatchGroup[];
+    truncated: boolean;
+};
+/**
+ * Whether a cross-reference originates from code. When section info is known,
+ * the source address must fall in an executable section (this filters `aar`
+ * heuristic refs whose source is in a data section). A containing function is
+ * surfaced as corroborating evidence; it's used as the signal only when section
+ * info is unavailable.
+ */
+export declare function isFromCode(xref: R2Xref, sections: R2Section[]): boolean;
+/**
+ * Classify one matched string value against the xrefs r2 reported for its
+ * address(es). `xrefs` is the parsed union across the group's vaddrs;
+ * `rawXrefParseAnomaly` is true when r2 emitted a non-empty xref blob that did
+ * not parse (version field drift — must degrade to `unknown`, never a negative).
+ */
+export declare function classifyMatch(group: MatchGroup, xrefs: R2Xref[], sections: R2Section[], ctx: ClassifyContext, rawXrefParseAnomaly?: boolean): MatchResult;
+//# sourceMappingURL=string-usage.d.ts.map

package/dist/analysis/string-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-usage.d.ts","sourceRoot":"","sources":["../../src/analysis/string-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,MAAM,UAAU,GAClB,sBAAsB,GACtB,wBAAwB,GACxB,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,WAAW,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,WAAW,EAAE,OAAO,CAAC;IACrB,mFAAmF;IACnF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,OAAO,EAAE,QAAQ,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,UAAU,SAAK,GACd;IAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAa9C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAKvE;AAuCD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,SAAS,EAAE,EACrB,GAAG,EAAE,eAAe,EACpB,mBAAmB,UAAQ,GAC1B,WAAW,CAqDb"}

package/dist/analysis/string-usage.js

@@ -0,0 +1,124 @@
+/**
+ * Pure classifier for verify_string_usage: given the strings/sections/xrefs
+ * radare2 reported for a queried value, decide whether the string is referenced
+ * by code — WITHOUT ever claiming it is "unused".
+ *
+ * The load-bearing rule (the "negative-only-when-complete" invariant): a
+ * `no_code_xrefs_detected` result is emitted ONLY when analysis was provably
+ * complete and well-formed. If the radare2 version/schema is unknown, the
+ * binary is packed/under-analyzed, output was truncated, or a non-empty xref
+ * blob failed to parse, the result is `unknown` — NEVER a negative. This mirrors
+ * the check_behavior_prerequisites packed-guard: it refuses to manufacture a
+ * confident "no xref" on exactly the obscured samples where static analysis is
+ * unreliable.
+ */
+const hex = (n) => "0x" + (n >>> 0 === n ? n.toString(16) : n.toString(16));
+/** Group string hits by distinct value (exact matches first), capped. */
+export function selectMatches(strings, query, maxMatches = 50) {
+    const byValue = new Map();
+    for (const s of strings) {
+        if (!s.value.includes(query))
+            continue;
+        let g = byValue.get(s.value);
+        if (!g) {
+            g = { value: s.value, exact: s.value === query, vaddrs: [] };
+            byValue.set(s.value, g);
+        }
+        g.vaddrs.push({ vaddr: s.vaddr, section: s.section });
+    }
+    const all = [...byValue.values()].sort((a, b) => (a.exact === b.exact ? 0 : a.exact ? -1 : 1));
+    return { groups: all.slice(0, maxMatches), truncated: all.length > maxMatches };
+}
+/**
+ * Whether a cross-reference originates from code. When section info is known,
+ * the source address must fall in an executable section (this filters `aar`
+ * heuristic refs whose source is in a data section). A containing function is
+ * surfaced as corroborating evidence; it's used as the signal only when section
+ * info is unavailable.
+ */
+export function isFromCode(xref, sections) {
+    if (sections.length > 0) {
+        return sections.some((s) => s.exec && xref.from >= s.vaddr && xref.from < s.vaddrEnd);
+    }
+    return xref.fcnAddr !== undefined || !!xref.fcnName;
+}
+const NOTE_REFERENCED = "At least one instruction in an executable section references this string's address. The string is reachable " +
+    "from recovered code, consistent with operational use. This does not prove the referencing code executes in " +
+    "any given run; confirm runtime use dynamically if the distinction matters.";
+const NOTE_NO_XREFS = "No direct code cross-reference to this string was found by static analysis (radare2 aa; aar). This is NOT " +
+    "evidence the string is unused. The reference may be computed at runtime (pointer arithmetic, indexing into a " +
+    "string table, stack/heap-built copies), resolved indirectly (pointer tables, relocations, vtables/RTTI), " +
+    "reachable only from code the analyzer did not recover (packed/encrypted/obfuscated regions, overlays, or " +
+    "functions analysis missed), or used by a separate component. Absence of a static xref means 'no DIRECT " +
+    "reference was resolvable here', not 'the string is dead or vestigial'. Do not dismiss it as a non-indicator " +
+    "on this basis alone; confirm with dynamic analysis or manual review.";
+const NOTE_DATA_POINTER = " A reference from a non-executable (data) section was found (the address is stored in a pointer/data table); " +
+    "this is still not a code reference and does not by itself establish operational use.";
+const NOTE_DATA_ONLY = (ft) => `This file is not an executable (detected type: ${ft}). It contains no code that could cross-reference the ` +
+    "string, so code-xref analysis does not apply. Evaluate the string as file content on its own merits.";
+const NOTE_UNKNOWN = "Cross-reference analysis could not be completed reliably (radare2 unavailable, analysis timed out, the binary " +
+    "appears packed/obscured, output was truncated, or the version's output could not be parsed). The xref status " +
+    "is UNKNOWN — this is explicitly NOT 'no xref found' and must not be read as evidence the string is unused. " +
+    "Unpack first, re-run with a longer timeout (depth=deep), or analyze manually.";
+const FOLLOWUP = {
+    referenced_from_code: "Confirm runtime use with emulation (speakeasy) or sandbox detonation; a static reference does not guarantee the path runs.",
+    no_code_xrefs_detected: "If this string matters to your assessment, confirm via dynamic analysis or manual review — do NOT record it as unused.",
+    data_only: "Use the analysis tools appropriate for this file type.",
+    unknown: "Unpack the sample, increase the timeout (depth=deep), or analyze manually, then re-check.",
+};
+/**
+ * Classify one matched string value against the xrefs r2 reported for its
+ * address(es). `xrefs` is the parsed union across the group's vaddrs;
+ * `rawXrefParseAnomaly` is true when r2 emitted a non-empty xref blob that did
+ * not parse (version field drift — must degrade to `unknown`, never a negative).
+ */
+export function classifyMatch(group, xrefs, sections, ctx, rawXrefParseAnomaly = false) {
+    const found_at = group.vaddrs.map((v) => ({ vaddr: hex(v.vaddr), section: v.section }));
+    const base = { value: group.value, exact: group.exact, found_at };
+    if (!ctx.isCodeFile) {
+        return {
+            ...base,
+            xref_status: "data_only",
+            xref_count: 0,
+            note: NOTE_DATA_ONLY(ctx.fileType || "unknown"),
+            recommended_followup: FOLLOWUP.data_only,
+        };
+    }
+    const codeXrefs = xrefs.filter((x) => isFromCode(x, sections));
+    if (codeXrefs.length > 0) {
+        const xref_sources = codeXrefs.slice(0, 10).map((x) => ({
+            from: hex(x.from),
+            ...(x.fcnName ? { fcn: x.fcnName } : {}),
+            ...(x.opcode ? { opcode: x.opcode } : {}),
+        }));
+        return {
+            ...base,
+            xref_status: "referenced_from_code",
+            xref_count: codeXrefs.length,
+            xref_sources,
+            note: NOTE_REFERENCED,
+            recommended_followup: FOLLOWUP.referenced_from_code,
+        };
+    }
+    // No code xref. A negative is allowed ONLY when analysis was provably complete.
+    const degraded = !ctx.schemaKnown || !ctx.analysisComplete || ctx.obscured || rawXrefParseAnomaly;
+    if (degraded) {
+        return {
+            ...base,
+            xref_status: "unknown",
+            xref_count: 0,
+            note: NOTE_UNKNOWN,
+            recommended_followup: FOLLOWUP.unknown,
+        };
+    }
+    const dataPointerFound = xrefs.length > 0; // refs exist, but none from code
+    return {
+        ...base,
+        xref_status: "no_code_xrefs_detected",
+        xref_count: 0,
+        ...(dataPointerFound ? { data_pointer_found: true } : {}),
+        note: NOTE_NO_XREFS + (dataPointerFound ? NOTE_DATA_POINTER : ""),
+        recommended_followup: FOLLOWUP.no_code_xrefs_detected,
+    };
+}
+//# sourceMappingURL=string-usage.js.map

package/dist/analysis/string-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-usage.js","sourceRoot":"","sources":["../../src/analysis/string-usage.ts"],"names":[],"mappings":"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"}