Usage Guide — Rikune

sample.ingest

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

Parameters参数

Parameter参数	Type类型	Required必需	Description描述
`path`	string	✓	Path to sample file样本文件路径
`filename`	string	—	Original filename (auto-detected)原始文件名（自动检测）
`source`	string	—	Source label (e.g. "malware_zoo")样本来源标签

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核心分析工具

Tool工具	Category类别	Description描述
`sample.ingest`	PE	Ingest & triage a PE sample导入并分诊 PE 样本
`pe.headers`	PE	Parse PE headers (DOS, COFF, Optional)解析 PE 头（DOS、COFF、可选头）
`pe.imports`	PE	Extract import table提取导入表
`pe.exports`	PE	Extract export table提取导出表
`pe.sections`	PE	Section table with entropy带熵值的节表
`pe.resources`	PE	Resource directory tree资源目录树
`pe.strings`	PE	Extract printable strings提取可打印字符串
`detect.compiler`	Detect	Compiler & packer detection (DIE)编译器和加壳检测（DIE）
`yara.scan`	YARA	Scan with YARA rules使用 YARA 规则扫描
`capa.analyze`	capa	Detect capabilities via capa通过 capa 检测能力

Workflow Tools工作流工具

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

Tool工具	Description描述
`workflow.analyze.start`	Start a staged analysis run启动分阶段分析运行
`workflow.analyze.status`	Check analysis run status检查分析运行状态
`workflow.summarize`	Generate final summary report生成最终摘要报告
`workflow.stage.preview`	Preview a stage before execution执行前预览阶段
`workflow.stage.advance`	Advance to the next stage推进到下一阶段

Ghidra ToolsGhidra 工具

Tool工具	Description描述
`ghidra.decompile`	Decompile a function by name or address按名称或地址反编译函数
`ghidra.functions.list`	List all recovered functions列出所有恢复的函数
`ghidra.xrefs`	Cross-reference analysis交叉引用分析
`ghidra.cfg`	Control flow graph extraction控制流图提取
`ghidra.pseudocode`	Source-like pseudocode export类源码伪代码导出

Dynamic Analysis Tools动态分析工具

Tool工具	Description描述
`frida.hook`	Generate Frida hook scripts生成 Frida Hook 脚本
`frida.trace`	API tracing with Frida使用 Frida 进行 API 追踪
`qiling.emulate`	Emulate binary with Qiling使用 Qiling 模拟二进制
`angr.symbolic`	Symbolic execution with angr使用 angr 进行符号执行
`wine.debug`	Debug with Wine/winedbg使用 Wine/winedbg 调试

Threat Intelligence Tools威胁情报工具

Tool工具	Description描述
`intel.c2.extract`	Extract C2 indicators提取 C2 指标
`intel.ioc.export`	Export IOCs (STIX/OpenIOC)导出 IOC（STIX/OpenIOC）
`intel.family.classify`	Malware family classification恶意软件家族分类
`yara.generate`	Auto-generate YARA rules自动生成 YARA 规则
`sigma.generate`	Auto-generate Sigma rules自动生成 Sigma 规则

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阶段图

Stage阶段	Backend Roles后端角色
`fast_profile`	PE leaf tools, preview strings, Rizin, YARA, YARA-X, UPXPE 叶工具、预览字符串、Rizin、YARA、YARA-X、UPX
`enrich_static`	Full strings, FLOSS, capability triage, PE structure, crypto, Rust profile完整字符串、FLOSS、能力分类、PE 结构、加密、Rust 分析
`function_map`	Ghidra deep attribution + bounded Rizin corroborationGhidra 深度归因 + 有界 Rizin 校验
`reconstruct`	Reconstruct workflow + targeted RetDec and angr artifacts重建工作流 + 定向 RetDec 和 angr 产物
`dynamic_plan`	Readiness probes, breakpoint planning, Qiling, PANDA就绪探测、断点规划、Qiling、PANDA
`dynamic_execute`	Safe simulation first, approval-gated execution paths安全模拟优先、审批门控执行路径
`summarize`	Persisted summary digests and report views持久化摘要和报告视图

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

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

preview-static

enrich-static

deep-attribution

dynamic-plan

dynamic-execute

manual-execution

artifact-only

Canonical Evidence规范证据

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

strings

binary_role

context_link

backend_preview

summary

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覆盖级别

Level级别	Description描述
`quick`	First-pass profile only仅首次画像
`static_core`	Static evidence + bounded enrichment静态证据 + 有界增强
`deep_static`	Deep static stage completed深度静态阶段完成
`reconstruction`	Reconstruction/export boundary reached重建/导出边界已达
`dynamic_verified`	Dynamic verification boundary reached动态验证边界已达

Completion States完成状态

State状态	Meaning含义
`queued`	Work has not completed yet工作尚未完成
`bounded`	Intentionally partial result有意的部分结果
`degraded`	A deeper stage failed or fell back更深阶段失败或回退
`completed`	Workflow reached its intended boundary工作流达到预期边界
`partial`	Only a subset of expected evidence available仅有预期证据的子集可用

Key Response Fields关键响应字段

Field字段	Purpose用途
`coverage_gaps`	Names missing, skipped, blocked, or degraded domains列出缺失、跳过、阻塞或降级的领域
`known_findings`	Strongest evidence-backed conclusions within current boundary当前边界内最强的证据支持结论
`suspected_findings`	Plausible but heuristic conclusions合理但启发式的结论
`unverified_areas`	Domains not actually covered未实际覆盖的领域
`upgrade_paths`	Machine-readable next steps to close gaps机器可读的下一步操作以弥合差距

Deepening Analysis Safely安全加深分析

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

Missing Domain缺失领域	Action操作
`ghidra_analysis`	`ghidra.analyze` / `analysis.context.link`
`reconstruction_export`	`workflow.reconstruct`
`summary_synthesis`	`workflow.summarize`
`dynamic_behavior`	`dynamic.dependencies` → `sandbox.execute`

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排队工作的工具

Tool工具	Notes说明
`workflow.analyze.promote`	Queues deeper stages排队更深阶段
`ghidra.analyze`	Deep attribution backend深度归因后端
`workflow.deep_static`	Full static pipeline完整静态流水线
`workflow.reconstruct`	Source-like code export类源码导出
`strings.extract(mode='full')`	May return bounded preview depending on size可能根据大小返回有界预览

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 等待建议。

Usage Guide使用指南