Usage Guide使用指南

sample.ingest

The primary entry point for all analysis. Ingest a PE binary and receive a structured triage result. 所有分析的主入口。导入 PE 二进制文件并接收结构化的分诊结果。

Parameters参数

Example示例

{
  "name": "sample.ingest",
  "arguments": {
    "path": "C:\\samples\\target.exe",
    "source": "manual_upload"
  }
}

{
  "sample_id": "sha256:a1b2c3d4...",
  "filename": "target.exe",
  "file_type": "PE32+",
  "size": 1258291,
  "triage": {
    "is_dotnet": false,
    "is_packed": true,
    "packer_hint": "UPX",
    "import_count": 42,
    "section_count": 5
  }
}

Core Analysis Tools核心分析工具

Workflow Tools工作流工具

Orchestrate multi-stage analysis with the staged pipeline. 使用分阶段流水线编排多阶段分析。

Ghidra ToolsGhidra 工具

Dynamic Analysis Tools动态分析工具

Threat Intelligence Tools威胁情报工具

Analysis Runtime分析运行时

The server uses persisted staged runs as the primary orchestration model. All analysis flows through a seven-stage pipeline with run-level contracts.服务器使用持久化分阶段运行作为主要编排模型。所有分析通过七阶段流水线以运行级别契约执行。

Primary Workflow主要工作流

workflow.analyze.start   → Create/reuse persisted run, execute fast_profile inline
workflow.analyze.status  → Primary progress surface for clients and AI agents
workflow.analyze.promote → Queue deeper stages without rerunning compatible work

Stage Graph阶段图

Worker Pools & Budget Lanes工作池与预算通道

The runtime separates fast reuse from deep isolation. Execution is admitted through explicit budget lanes:运行时将快速复用与深度隔离分离。执行通过显式预算通道准入：

Canonical Evidence规范证据

High-cost reusable outputs are persisted as canonical evidence per sample. Evidence families include:高成本可复用输出按样本持久化为规范证据。证据系列包括：

Analysis Coverage Boundaries分析覆盖边界

Large or expensive samples may not receive the same depth. The server reports boundaries explicitly instead of forcing clients to infer from warnings.大型或高开销样本可能不会获得相同的分析深度。服务器显式报告边界，而非迫使客户端从警告中推断。

Coverage Levels覆盖级别

Completion States完成状态

Key Response Fields关键响应字段

Deepening Analysis Safely安全加深分析

Use upgrade_paths instead of guessing. Common upgrades:使用 upgrade_paths 而非猜测。常见升级路径：

Async Job Pattern异步任务模式

The staged runtime uses workflow.analyze.* as the primary orchestration contract. task.status is available for low-level job inspection but is not the main workflow surface.分阶段运行时使用 workflow.analyze.* 作为主要编排契约。task.status 可用于底层任务检查但不是主要工作流界面。

Preferred Pattern推荐模式

workflow.analyze.start(sample_id, goal='triage')
workflow.analyze.promote(run_id, through_stage='function_map')
workflow.analyze.status(run_id)

Tools That Queue Work排队工作的工具

Polling Guidance轮询指南

When a stage is queued: (1) prefer workflow.analyze.status(run_id); (2) only use task.status(job_id) for raw job details; (3) respect polling_guidance wait recommendations.当阶段排队时：(1) 优先使用 workflow.analyze.status(run_id)；(2) 仅在需要原始任务详情时用 task.status(job_id)；(3) 遵守 polling_guidance 等待建议。

Large staged responses may prune historical stage payloads and report this in top-level warnings. Use artifact.read for the full artifact payload. task.status also reports external_active_* memory telemetry for analyzer subprocesses that are still running outside the queue view.大型 staged 响应可能会裁剪历史阶段结果，并在顶层 warnings 中说明。完整内容请使用 artifact.read。task.status 还会通过 external_active_* 暴露仍在队列视图之外运行的 analyzer 子进程内存遥测。