Full-Chain-Sentinel-System README

The project's README from github.com/zgsfsec/Full-Chain-Sentinel-System. As one markdown file: README.md.

全链哨兵 Full Chain Sentinel System

知攻善防实验室,基于 pi agent harness 改造的授权渗透测试 Agent,带中文 Web 控制台与容器化作业环境。

授权使用声明

本项目是攻击性安全工具,只能用于你已获得书面授权的目标。

本项目以 MIT 许可发布,不附带任何担保。

功能

快速开始

要求 Node.js >= 22.19.0。

npm install --ignore-scripts
npm run build:offline  # 后端各包与 coding-agent(不联网,模型目录已入库)
npm run build:web      # Web 控制台与前端资源
npm run start:web

npm run build 只构建后端各包,控制台需要额外的 npm run build:web。

启动后日志里会打印本次的入口地址,形如 http://<地址>:<端口>/<随机串>。默认监听 0.0.0.0,随机入口串与 cookie 校验用于挡扫描器:没有入口串的请求一律返回普通 404,入口串每次启动都变。请在日志里取完整地址访问。

首次访问的流程:

  1. 设置控制台密码(scrypt 哈希,保存在本机配置目录)。
  2. 阅读并勾选授权使用承诺。
  3. 在左侧「模型设置」配置端点(Base URL / API Key / 模型 ID)。

启动参数与环境变量:

参数 环境变量 说明
--host <地址> SENTINEL_HOST 监听地址,默认 0.0.0.0
--port <端口> SENTINEL_PORT 监听端口,默认 7777
--cwd <目录> SENTINEL_CWD 工作目录,默认当前目录
--gate-token <串> SENTINEL_GATE_TOKEN 固定入口串,默认每次启动随机
--no-gate — 关闭随机入口,直接以 / 提供服务(仅本机调试)
--no-consent — 跳过首次授权承诺(自动化环境)
--check — 只做启动前自检并打印报告,不启动服务

CLI 同样可用:

./pi-test.sh --no-env      # 从源码运行 sentinel CLI

目录结构

本仓库沿用上游 pi monorepo 的分包结构(包名仍是上游的 @earendil-works/*,改名单独进行):

包 说明
packages/web 全链哨兵 Web 控制台:HTTP + WebSocket 服务与前端
packages/coding-agent Agent CLI 与运行时
packages/agent 工具调用与状态管理
packages/ai 多 provider LLM API
packages/tui 终端 UI 库
packages/durable 会话、任务与文档运行时
packages/mcp · packages/protocol MCP 与协议层
packages/droid-apk 安卓 DroidBridge APK(Kotlin)
docker 作业容器镜像(Kali + 工具链)

开发

./test.sh                   # 全部非 e2e 测试
npm run check               # biome + 依赖/导入/入口图检查 + tsc + webui + 浏览器冒烟
npm run build:offline       # 全量构建,不联网、不重生成模型目录

本仓库不跑 CI(只保留发布流程):提交前请自己跑 npm run check 和 ./test.sh。

单测从包根目录跑:

node "$(git rev-parse --show-toplevel)/node_modules/vitest/dist/cli.js" --run test/<name>.test.ts

packages/ai/src/providers/data/ 是 generate-models 的产物,已固定在版本库里:模型 id 的类型联合体直接由它推导,固定它之后 tsc 和测试不会随厂商轮换模型而漂移(全新克隆也能离线做类型检查)。要更新目录时跑 npm run generate:models(需联网)并提交改动——刷新会改到 .manifest.json 的 generatedAt 时间戳,属正常。发布流程仍会实时刷新,发布产物里的目录是最新的。

作业容器:

docker build -t sentinel:latest docker/

基础镜像与 apt/pip/npm/go 软件源可在控制台「设置 → 环境」配置,也可以在命令行用 --build-arg 覆盖。

安全边界

控制台:Docker 是硬依赖。每个项目一个 Kali 容器(sentinel:latest),Agent 的 bash 命令在容器内执行(docker exec),项目目录 bind mount 进 /work,容器以 root 运行。容器网络默认 host(容器直接用宿主机网络栈,反向 shell、payload 服务、本地靶场、内网与 VPN 才是真实的),可在「设置 → 环境 → 容器网络」切到 bridge;两种模式都保留 NET_RAW,NET_ADMIN 只在 bridge 模式授予。Docker 检查有阻断项时控制台拒绝 prompt、compact 与持续目标。

但容器只约束命令,不是整体沙箱:控制台与 Agent 进程本身以启动者的用户身份跑在宿主机上,只有命令进容器。

完整边界与配置见 packages/web/README.md。

CLI:沿用 pi 的权限模型,无内建沙箱,工具以当前用户权限在宿主机执行;需要隔离就把 CLI 整个跑进容器(containerization.md 是上游文档,命令与路径名仍是 pi)。

自动执行模式下模型可运行任意命令,持续目标在自动执行下也没有危险命令黑名单,请仅在授权目标与隔离环境中使用;需要无人值守又不愿全放行时用 AI 审批。控制台的登录、随机入口串与授权承诺只用于防误用与防扫描,不构成隔离。

安全问题请通过仓库 Issue 反馈,不要在公开 Issue 里附可直接利用的细节。

上游与许可

本项目是 pi 的衍生作品(fork),不是上游官方项目,与上游团队无关。

上游代码以 MIT 许可发布,版权归 Mario Zechner,许可全文见 LICENSE;本仓库保留该许可与版权声明,并在此基础上加入渗透测试相关的系统提示、Web 控制台、容器化作业环境与安卓设备插件。

何为全链路?

渗透测试场景在安全服务工作中,通常分为三种 1.Web 渗透 2.微信小程序渗透 3.APP 渗透 至此,我们全链路打通,一个平台畅游所有任务 三端是怎么打通的呢? 我们要知道我们渗透测试测的是什么?很多人都不明白道理,我们渗透测试过程,90% 的针对服务器后端进行测试的,后端想给我们前端展示,所以想打通三端也只是不同载体的问题。 比如 Web 前端载体就是浏览器, 微信小程序的前端载体就是微信小程序容器 APP 的前端载体就是一些 UI 框架 所以,本质上 Web、小程序、APP,都是一样的。

使用

image

简单说几个场景怎么用吧, 1.Web 测试 直接输入框使用即可 2.微信小程序 选择预设 Agent 然后自己在 Tscan 这类工具中把微信小程序反编译,点击左下角“附件”上传即可。 3.APP 在左侧安卓设备中配置好你的安卓机器,然后在你的安卓里面安装好对应 APP,然后在对话框中选择“安卓”即可 因为本人想法是更少的工具和上下文,所以,你如果不开“安卓”这个按钮的话,他是不会插入安卓相关的工具调用的、也不会插入相关 prompt

关于安卓配置

你需要有一台 root 后的设备(虚拟机亦可),并且安装配套的 app 即可

image

关于手机 root,这里就不再讲解,有兴趣可以去酷安社区逛逛,安卓机为反连主平台,所以你可以将主程序部署在公网服务器。

image

工程模式

适用于批量测试环节,指挥官架构,适用于多任务指挥,这个还是测试阶段,自行玩一玩吧。

image

守门审计

建议在设置->模型里面再配置一个小模型,比如 qwen,Hook所有 Bash 调用过程,建议用千问的 API 按量付费,不可以用 CodingPlan 模型,因为 CodingPlan 会有速率限制。

https://www.qianwenai.com/models/qwen-flash

采用小模型监管大模型,最大程度上尽量避免对生产环境造成影响。

image

关于 POC 订阅

你可以做一些自己的 Nuclei 的 POC 订阅服务,放进“设置->POC订阅”里面,这种应用场景主要是打 nday ,本来没打算加 Nuclei 固定 POC 的功能的,但是考虑到像 jeecg boot 、若依这种开发框架,的 api 路由自定义功能,还是加了吧。

你只需要在你的远程服务器上定时的把Nuclei 的所有 POC 打包成 zip,然后远程同步即可。

也可以直接同步 Nuclei 官方的 POC

image

全链哨兵交流群

加群的,一定要在“打招呼内容”备注“全链哨兵”。

image image

Full-Chain-Sentinel-System (zgsfsec/Full-Chain-Sentinel-System)

penetration-testing
Searching Database…

What is this?Full Chain Sentinel is an authorized penetration-testing agent system, forked from the 'pi' coding-agent harness, that adds a Chinese-language web console and a per-project containerized job environment to run the full recon-to-report attack workflow.
Is this a library I import, or a standalone app I run?It is a standalone self-hosted application — a Node.js monorepo fork of the 'pi' harness with its own web console and per-project Kali containers — not a library you import into other code.
How do I get it running?Install Node.js >= 22.19.0, run 'npm run build' for the backend packages, and 'npm run build:web' for the console. On first access you set a console password, accept the authorized-use consent, then configure your model endpoint.
Do I need Docker to run this?Yes — Docker is a hard dependency; every project gets its own Kali container (sentinel:latest) in which the agent's bash commands are executed via docker exec.
Is it safe to just point this at any target?No — this is an offensive tool for targets you already have written authorization to test; unauthorized scanning or exploitation is illegal in China and most jurisdictions. In auto-execute mode the model can run any command, and even AI-gatekeeper mode fails open (allows the command) if its judgment fails or times out.
Is the Docker container a full sandbox?No. Only bash and Android-shell commands actually go through the container; file read/edit/write, MCP tools, frida, packet capture, and APK analysis call the host directly, and the container itself runs as root with no resource limits or seccomp.
What does the AI gatekeeper (守门员) actually check?A separate, smaller model (e.g. Qwen) reviews each bash command and decides ALLOW or BLOCK before it runs, meant to catch the primary model's risky actions — but it fails open (allows the command) if it can't parse a verdict or times out.
Can I feed it my own vulnerability feed?Yes — the POC subscription feature lets you point it at a zip of Nuclei POCs hosted on your own server (or sync the official Nuclei feed) for testing against known n-day vulnerabilities.
What does the Android plugin give me?It pairs with a self-made DroidBridge APK installed on a rooted test device to provide a reverse-connected shell, file transfer, screenshots, logcat, tcpdump packet capture, frida dynamic instrumentation, and static APK analysis from the console.
Creator
zgsfsec
Size
32.3 MB
Stars
259
Age
4d
Commits · 90 Days