LingXi

  ██╗     ██╗███╗   ██╗ ██████╗       ██╗  ██╗██╗
  ██║     ██║████╗  ██║██╔════╝       ╚██╗██╔╝██║
  ██║     ██║██╔██╗ ██║██║  ███╗█████╗ ╚███╔╝ ██║
  ██║     ██║██║╚██╗██║██║   ██║╚════╝ ██╔██╗ ██║
  ███████╗██║██║ ╚████║╚██████╔╝      ██╔╝ ██╗██║
  ╚══════╝╚═╝╚═╝  ╚═══╝ ╚═════╝       ╚═╝  ╚═╝╚═╝

📋 目录

• 项目简介
• 系统架构
• 核心特性
• 运行模式
• 项目结构
• 快速开始
• 关键配置项
• 各大 CTF WP 知识库
• 扩展能力说明
• Web Dashboard
• 部署建议
• 验证建议
• 参考项目与致谢
• 许可证

项目简介

LingXi 是一个源自腾讯安全 Hackathon 比赛项目的自主渗透测试 Agent。它围绕“自动拉题 / 侦察 / 工具执行 / 策略纠偏 / Flag 提交 / 经验沉淀”的闭环设计，当前仓库保留了核心架构：

• 主入口与调度流程
• Agent 编排与提示词体系
• Web Dashboard
• 记忆 / 知识抽象层
• LLM Provider 适配
• Docker/Kali 基础运行层
• ctf_writeups_kb 代码与测试

当前仓库聚焦可复用核心能力，并遵循“核心开源 + 扩展私有”的边界：

• 保留 LingXi 名称与腾讯比赛项目背景
• 不保留历史 Git 记录
• 不附带论坛官方工具包、私有 PoC、Sliver 资产、运行日志、数据库、抓取归档或知识库快照
• 缺失这些本地扩展时，核心路径默认以“待命模式 + 可观察 + 可开发 + 可测试”的方式工作

当前默认主执行链路已经演进为 agent/sdk_runner.py 中的 SDK Runner 体系，因此本文档也以这一现状描述架构与运行方式。

🏗️ 系统架构

LingXi 延续 Planner / Executor / Reflector 的认知分层，但当前仓库更适合从“入口层 → 调度层 → 解题执行层 → 工具/MCP 层 → 记忆知识层 → 可观察层”来理解：

┌──────────────────────────────────────────────────────────────────────────────┐
│                               LingXi Architecture                            │
├──────────────────────────────────────────────────────────────────────────────┤
│  入口层                                                                      │
│  main.py / config.py / runtime_env.py / .env                                │
│  CLI: default / --main / --all / --web / --*-only                           │
├──────────────────────────────────────────────────────────────────────────────┤
│  调度层                                                                      │
│  agent/scheduler.py / background workers / instance lifecycle               │
│                                                                              │
│  ┌─────────────────────┬──────────────────────┬───────────────────────────┐ │
│  │ Platform Runtime    │ Optional Extensions  │ Async Workers             │ │
│  │ task dispatch       │ forum / sliver / poc │ knowledge writeback       │ │
│  │ instance lifecycle  │ loaded only if local │ memory sync               │ │
│  └──────────┬──────────┴──────────┬───────────┴──────────────┬────────────┘ │
│             │                     │                          │              │
├─────────────▼─────────────────────▼──────────────────────────▼──────────────┤
│  解题 / 执行层                                                               │
│  agent/sdk_runner.py / agent/prompts.py / agent/reflector.py                │
│  main agent / advisor / reflector / tool guard                              │
├──────────────────────────────────────────────────────────────────────────────┤
│  工具 / MCP 层                                                                │
│  tools/shell.py / python_exec.py / platform_api.py / forum_api.py           │
│  recon / kali_mcp / sliver_mcp / level2_cve_poc / mcp bridge               │
├──────────────────────────────────────────────────────────────────────────────┤
│  记忆 / 知识层                                                                │
│  memory/store.py / knowledge_store.py / knowledge_gateway.py                │
│  knowledge_service.py / ctf_writeups_kb/                                    │
├──────────────────────────────────────────────────────────────────────────────┤
│  可观察层                                                                      │
│  Rich Console / Web Dashboard / SSE / log file / reports                    │
└──────────────────────────────────────────────────────────────────────────────┘

双 Agent 协作模型

✨ 核心特性

🎯 智能执行能力

• 自动化主链路：拉题、侦察、执行、提交、复盘形成闭环
• 多模式运行：支持主战场、双开、仅 Web、仅独立子模式
• 自动侦察：端口、HTTP 指纹、页面上下文、错误回显等基础线索提纯
• 多执行手段协同：Shell、Python、Kali、平台 API、可选 MCP 扩展
• 进度感知：支持基于分数/Flag 状态做任务级收敛

🧠 分层知识系统

• 运行记忆层：同题 / 同 scope 的热路径回放
• 结构化经验层：高价值成功链路与失败归因写回
• 外部知识层：ctf_writeups_kb/ 提供可控检索与 API 服务
• 门控策略：本地经验优先于外部参考

🛡️ 鲁棒性

• Flag 快路径提交
• 危险 Shell / Python 行为约束
• 重复低价值路径拦截
• API 退避与恢复
• 写回线程安全
• 缺少私有扩展时优雅降级

📊 可观察性

• Rich Console
• FastAPI + SSE Web Dashboard
• 知识中心页面
• 调度状态、日志轨迹、任务控制可视化

🔄 Provider 与容灾

• 支持多 Provider 角色拆分
• 主攻手 / 顾问链路隔离
• 支持备用端点切换
• 支持可选论坛独立模型链路

运行模式

主入口是根目录的 main.py：

python main.py

支持以下模式：

说明：

• 未配置 COMPETITION_BASE_URL / COMPETITION_API_BASE_URL 时，程序会进入待命模式
• 待命模式下 Dashboard 依然可用，适合本地开发、配置校验与文档化演示
• 论坛、PoC、Sliver 等路径默认关闭，只有你本地挂接扩展后才会启用

📦 项目结构

LingXi/
├── main.py                    # 🚀 主入口
├── config.py                  # ⚙️ 全局配置管理
├── runtime_env.py             # 🐍 Python 解释器与 .venv 统一解析
├── start_daemon.sh            # 🕒 后台守护启动脚本
├── requirements.txt           # 📦 运行依赖
├── .env.example               # 🔑 公共配置模板
├── README.md                  # 📖 本文档
│
├── agent/                     # 🧠 Agent 核心
│   ├── scheduler.py           #   调度与实例生命周期
│   ├── sdk_runner.py          #   当前默认执行层
│   ├── prompts.py             #   系统提示词
│   ├── reflector.py           #   失败归因与反思
│   ├── skills.py              #   技能与扩展装配
│   └── console.py             #   Rich 输出
│
├── tools/                     # 🔧 工具层
│   ├── shell.py               #   Shell 执行器
│   ├── python_exec.py         #   Python 执行器
│   ├── platform_api.py        #   平台 API 客户端
│   ├── forum_api.py           #   论坛扩展桥接
│   ├── level2_cve_poc.py      #   本地 PoC 扩展桥接
│   ├── kali_mcp.py            #   Kali MCP 桥接
│   ├── sliver_mcp.py          #   Sliver MCP 桥接
│   └── recon.py               #   自动侦察
│
├── llm/                       # 🤖 LLM Provider 适配
├── memory/                    # 💾 记忆与知识系统
├── web/                       # 🌐 Web Dashboard
├── ctf_writeups_kb/           # 📚 CTF Writeup 检索子项目
├── docker/                    # 🐳 Kali 容器与执行环境
├── tests/                     # ✅ 主项目测试
│
├── extensions/                # 🧩 本地可选扩展挂载点（仓库默认不附带私有实现）
│   ├── forum/                 #   论坛扩展
│   ├── level2-pocs/           #   私有 PoC 扩展
│   ├── skills/                #   本地技能目录
│   └── additional-skills/     #   额外技能目录
│
├── SECURITY.md                # 🔒 安全说明
└── CONTRIBUTING.md            # 🤝 贡献说明

快速开始

1. 环境准备

建议环境：

• Python 3.11+
• Docker / Docker Desktop（可选但推荐）
• 可运行 Kali 容器的本地或服务器环境（可选）

安装依赖：

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Windows PowerShell：

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

说明：

• 文档默认推荐 python venv，这是对外安装与测试的标准路径
• 维护者本地可以使用 uv 做加速，但这不是默认前置条件
• requirements.txt 已包含 mcp 依赖；即使没有本地扩展，实现层也能正常导入并保持默认关闭

2. 依赖说明

建议把依赖拆成“核心必需”和“本地可选扩展”两层理解：

3. 配置环境变量

复制模板：

cp .env.example .env

最小可运行配置示例：

# 平台地址留空时进入待命模式
COMPETITION_BASE_URL=
COMPETITION_API_BASE_URL=

AGENT_TOKEN=replace-with-agent-token

MAIN_LLM_PROVIDER=openai
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=replace-with-openai-key
OPENAI_MODEL=gpt-4o-mini

ADVISOR_LLM_PROVIDER=anthropic
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_API_KEY=replace-with-anthropic-key
ANTHROPIC_MODEL=claude-3-5-sonnet-latest

DOCKER_ENABLED=true
FORUM_ENABLED=false
SLIVER_ENABLED=false
SLIVER_AUTO_ENABLE_IF_PRESENT=false

4. 启动 Docker / Kali（可选）

如果你希望启用 Docker/Kali 工作流：

cd docker
docker compose up -d

如果你只想验证主程序、Web、记忆和知识层，这一步可以暂时跳过。

5. 启动 LingXi

# 待命模式 + Web
python main.py --web --port 7890

# 默认主链路
python main.py

# 独立 Web
python main.py --web-only --port 7890

关键配置项

下面这些变量最常用：

更完整的配置请看：

• 根项目配置模板：./.env.example
• 知识库子模块说明：./ctf_writeups_kb/README.md

各大 CTF WP 知识库

ctf_writeups_kb/ 是当前仓库保留的外部知识库子项目，职责是：

• 采集和整理可公开来源的 CTF Writeup
• 构建 embedding / 检索 / 轻量索引链路
• 提供 CLI / HTTP API 两种访问方式
• 为顾问链路提供受控外部参考

典型数据流：

公开来源 / 来源清单 / manifest
        ↓
writeups_raw.jsonl（本地生成）
        ↓
normalize / dedupe / chunk
        ↓
writeups_index.jsonl（本地生成）
        ↓
Milvus Lite / Qdrant（本地生成）
        ↓
KnowledgeService / Gateway
        ↓
Advisor / API / CLI

注意：

• 当前仓库只附带代码、测试和 data/source_library_cn.json
• writeups_raw.jsonl、writeups_index.jsonl、milvus.db、qdrant/ 都是本地生成产物
• 不会随公共仓库一起发布

扩展能力说明

当前仓库保留扩展接口，但不附带私有实现。主要包括：

1. Docker / Kali

• 仓库保留 docker/、kali_container.py、tools/kali_mcp.py
• 适用于本地 Kali 容器中的工具执行与受控工作流
• 没有 Docker 时不影响待命模式、Dashboard、记忆和知识层

2. MCP

• requirements.txt 已包含 mcp
• tools/forum_api.py、tools/sliver_mcp.py、tools/kali_mcp.py 仍保留桥接层
• 如果没有本地扩展或目标服务，桥接层默认不会强制启用

3. 技能目录

当前仓库支持本地挂接以下技能/扩展目录：

• extensions/skills/
• extensions/additional-skills/
• extensions/forum/
• extensions/level2-pocs/

说明：

• 这些目录在仓库中默认不存在或为空
• 如果你在本地有私有技能包或专项扩展，可以自行挂接
• 不应把这些私有扩展再提交回当前 GitHub 仓库

4. 论坛 / PoC / Sliver

• 论坛赛道能力在当前仓库中表现为“可选论坛扩展”
• Level2/专项 PoC 能力在当前仓库中表现为“本地 PoC 扩展”
• Sliver 能力在当前仓库中表现为“可选控制面扩展”
• 三者默认关闭，缺失时不应阻断基础运行

Web Dashboard

Web 面板是可选组件，不是主链路必需。

启动方式：

python main.py --web
python main.py --web --port 7890
python main.py --web-only --port 7890

主要用途：

• 观察任务、赛区状态和调度结果
• 查看实时日志流与执行轨迹
• 手动创建 / 暂停 / 恢复 / 中止任务
• 浏览记忆与知识中心

部署建议

方式一：直接运行

git clone https://github.com/adrian803/LingXi.git
cd LingXi
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env
python main.py --web

方式二：带 Docker/Kali 运行

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
docker compose -f docker/docker-compose.yml up -d
python main.py --web

方式三：后台守护

bash start_daemon.sh --web
bash start_daemon.sh --status
bash start_daemon.sh --logs

说明：

• 当前仓库不附带比赛环境专用部署脚本
• 建议先跑通 venv + 待命模式 + Dashboard
• 之后再按需补 Docker/Kali、MCP、技能目录或私有扩展

验证建议

上线前建议至少做这些检查：

python -m py_compile main.py agent/sdk_runner.py agent/skills.py tools/forum_api.py tools/level2_cve_poc.py web/server.py
python -m unittest tests.test_memory_knowledge
python -m unittest tests.test_forum_host_fallback
python -m unittest tests.test_level2_poc_tool
python -m unittest ctf_writeups_kb.tests.test_api_search

本文档默认仍然使用 python venv 作为安装与测试方式；维护者本地可以使用 uv 做开发加速，但不把 uv 作为默认前提。

参考项目与致谢

LingXi 的实现参考了以下项目或技术栈：

• Claude Code SDK
• LangChain
• FastAPI
• Rich
• MCP
• pymilvus / Qdrant

许可证

本仓库采用 GPL-3.0-only。