abhi-vmlinuz/nexus-oss
GitHub: abhi-vmlinuz/nexus-oss
自托管的可扩展临时环境编排平台，用于 CTF 和网络安全实验室，通过 K3s 和 WireGuard 为每位选手提供隔离的容器化挑战实例。
Stars: 0 | Forks: 0
# Nexus OSS
[](LICENSE)
[](https://golang.org)
[](https://www.rust-lang.org)
## 目录
- [概述](#overview)
- [架构](#architecture)
- [组件](#components)
- [前置条件](#prerequisites)
- [安装说明](#installation)
- [配置说明](#configuration)
- [CLI 参考](#cli-reference)
- [卸载](#uninstalling)
- [项目结构](#project-structure)
- [开发指南](#development)
## 概述
Nexus OSS 是一个控制平面，用于在裸机或自托管虚拟机上运行容器化的 CTF (Capture The Flag) 挑战。它通过轻量级的 K3s + nerdctl 技术栈替代了昂贵的云端编排方案，并提供以下功能：
- 通过 WireGuard VPN 和 `ipset`/`iptables` 网络策略实现 **多租户隔离**
- **临时挑战实例** — 每个玩家会话都会获得自己独立的隔离容器
- **运维端 CLI** 带有实时 TUI 仪表板，可实时监控会话
- **插件注册中心** — 可使用本地注册中心，或通过 Docker Hub / GHCR 进行身份验证
- **`dev` 和 `prod` 模式** 分别用于本地测试和加固的生产环境部署
## 架构
```
┌─────────────────────────────────────────┐
│ Operator (you) │
│ nexus tui / nexus CLI │
└────────────────┬────────────────────────┘
│ HTTP REST
┌────────────────▼─────────────────────────┐
│ nexus-engine │
│ Gin · Redis State · K3s Controller │
└───────┬──────────────┬───────────────────┘
│ gRPC │ Kubernetes API
┌──────────────▼────┐ ┌─────▼─────────────────┐
│ nexus-node-agent │ │ k3s │
│ (Rust, privd) │ │ nexus-challenges NS │
│ ipset · WireGuard│ │ Challenge Pods/Svcs │
└───────────────────┘ └───────────────────────┘
│
┌──────────────▼───────────┐
│ Container Registry │
│ local:5000 / GHCR / Hub │
└──────────────────────────┘
```
## 组件
| 组件 | 语言 | 职责 |
|---|---|---|
| **nexus-engine** | Go (Gin) | 中央 REST API，会话生命周期，K3s 协调 |
| **nexus-cli** | Go (Cobra + Bubbletea) | 运维端 CLI 和实时 TUI 仪表板 |
| **nexus-node-agent** | Rust (Tonic/gRPC) | 特权守护进程 — 管理 `ipset`，`iptables`，WireGuard |
| **nexus-installer** | Go (Bubbletea TUI) | 交互式全屏安装向导 |
### nexus-engine
核心 API 服务器。它管理着完整的挑战会话生命周期：
- 为每个玩家会话创建/销毁 K3s Pod
- 在 Redis 中追踪会话状态（基于 TTL 的清理）
- 通过 gRPC 与 `nexus-node-agent` 通信以配置网络
- 暴露 REST API 供 CLI 和外部平台（如 CTFd）调用
### nexus-cli
运维控制台。提供以下功能：
- `nexus tui` — 实时更新的终端仪表板，用于监控会话
- `nexus challenge` — 创建、列出和删除挑战定义
- `nexus session` — 检查和终止玩家会话
- `nexus status` — 对引擎进行健康检查
- `nexus config` — 查看和验证本地配置
### nexus-node-agent
一个特权 Rust 守护进程，与引擎一同运行在每个节点上。它负责处理所有需要 `CAP_NET_ADMIN` 权限的内核级网络操作：
- 用于基于 VPN 隔离的 WireGuard 节点管理
- 每个会话的 `ipset`/`iptables` 规则执行
- 通过非加密的 gRPC 套接字（仅限本地）接受来自 `nexus-engine` 的命令
### nexus-installer
一个使用 Go 和 Bubbletea 编写的全屏 TUI 安装程序。它取代了旧版的 `deploy/setup.sh`，提供交互式、针对不同发行版适配的安装体验，可自动完成全部 9 个阶段的引导操作。
## 前置条件
| 依赖项 | 最低版本 | 备注 |
|---|---|---|
| Linux x86_64 | Kernel 5.6+ | WireGuard 需要 5.6 及以上版本；CachyOS/Fedora 内核表现良好 |
| Go | 1.21+ | 用于构建 `nexus-engine` 和 `nexus-cli` |
| Rust + Cargo | 1.70+ | 用于构建 `nexus-node-agent` |
| `git` | 任意 | 用于克隆仓库 |
| `curl` | 任意 | K3s 安装程序使用 |
| `sudo` | 任意 | 用于系统级操作 |
## 安装说明
### 一键引导安装 (推荐)
只需使用一条命令即可在任何受支持的 Linux 发行版上安装 Nexus OSS：
```
curl -fSL https://raw.githubusercontent.com/abhi-vmlinuz/nexus-oss/main/bootstrap.sh | bash
```
### 手动安装
如果您希望先审查代码或手动克隆：
```
git clone https://github.com/abhi-vmlinuz/nexus-oss.git
cd nexus-oss
chmod +x build-installer.sh
./build-installer.sh
```
### 安装程序执行流程 (9 个阶段)
| 阶段 | 描述 |
|---|---|
| 0 | 验证 `sudo` 凭据，在 `/var/log/nexus-install.log` 初始化安装日志 |
| 1 | 检测发行版，安装系统软件包（`curl`，`jq`，`wireguard`，`golang`，`rust` 等） |
| 2 | 以独立模式安装 K3s（禁用 Traefik），创建 `nexus-challenges` 命名空间 |
| 3 | 安装 `nerdctl` + containerd，配置 `nexus` 用户组和套接字权限 |
| 4 | 设置容器注册中心（本地 `:5000` 或通过 GHCR/Docker Hub 进行身份验证） |
| 5 | 部署 Redis（Docker 容器或宿主机服务） |
| 6 | 在 `wg0` 上配置 WireGuard VPN 服务器（仅限 `prod` 模式） |
| 7 | 从源码构建并安装 `nexus-engine`，`nexus` (CLI) 和 `nexus-node-agent` |
| 8 | 将配置写入 `~/.config/nexus/config.json` |
| 9 | 生成并启用 systemd 单元文件，启动所有服务 |
### 支持的发行版
| 发行版家族 | 包管理器 | 状态 |
|---|---|---|
| Debian / Ubuntu | `apt` | ✅ 支持 |
| Fedora / RHEL / CentOS | `dnf` / `yum` | ✅ 支持（兼容 SELinux） |
| Arch Linux / Manjaro | `pacman` | ✅ 支持 |
| openSUSE | `zypper` | ✅ 支持 |
## 配置说明
安装完成后，配置文件存储在 `~/.config/nexus/config.json` 中（权限模式为 `0600`）。
```
{
"engine": {
"url": "http://localhost:8081",
"mode": "dev"
},
"registry": {
"type": "local",
"url": "localhost:5000",
"auth": {
"type": "none",
"username": "",
"password": ""
}
},
"redis": {
"url": "redis://localhost:6379"
},
"node_agent": {
"addr": "localhost:50051"
},
"k8s": {
"namespace": "nexus-challenges"
}
}
```
### 环境变量覆盖
所有配置值均可通过环境变量覆盖：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `NEXUS_MODE` | `dev` | `dev` 或 `prod` |
| `NEXUS_PORT` | `8081` | 引擎监听端口 |
| `NEXUS_REDIS_URL` | `redis://localhost:6379` | Redis 连接字符串 |
| `NEXUS_REGISTRY_URL` | `localhost:5000` | 容器注册中心 URL |
| `NEXUS_NODE_AGENT_ADDR` | `localhost:50051` | 节点代理 gRPC 地址 |
| `NEXUS_K3S_NAMESPACE` | `nexus-challenges` | Kubernetes 命名空间 |
| `NEXUS_ENGINE_URL` | `http://localhost:8081` | CLI 连接引擎使用的 URL |
| `KUBECONFIG` | `/etc/rancher/k3s/k3s.yaml` | K3s kubeconfig 路径 |
### 模式
**`dev` 模式**（默认）：
- WireGuard VPN 被 **禁用**
- 服务运行在没有严格网络隔离的环境下
- 适合本地开发和测试
**`prod` 模式**：
- 在 `wg0` 上启用 WireGuard VPN（`10.8.0.1/24`，端口 `51820`）
- 每个会话强制执行 `ipset`/`iptables` 规则
- Systemd 服务以 `CAP_NET_ADMIN` 权能运行
## CLI 参考
```
nexus [command]
Available Commands:
challenge Manage CTF challenge definitions
session Inspect and manage player sessions
compose Deploy multi-container challenge stacks
config Show or update Nexus configuration
status Health check against the engine
tui Open the live TUI dashboard
Global Flags:
--engine string Override the Nexus engine URL
```
### 示例
```
# 检查 engine 和 redis 的健康状况
nexus status
# 打开实时 operator 控制台
nexus tui
# 列出所有已部署的 challenges
nexus challenge list
# 从 docker-compose 文件创建新的 challenge
nexus compose up ./testing/pwn-101/docker-compose.yml
# 查看当前配置
nexus config view
# 验证连通性
nexus config validate
```
### Shell 补全
Nexus CLI 支持针对 Bash、Zsh、Fish 和 PowerShell 的 Tab 键补全。要为当前会话启用此功能：
```
# Bash
source <(nexus completion bash)
# Zsh
source <(nexus completion zsh)
# Fish
nexus completion fish | source
```
要使其永久生效，请将相应的命令添加到您的 Shell 配置文件中（如 `~/.bashrc` 或 `~/.zshrc`）。
## 卸载
运行卸载脚本以干净地移除所有 Nexus 组件：
```
sudo ./deploy/uninstaller.sh
```
卸载程序将移除：
- **Systemd 服务**：`nexus-engine`，`nexus-node-agent`，`nexus-socket-fix`
- **二进制文件**：`/usr/local/bin/nexus`，`/usr/local/bin/nexus-engine`，`/usr/local/bin/nexus-node-agent`
- **配置文件**：`~/.config/nexus/`
- **容器**：`nexus-redis`，`nexus-registry`（通过 nerdctl 移除）
- **WireGuard**：`wg0` 接口和 `/etc/wireguard/wg0.conf`
## 项目结构
```
nexus-oss/
├── build-installer.sh # Bootstrap: build, run, and cleanup the installer
├── deploy/
│ ├── setup.sh # Legacy bash installer (superseded by TUI)
│ ├── uninstaller.sh # Full system cleanup script
│ ├── network-policy-dev.yaml # K3s network policy (dev)
│ └── network-policy-prod.yaml# K3s network policy (prod)
├── nexus-engine/ # Go — Core REST API server
│ ├── cmd/main.go # Entry point
│ └── internal/
│ ├── api/ # Gin HTTP handlers
│ ├── controller/ # Session reconciliation loop
│ ├── k8s/ # K3s/Kubernetes client
│ ├── nodeagent/ # gRPC client for nexus-node-agent
│ ├── registry/ # Container registry interaction
│ ├── state/ # Redis state management
│ └── config/ # Environment-based configuration loader
├── nexus-cli/ # Go — Operator CLI (Cobra + Bubbletea)
│ ├── main.go
│ ├── cmd/ # Cobra subcommands
│ ├── client/ # HTTP client for nexus-engine
│ ├── tui/ # Live Bubbletea TUI dashboard
│ └── config/ # Config loader with env fallback
├── nexus-node-agent/ # Rust — Privileged network daemon (Tonic gRPC)
│ ├── src/
│ │ ├── main.rs
│ │ ├── server.rs # gRPC server implementation
│ │ ├── config.rs # Config from environment
│ │ └── adapters/ # ipset, iptables, WireGuard adapters
│ └── Cargo.toml
├── nexus-installer/ # Go — Interactive TUI installer (Bubbletea)
│ ├── main.go # Bubbletea program entry + Update loop
│ ├── model.go # Shared application state model
│ ├── pages.go # TUI page renderers
│ ├── styles.go # Lipgloss design system
│ └── internal/
│ ├── installer.go # 9-phase installation logic
│ └── exec.go # Shell command runner with logging
├── docs/
│ ├── architecture.md
│ ├── api.md
│ └── quickstart.md
├── scripts/
│ └── smoke_test.sh # Post-install smoke test
└── testing/
├── pwn-101/ # Example single-container challenge
└── multi-pwn/ # Example multi-container challenge stack
```
## 开发指南
### 构建单个组件
```
# 构建 nexus-engine
cd nexus-engine && go build -o nexus-engine ./cmd
# 构建 nexus-cli
cd nexus-cli && go build -o nexus .
# 构建 nexus-node-agent (Rust)
cd nexus-node-agent && cargo build --release
# 构建 nexus-installer TUI
cd nexus-installer && go build -o nexus-installer *.go
```
### 以开发模式运行
```
# 1. 启动 Redis
nerdctl run -d --name nexus-redis -p 6379:6379 redis:7-alpine
# 2. 启动 engine (开发模式使用 config.json 中的默认值)
nexus-engine
# 3. 在另一个终端中，验证
nexus status
nexus tui
```
### 冒烟测试
全新安装完成后，运行内置的冒烟测试以验证所有服务是否可达：
```
chmod +x scripts/smoke_test.sh
./scripts/smoke_test.sh
```
### 安装日志
所有安装程序的输出都会被永久记录在以下位置：
```
/var/log/nexus-install.log
```
## 🛠️ 故障排除
遇到了服务权限、SELinux 或本地回环连接问题？
请查阅我们的 [调试指南](DEBUGGING.md) 以获取常见安装难题的解决方案。
## 许可证
Apache 2.0 — 详情请参见 [LICENSE](LICENSE)。
标签：CISA项目, Docker, EVTX分析, Go, iptables, JSONLines, K3s, Nexus, OPA, Ruby工具, Rust, Web报告查看器, WireGuard, 临时环境, 可视化界面, 多租户隔离, 安全实验室, 安全防御评估, 容器编排, 开源, 控制平面, 搜索引擎查询, 日志审计, 编排器, 网络安全, 网络安全实训, 网络流量审计, 网络策略, 虚拟化, 轻量级虚拟机, 隐私保护, 零信任, 靶场