Docker DeploymentDocker 部署

Prerequisites前置要求

• Docker 20.10+
• At least 10 GB free disk space
• 至少 10 GB 可用磁盘空间
• 8 GB+ RAM recommended
• 建议 8 GB+ 内存

Quick Start快速开始

Guided installer向导式安装

.\rikune.ps1

./rikune.sh

The top-level scripts are the normal entry point. They install, start, stop, show status, stream logs, run health checks, regenerate Docker files, and bootstrap the Windows runtime when you choose the hybrid path. 顶层脚本是普通用户的入口。它们负责安装、启动、停止、状态查询、日志、健康检查、 Docker 文件生成，以及在选择 hybrid 方案时初始化 Windows 运行时。

Static-only analyzer (safe default)纯静态 analyzer（安全默认）

.\rikune.ps1 install -Profile static -DataRoot "D:\Docker\rikune"

Hybrid analyzer + Windows runtime plane混合 analyzer + Windows 运行时面

# Single Windows host
.\rikune.ps1 install -Profile hybrid -InstallRuntime

# Hyper-V VM runtime backend for debugging
.\rikune.ps1 install -Profile hybrid -InstallRuntime `
  -RuntimeBackend hyperv-vm `
  -HyperVVmName "rikune-runtime" `
  -HyperVSnapshotName "clean-runtime" `
  -HyperVRuntimeEndpoint "http://192.168.1.50:18081" `
  -HyperVRestoreOnRelease

# Linux analyzer + remote Windows Host Agent
./rikune.sh install --profile hybrid --windows-host <windows-host> --windows-user <windows-user>

In the single-host Windows hybrid path, the script installs or starts the Host Agent, checks the selected runtime backend, writes .docker-runtime.env, builds the analyzer image, and starts rikune-analyzer. The runtime is launched on demand by dynamic/sandbox tools, not as a permanently open GUI during installation. The default Windows Sandbox backend must run from a logged-on user session; the Host Agent binds to 0.0.0.0 by default and the installer adds best-effort Hyper-V firewall rules so Docker can reach it through host.docker.internal:18082 and the runtime portproxy range; the Hyper-V VM backend can be used for checkpoint-based debugging. 在单机 Windows hybrid 方案中，脚本会安装或启动 Host Agent、检查所选运行时后端、写入 .docker-runtime.env、构建 analyzer 镜像并启动 rikune-analyzer。运行时由动态/沙箱工具按需启动，安装时不会要求一直打开一个 Sandbox 窗口。默认 Windows Sandbox 后端必须运行在已登录用户会话里；Host Agent 默认绑定 0.0.0.0，并 best-effort 添加 Hyper-V firewall 规则，让 Docker 可以通过 host.docker.internal:18082 和 runtime portproxy 端口访问；Hyper-V VM 后端可用于基于 checkpoint 的调试，并可选择退出时回滚、关机保留或保留脏现场。

Full Linux toolchain image全量 Linux 工具链镜像

.\rikune.ps1 install -Profile full -DataRoot "D:\Docker\rikune"

Windows runtime bootstrapWindows 运行时面初始化

.\install-runtime-windows.ps1 -Headless -ApiKey <host-agent-key>

# Hyper-V VM backend
.\install-runtime-windows.ps1 -Headless -ApiKey <host-agent-key> `
  -RuntimeBackend hyperv-vm `
  -HyperVVmName "rikune-runtime" `
  -HyperVSnapshotName "clean-runtime" `
  -HyperVRuntimeEndpoint "http://192.168.1.50:18081" `
  -HyperVRestoreOnRelease

Auth split: use RUNTIME_HOST_AGENT_API_KEY for Analyzer → Host Agent control requests, and use RUNTIME_API_KEY only when the Windows Runtime Node itself requires a separate API key. 鉴权分层：RUNTIME_HOST_AGENT_API_KEY 仅用于 Analyzer → Host Agent 控制请求；RUNTIME_API_KEY 仅在 Windows Runtime Node 自身需要单独鉴权时使用。

Runtime debug flow: MCP clients should call dynamic.runtime.status first to inspect configured Runtime Node and Host Agent capabilities, dynamic.toolkit.status to inspect runtime-side CDB/ProcDump/ProcMon/Sysmon/TTD/x64dbg/dnSpy/Frida/dotnet readiness, dynamic.deep_plan to pick a bounded behavior/debugger/memory/network/.NET profile, debug.network.plan, debug.managed.plan, and debug.gui.handoff for network lab, .NET runtime, and manual GUI handoff detail, dynamic.persona.plan to prepare a planning-only Sandbox/Hyper-V persona checklist, dynamic.behavior.diff, analysis.evidence.graph, and crypto.lifecycle.graph to correlate runtime observations with static expectations, runtime.hyperv.control when a Hyper-V VM checkpoint must be listed, created, restored, or stopped, runtime.debug.session.start to start or attach a Windows runtime and choose hyperv_retention_policy as clean_rollback, stop_only, or preserve_dirty, runtime.debug.command to dispatch debug.session.*, sandbox.execute, dynamic.behavior.capture, telemetry, ProcDump, managed safe-run, or dump work, then runtime.debug.session.stop to release the backend. 运行时调试流程：MCP 客户端应先调用 dynamic.runtime.status 检查 Runtime Node 和 Host Agent 能力，用 dynamic.toolkit.status 查询 runtime 内 CDB/ProcDump/ProcMon/Sysmon/TTD/x64dbg/dnSpy/Frida/dotnet 就绪状态，用 dynamic.deep_plan 选择受限的行为、调试器、内存、网络或 .NET profile，用 debug.network.plan、debug.managed.plan 和 debug.gui.handoff 查看网络实验、.NET runtime 和手动 GUI handoff 细节，用 dynamic.persona.plan 准备只规划不启动的 Sandbox/Hyper-V persona 清单，用 dynamic.behavior.diff、analysis.evidence.graph 和 crypto.lifecycle.graph 把运行时观察关联回静态预期，再调用 runtime.hyperv.control 列出、创建、恢复或停止 Hyper-V VM checkpoint，然后调用 runtime.debug.session.start 启动或附着 Windows runtime，并用 hyperv_retention_policy 选择 clean_rollback、stop_only 或 preserve_dirty，再用 runtime.debug.command 分发 debug.session.*、 sandbox.execute、dynamic.behavior.capture、遥测、ProcDump、managed safe-run 或转储任务，最后用 runtime.debug.session.stop 释放后端。

Deployment Topologies部署拓扑

Rikune now supports a split analyzer/runtime model. Pick the deployment shape that matches your safety and automation goals: Rikune 现在支持 analyzer/runtime 拆分模型。请根据你的安全目标和自动化需求选择部署方式：

Important: Docker or WSL analyzers cannot use auto-sandbox. For Linux-side analyzers, use the hybrid profile when you need a Windows runtime. 重要：Docker 或 WSL 中的 analyzer 不能使用 auto-sandbox。如果 analyzer 在 Linux 一侧，需要 Windows 运行时时请使用 hybrid profile。

Plugin-Driven Docker Generation插件驱动的 Docker 生成

Rikune does not maintain one hand-written Dockerfile. Each plugin declares exactly what system-level dependencies it needs, and the generator produces profile-specific outputs: static, hybrid, and full. Plugins remain the single source of truth. Rikune 不手动维护单一 Dockerfile。 每个插件在代码中声明自己所需的系统级依赖， 生成器自动读取所有插件声明并产出 Dockerfile 和 Compose 文件，并按 static、hybrid、full 三个 profile 分流。插件是唯一真相源。

How It Works工作原理

┌─────────────────────────────────────────────────────────────┐
│  Plugin SDK  (src/plugins/sdk.ts)                       │
│                                                             │
│  PluginSystemDep {                                       │
│    name, type, envVar, dockerDefault,                     │
│    dockerFeature?     → controls # @if blocks          │
│    aptPackages?       → merged into apt-get install    │
│    dockerValidation?  → merged into validation step    │
│  }                                                         │
└──────────────────────┬──────────────────────────────────────┘
                       │ each plugin implements
                       ▼
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│ ghidra   │  │ frida    │  │ malware  │  │ ...×32   │
│ systemDeps│  │ systemDeps│  │ systemDeps│  │ systemDeps│
└─────┬────┘  └─────┬────┘  └─────┬────┘  └─────┬────┘
      │              │              │              │
      └──────────────┴──────┬───────┴──────────────┘
                            │ dynamic import at build time
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Generator  (scripts/generate-docker.mjs)                  │
│                                                             │
│  1. discoverPluginIds()  → scan dist/plugins/               │
│  2. loadPluginMetadata() → import deps + execution domain      │
│  3. collectRequirements() → features, apt, env, validation   │
│  4. processTemplate()    → conditional Dockerfile             │
│  5. generateCompose()    → profile-specific Compose files      │
└──────────────┬──────────────────────────────┬───────────────┘
               │                              │
               ▼                              ▼
  📄 Dockerfile(s)                 📄 Compose file(s)
    (multi-stage, only               (volumes, env, args
     needed stages)                   matching features)

Step 1 — Plugin Declares Dependencies步骤 1 — 插件声明依赖

Each plugin's systemDeps array describes what it needs. Three fields control Docker generation: 每个插件的 systemDeps 数组描述其所需依赖，三个字段控制 Docker 生成：

systemDeps: [
  {
    type: 'binary',
    name: 'analyzeHeadless',
    envVar: 'GHIDRA_INSTALL_DIR',
    dockerDefault: '/opt/ghidra',
    // ── Docker-specific fields ──
    dockerFeature: 'ghidra',        // activates # @if ghidra blocks
    dockerValidation: [
      'test -f /opt/ghidra/support/analyzeHeadless'
    ]
  },
  {
    type: 'binary',
    name: 'java',
    dockerDefault: '/opt/java/openjdk/bin/java',
    dockerFeature: 'ghidra',        // same feature group
  }
]

systemDeps: [
  {
    type: 'binary',
    name: 'gdb',
    dockerFeature: 'gdb',
    aptPackages: ['gdb', 'ltrace', 'strace'],  // merged into apt-get
  }
]

Step 2 — Template Uses Conditionals步骤 2 — 模板使用条件块

The Dockerfile template (docker/Dockerfile.template) wraps optional stages in # @if / # @endif markers: Dockerfile 模板（docker/Dockerfile.template）用 # @if / # @endif 标记包裹可选阶段：

# @if ghidra
FROM eclipse-temurin:21-jdk AS ghidra-stage
ARG GHIDRA_VERSION=11.3.2
RUN curl -L ... | unzip ...
# @endif ghidra

# @if angr
RUN python -m venv /opt/angr-venv && \
    /opt/angr-venv/bin/pip install angr
# @endif angr

Step 3 — Generator Reads Plugins & Produces Output步骤 3 — 生成器读取插件并输出

The generator (scripts/generate-docker.mjs) performs 5 steps with zero hardcoded mappings: 生成器（scripts/generate-docker.mjs）执行 5 个步骤，没有任何硬编码映射：

CLI UsageCLI 用法

# Full Linux image
node scripts/generate-docker.mjs --profile=full

# Static-only analyzer image
node scripts/generate-docker.mjs --profile=static

# Hybrid analyzer with remote Windows runtime
node scripts/generate-docker.mjs --profile=hybrid

# Generate all profiles
node scripts/generate-docker.mjs --all-profiles

# Preview without writing files
node scripts/generate-docker.mjs --profile=static --dry-run

💡 Tip: rikune.ps1, rikune.sh, and install-docker.ps1 run the generator automatically before Compose build. They discover all plugins, write the selected profile files, then build the selected service — no manual step needed. 💡 提示：rikune.ps1、rikune.sh 和 install-docker.ps1 会在 Compose 构建前自动运行生成器。它们发现所有插件、写入所选 profile 文件、然后构建所选服务 — 无需手动操作。

Adding Docker Support to a New Plugin为新插件添加 Docker 支持

If your plugin needs a system tool in the Docker image, just add the Docker fields to its systemDeps: 如果你的新插件需要 Docker 镜像中的系统工具，只需在其 systemDeps 中添加 Docker 字段：

systemDeps: [{
  type: 'binary',
  name: 'mytool',
  envVar: 'MYTOOL_PATH',
  dockerDefault: '/usr/bin/mytool',
  // Add these for Docker:
  dockerFeature: 'mytool',
  aptPackages: ['mytool'],
  dockerValidation: ['mytool --version'],
}]

Then add a corresponding # @if mytool block in docker/Dockerfile.template if it needs a dedicated build stage. For simple apt packages, just the aptPackages field is enough — they are automatically merged into the runtime stage. 然后如果需要独立构建阶段，在 docker/Dockerfile.template 中添加对应的 # @if mytool 块。对于简单的 apt 包，只需 aptPackages 字段即可 — 它们会自动合并到运行时阶段。

Services Overview服务概览

The analyzer container runs the control-plane services. When you configure a Windows Runtime Node or Host Agent, real sample execution is delegated over HTTP instead of happening inside the Linux analyzer container. analyzer 容器运行控制面服务。配置 Windows Runtime Node 或 Host Agent 后，真实样本执行会通过 HTTP 委派出去，而不是在 Linux analyzer 容器内进行。

/api/v1/health is a liveness check. /api/v1/ready is profile-aware readiness and checks only dependencies required by enabled plugins./api/v1/health 是进程存活检查；/api/v1/ready 是 profile-aware readiness，只检查当前启用插件真正需要的依赖。

Production Mode生产模式

# Recommended production default
.\rikune.ps1 install -Profile static -DataRoot "D:\Docker\rikune"

# Single Windows host hybrid
.\rikune.ps1 install -Profile hybrid -InstallRuntime

# Hybrid with Hyper-V VM runtime backend
.\rikune.ps1 install -Profile hybrid -InstallRuntime `
  -RuntimeBackend hyperv-vm `
  -HyperVVmName "rikune-runtime" `
  -HyperVSnapshotName "clean-runtime" `
  -HyperVRuntimeEndpoint "http://192.168.1.50:18081" `
  -HyperVRestoreOnRelease

# Linux analyzer + remote Windows Host Agent
./rikune.sh install --profile hybrid --windows-host <windows-host> --windows-user <windows-user>

Docker Compose

# Generate all profile files
npm run docker:generate:all

# Static-only Linux analyzer (safe default)
docker compose --env-file .docker-runtime.env -f docker-compose.analyzer.yml up -d --build analyzer

# Hybrid Linux analyzer + Windows runtime plane
docker compose --env-file .docker-runtime.env -f docker-compose.hybrid.yml up -d --build analyzer

# Full Linux toolchain image
docker compose --env-file .docker-runtime.env -f docker-compose.yml up -d --build mcp-server

# View analyzer logs
docker compose --env-file .docker-runtime.env -f docker-compose.hybrid.yml logs -f analyzer

# Stop the selected stack
docker compose --env-file .docker-runtime.env -f docker-compose.hybrid.yml down

Note: static and hybrid use the analyzer Dockerfile and exclude local dynamic execution dependencies. Use full only when you intentionally want the heavier all-in-one Linux toolchain image. 注意：static 和 hybrid 使用 analyzer Dockerfile，不在本地安装动态执行依赖。只有在明确需要更重的全量 Linux 工具链时才使用 full。

MCP Client ConfigurationMCP 客户端配置

Docker profiles run a long-lived analyzer container for the dashboard and HTTP API. MCP clients should start a separate stdio process inside that running container with docker exec -i. Docker profile 会先运行一个长期存在的 analyzer 容器，用于 Dashboard 和 HTTP API。 MCP 客户端应通过 docker exec -i 在这个已运行容器中启动独立的 stdio 进程。

JSON clientsJSON 客户端

{
  "mcpServers": {
    "rikune": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e", "API_ENABLED=false",
        "-e", "NODE_ENV=production",
        "-e", "PYTHONUNBUFFERED=1",
        "rikune-analyzer",
        "node",
        "dist/index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "PYTHONUNBUFFERED": "1"
      },
      "timeout": 300000
    }
  }
}

Codex

[mcp_servers.rikune]
command = "docker"
startup_timeout_sec = 180
args = [
  "exec",
  "-i",
  "-e", "API_ENABLED=false",
  "-e", "NODE_ENV=production",
  "-e", "PYTHONUNBUFFERED=1",
  "rikune-analyzer",
  "node",
  "dist/index.js"
]

[mcp_servers.rikune.env]
NODE_ENV = "production"
PYTHONUNBUFFERED = "1"

API_ENABLED=false only applies to the short-lived MCP stdio child process. The already running analyzer container still serves the dashboard at http://localhost:18080/dashboard. For the full profile, change the container name from rikune-analyzer to rikune. Keep startup_timeout_sec at 180 or higher because the Docker MCP child loads the plugin graph on startup. API_ENABLED=false 只作用于短生命周期的 MCP stdio 子进程。已经运行的 analyzer 容器仍然会在 http://localhost:18080/dashboard 提供 Dashboard。 如果使用 full profile，请把容器名从 rikune-analyzer 改为 rikune。请将 startup_timeout_sec 保持在 180 或更高，因为 Docker MCP 子进程启动时需要加载插件图。

Environment Variables环境变量

Web Dashboard

After starting the container, open your browser to: 容器启动后，在浏览器中访问：

http://localhost:18080/dashboard

The dashboard provides 6 tabs: Overview, Tools, Plugins, Samples, Config, and System, with SSE real-time event stream and auto-refresh. 看板提供 6 个选项卡：Overview、Tools、Plugins、Samples、Config 和 System，支持 SSE 实时事件流和自动刷新。

Bundled Toolchain内置工具链

The Docker image ships with all of these pre-installed: Docker 镜像预装了以下所有工具：

Troubleshooting故障排除

Build Problems构建问题

Runtime Issues运行时问题

MCP CommunicationMCP 通信

Ghidra AnalysisGhidra 分析