Frequently Asked Questions常见问题

Rikune supports Linux, macOS, and Windows, but the recommended shape depends on what you need. Use static-only Linux Docker with RUNTIME_MODE=disabled when you do not want to execute samples, use the hybrid Docker profile to connect a Linux analyzer to a Windows Host Agent / Windows Sandbox or Hyper-V VM runtime, and use a Windows-native analyzer with auto-sandbox when you want single-host Windows Sandbox execution. Docker or WSL analyzers cannot use auto-sandbox directly.

Rikune 支持 Linux、macOS 和 Windows，但推荐部署方式取决于你的目标。若你不想执行样本，请使用带有 RUNTIME_MODE=disabled 的纯静态 Linux Docker；若要让 Linux analyzer 连接 Windows Host Agent / Windows Sandbox 或 Hyper-V VM 运行时，请使用 hybrid Docker profile；若要在单机 Windows 上通过 Windows Sandbox 执行真实样本，请使用带有 auto-sandbox 的Windows 原生 analyzer。Docker 或 WSL 中的 analyzer 不能直接使用 auto-sandbox。

RUNTIME_HOST_AGENT_API_KEY is the control-plane key used by the analyzer when it asks the Windows Host Agent to start or stop Windows Sandbox. RUNTIME_API_KEY is the data-plane key used by the analyzer when it talks directly to a Windows Runtime Node. Keep them separate unless you intentionally reuse the same value for both.

RUNTIME_HOST_AGENT_API_KEY 是控制面密钥，用于 analyzer 请求 Windows Host Agent 启动或停止 Windows Sandbox。RUNTIME_API_KEY 是数据面密钥，用于 analyzer 直接访问 Windows Runtime Node。除非你明确决定复用同一个值，否则请将它们分开配置。

For native mode, yes — set GHIDRA_INSTALL_DIR to your Ghidra installation path. With Docker, Ghidra is pre-installed in the container image.

原生模式下需要 — 将 GHIDRA_INSTALL_DIR 设为你的 Ghidra 安装路径。使用 Docker 时，Ghidra 已预装在容器镜像中。

Any MCP-compatible client works. We provide install scripts for Claude Desktop, VS Code Copilot, and Codex CLI. Other clients (Qwen, etc.) can connect via standard MCP configuration.

任何 MCP 兼容客户端均可使用。我们提供了 Claude Desktop、VS Code Copilot 和 Codex CLI 的安装脚本。其他客户端（通义千问等）可通过标准 MCP 配置连接。

Start the Docker profile first, then configure Codex to run docker exec -i -e API_ENABLED=false rikune-analyzer node dist/index.js. The API_ENABLED=false flag is important because the dashboard/API is already owned by the long-running container process. Also set startup_timeout_sec = 180; Docker startup loads the plugin graph and can exceed Codex's 30-second default.

先启动 Docker profile，然后让 Codex 执行 docker exec -i -e API_ENABLED=false rikune-analyzer node dist/index.js。 API_ENABLED=false 很重要，因为 Dashboard/API 已经由长期运行的容器进程占用。 同时设置 startup_timeout_sec = 180；Docker 启动时需要加载插件图，可能超过 Codex 默认的 30 秒。

No. The installer prepares the Host Agent and Docker analyzer. Windows Sandbox is launched on demand when a dynamic/sandbox MCP tool requests real sample execution, such as runtime.debug.session.start or sandbox.execute. sandbox.execute also returns execution_semantics, so clients can tell whether the result came from live Windows Sandbox, live Hyper-V, safe simulation, or emulation. Read-only probes such as dynamic.runtime.status, dynamic.toolkit.status, dynamic.deep_plan, and dynamic.persona.plan, plus planners such as debug.network.plan, debug.managed.plan, and debug.gui.handoff, do not launch it. Correlation tools such as dynamic.behavior.diff, analysis.evidence.graph, and crypto.lifecycle.graph only read persisted artifacts. The Host Agent must run in a logged-on Windows user session; do not run the Sandbox backend as a traditional Windows Service. In Docker/WSL deployments the Host Agent must be reachable through host.docker.internal:18082, so the installer binds it to 0.0.0.0, adds best-effort Hyper-V firewall rules for the Host Agent/runtime ports, and keeps API-key authentication enabled. A Sandbox window may appear during that task and close after the runtime session finishes; some automation paths expose only the backing VM/runtime endpoint instead of a visible interactive window.

不会。安装器只负责准备 Host Agent 和 Docker analyzer。Windows Sandbox 会在动态/沙箱 MCP 工具请求真实样本执行时按需启动，例如 runtime.debug.session.start 或 sandbox.execute。sandbox.execute 也会返回 execution_semantics，让客户端区分结果来自 live Windows Sandbox、live Hyper-V、safe simulation 还是 emulation。dynamic.runtime.status、 dynamic.toolkit.status、dynamic.deep_plan、dynamic.persona.plan 这类只读探测，以及 debug.network.plan、debug.managed.plan、debug.gui.handoff 这类规划工具不会启动它；dynamic.behavior.diff、 analysis.evidence.graph 和 crypto.lifecycle.graph 只读取已持久化 artifact。Host Agent 必须运行在已登录的 Windows 用户会话里；不要把 Sandbox 后端作为传统 Windows Service 运行。Docker/WSL 部署需要通过 host.docker.internal:18082 访问 Host Agent，所以安装器会绑定 0.0.0.0，best-effort 添加 Host Agent/runtime 端口的 Hyper-V firewall 规则，并保持 API Key 鉴权。执行任务期间可能看到 Sandbox 窗口，运行时会话结束后会关闭；某些自动化路径只暴露后台 VM/runtime endpoint，不一定出现交互窗口。

Yes. Use the Host Agent hyperv-vm backend when you want checkpoint rollback, longer debugging sessions, or unattended-style runtime experiments. The VM must already run the Rikune Runtime Node and expose its HTTP endpoint to the analyzer or Host Agent network. Per session, choose hyperv_retention_policy as clean_rollback, stop_only, or preserve_dirty.

可以。需要 checkpoint 回滚、长时间调试会话或无人值守风格实验时，可以使用 Host Agent 的 hyperv-vm 后端。VM 内需要提前运行 Rikune Runtime Node，并让 analyzer 或 Host Agent 所在网络能够访问它的 HTTP endpoint。每次会话可用 hyperv_retention_policy 选择 clean_rollback、stop_only 或 preserve_dirty。

Common Python packages like pefile, lief, and yara-python may fail on some platforms. Try:

像 pefile、lief、yara-python 这样的 Python 包在某些平台上可能安装失败。尝试：

# Install with specific versions
pip install pefile==2024.8.26
pip install lief==0.15.1

# For YARA, use yara-python binary wheels
pip install yara-python

If you're on Windows without a C compiler, use the Docker image instead. 如果你在 Windows 上没有 C 编译器，建议使用 Docker 镜像。

By default, the SQLite database is stored at DB_PATH (defaults to ./data/database.db in native mode, /app/data/database.db in Docker). You can override this with the DB_PATH environment variable.

默认情况下，SQLite 数据库存储在 DB_PATH（原生模式默认 ./data/database.db，Docker 中默认 /app/data/database.db）。你可以通过 DB_PATH 环境变量覆盖。

Place your rules under the yara_rules/ directory in your workspace root. The directory structure is:

将规则放在工作空间根目录的 yara_rules/ 目录下。目录结构为：

yara_rules/
├── custom/          # Your custom rules
├── community/       # Community rule sets
└── index.yar        # Auto-generated index

Ghidra's headless analyzer performs deep binary analysis including decompilation, which is CPU-intensive. The staged pipeline runs it asynchronously to avoid MCP timeouts. Large binaries (50MB+) may take several minutes. Use workflow.stage.preview to check estimated time before running.

Ghidra 的无头分析器执行深度二进制分析（包括反编译），是 CPU 密集型操作。分阶段流水线异步执行以避免 MCP 超时。大型二进制文件（50MB+）可能需要几分钟。使用 workflow.stage.preview 在运行前检查预计时间。

Yes. Rikune auto-detects .NET assemblies and uses specialized profiling paths. The dotnet.metadata tool extracts CLR metadata, type definitions, and method signatures without Ghidra.

支持。Rikune 自动检测 .NET 程序集并使用专用分析路径。dotnet.metadata 工具可提取 CLR 元数据、类型定义和方法签名，无需 Ghidra。

It depends on the profile. static and hybrid use the leaner analyzer image, while full includes the heavier Linux-side toolchain (Ghidra, Rizin, angr, RetDec, etc.). Keep at least 10 GB free for static/hybrid and more headroom for full builds and Ghidra projects.

取决于 profile。static 和 hybrid 使用较轻的 analyzer 镜像； full 才包含更重的 Linux 侧工具链（Ghidra、Rizin、angr、RetDec 等）。 static/hybrid 至少预留 10 GB，full 构建和 Ghidra 项目需要更多空间。

Mount a local directory as a volume with -v ./samples:/samples:ro, or use the HTTP API at POST /api/v1/samples to upload files directly.

通过 -v ./samples:/samples:ro 挂载本地目录，或使用 HTTP API POST /api/v1/samples 直接上传文件。

Rikune uses cache prewarming — the L1 (memory) and L2 (filesystem) caches automatically persist results. On restart, the cache manager can prewarm with the most recently accessed entries, reducing cache misses by 60-80% and improving response time 2-5x for common operations.

Rikune 使用缓存预热 — L1（内存）和 L2（文件系统）缓存自动持久化结果。重启时缓存管理器可以预热最近访问的条目，缓存未命中率降低 60-80%，常见操作响应时间提升 2-5 倍。

Use budget lanes to control concurrency. Increase MAX_PYTHON_WORKERS for parallel Python tasks. The runtime reuses warm compatible workers instead of cold-starting — static Python helpers and Rizin preview paths are pooled, while Ghidra remains scheduler-governed for isolation. Database batch inserts are 10-50x faster than individual operations.

使用预算通道控制并发。增加 MAX_PYTHON_WORKERS 以并行化 Python 任务。运行时复用兼容的热工作进程而非冷启动 — 静态 Python 辅助程序和 Rizin 预览路径使用池化，Ghidra 保持调度隔离。数据库批量插入比逐条操作快 10-50 倍。

Large samples may receive intentionally limited analysis depth. Check the coverage_level and completion_state fields in results. A bounded state means the result is intentionally partial — use the returned upgrade_paths to deepen analysis safely. See the Analysis Coverage docs for full details.

大型样本可能会获得有意限制的分析深度。检查结果中的 coverage_level 和 completion_state 字段。bounded 状态表示结果是有意的部分结果 — 使用返回的 upgrade_paths 安全加深分析。详见分析覆盖文档。