0xsimaa/Stealth_Pi

# StealthPi **StealthPi** 是一个便携式的双应用网络评估系统，作为在 **国家 CERT，伊斯兰堡** — 渗透测试与研究部门的实习项目而开发。 所有扫描**仅**在明确的书面授权范围内，针对授权网络和实验室目标执行。这是一个受监督的、合法的安全评估工具 — **严禁用于未经授权的用途**。 ## 架构 StealthPi 由两个完全解耦的 Python Flask 应用程序组成，它们**仅**通过 REST API 进行通信： | 应用程序 | 主机 | 职责 | |---|---|---| | **Scanner App** (`scanner_app/`) | Ubuntu Server 24.04 / Raspberry Pi 5 | 主动网络交互：Scapy 发现、DPI、PCAP 捕获、Web 爬取/镜像/测试、本地 SQLite、REST API | | **Dashboard App** (`dashboard_app/`) | 操作员工作站 | 扫描后分析：从 Scanner 同步、SHA-256 校验、警报、PCAP 汇总、Ollama/Mistral 报告、服务器渲染的 UI | Scanner App 对 Dashboard 是否在线有**零依赖**。Dashboard **绝不**直接写入 Scanner 数据库。 ``` ┌─────────────────────┐ REST API ┌──────────────────────┐ │ Scanner App │ ◄────────────────────── │ Dashboard App │ │ (Pi / VM) │ Bearer token auth │ (Operator PC) │ │ │ PCAP + scan records │ │ │ Scapy · SQLite │ │ pyshark · Ollama │ │ PCAPManager │ │ Jinja2 UI │ └─────────────────────┘ └──────────────────────┘ ``` ## Scanner App — 当前状态 | 阶段 | 模块 | 状态 | |---|---|---| | 1 | `config.py`, `database.py`, `auth.py`, `app.py` | 完成 | | 2 | `scan_engine.py` — ARP 主机发现 | 完成 | | 3 | `scan_engine.py` — 端口扫描，`dpi_module.py` | 完成 | | 4 | `pcap_manager.py`, `scan_worker.py` | 完成 | | 5 | `api_routes.py` | 完成 | | 6 | `dashboard_app/` — 配置，数据库，sync_client | 完成 | | 7 | Dashboard UI，警报，PCAP 汇总，AI 报告 | 完成 | | 8 | `web_crawler.py`, `web_mirror.py` | 完成 | | 9 | `active_tester.py`（确认受控） | 完成 | | 10 | `storage_monitor.py`，systemd 单元，`SETUP.md` | 完成 | ### 关键模块 - **`scan_engine.py`** — 独立的 Scapy 引擎（`discover_hosts`，`scan_ports`）。在特权子进程中运行，从不被 Flask 导入。 - **`pcap_manager.py`** — `PCAPManager` 实现了 `writer` 协议：实时 `PcapWriter`（`sync=True`），500 MB 轮转并使用 gzip 归档，SHA-256 最终化。 - **`scan_worker.py`** — `network`、`web_static` 和 `web_active` 模式的子进程入口点。 - **`dpi_module.py`** — 离线/实时数据包分析：明文凭据、弱 TLS、过时的 banner、异常的 TCP flags、重叠的分片。 - **`web_crawler.py` / `web_mirror.py`** — 授权的 Web 爬取和用于静态/主动评估的 Podman nginx 镜像。 - **`active_tester.py`** — 仅针对本地镜像的确认受控主动测试。 - **`storage_monitor.py`** — 磁盘阈值检查；当存储空间不足时阻止新扫描。 ## 环境要求 - Python **3.11+** - Scanner：Flask，Scapy，python-dotenv，requests，beautifulsoup4 - Dashboard：Flask，python-dotenv，requests，pyshark，markdown - **tshark**（Wireshark CLI）用于 PCAP 汇总：`sudo apt install tshark` - **podman** + **wget** 用于 Web 镜像模式 - **Ollama** + **DeepSeek R1**（默认为 `deepseek-r1:7b`）用于带有推理轨迹的 AI 报告 - 运行 `bash scripts/setup-ollama.sh` 一次以安装/修复 Ollama 并拉取模型 - 需要 Root/CAP_NET_RAW 权限进行实时扫描（开发环境中 `SCAN_WORKER_SUDO=true`；生产环境中使用 systemd `AmbientCapabilities`） 有关生产部署、systemd 单元和 LUKS 指南，请参阅 **`SETUP.md`**。 首次使用前请运行 **`bash scripts/preflight.sh`**。 ## 快速开始 (Scanner App) ### 1. 克隆并配置 ``` git clone stealthpi cd stealthpi cp .env.example .env cp dashboard_app/.env.example dashboard_app/.env ``` 为您的实验室环境编辑 `.env`： ``` # 示例 — 本地 VMware 开发 MANAGEMENT_INTERFACE_IP=127.0.0.1 SCANNING_INTERFACE=ens33 MANAGEMENT_INTERFACE=ens33 PCAP_STORAGE_DIR=/home/you/stealthpi/storage/pcaps DB_PATH=/home/you/stealthpi/storage/scanner.db FLASK_PORT=9000 SCAN_WORKER_SUDO=true SCANNER_APP_URL=http://127.0.0.1:9000 ``` 创建存储目录（只需一次）： ``` mkdir -p storage/pcaps storage/dashboard_pcaps ``` 如果之前运行过 `sudo` 导致扫描出现权限错误： ``` bash scripts/fix-storage.sh ``` ### 2. 虚拟环境 ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ### 3. 运行 Scanner API（非特权） **终端 1：** ``` bash scripts/start-scanner.sh ``` 或者：`python scanner_app/app.py` - **Web 状态页面：** http://127.0.0.1:9000/ - **API 健康状态：** http://127.0.0.1:9000/api/health 您应该会看到 `Running on http://127.0.0.1:9000`。如果 9000 端口被占用，请停止旧进程（`lsof -i :9000`）或在 `.env` 中更改 `FLASK_PORT`。 通过 API 启动扫描（需要 Bearer token；`SCAN_WORKER_SUDO=true` 对 Scapy 使用 sudo）： ``` curl -X POST http://127.0.0.1:9000/api/scans \ -H "Authorization: Bearer $STEALTHPI_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"target_subnet":"192.168.142.0/24","mode":"network"}' ``` ### 4. 运行网络扫描（特权子进程） 仅 ARP 发现（旧版 CLI）： ``` cd scanner_app sudo ../.venv/bin/python scan_engine.py --subnet 192.168.142.0/24 --out test.pcap ``` 使用 `PCAPManager` + 数据库更新的完整网络扫描： ``` sudo ../.venv/bin/python scan_worker.py \ --scan-id "$(uuidgen)" \ --subnet 192.168.142.0/24 \ --intensity low ``` 或者通过带有 `--scan-id` 的 `scan_engine.py`（插入扫描行，然后委托给 `scan_worker`）： ``` sudo ../.venv/bin/python scan_engine.py \ --scan-id "$(uuidgen)" \ --subnet 192.168.142.0/24 ``` ### 5. 运行单元测试 请务必使用 **venv** 中的 Python（系统 Python 没有安装 Scapy）： ``` source .venv/bin/activate python run_tests.py ``` ## 快速开始 (Dashboard App) **终端 2**（Scanner 必须先在终端 1 中运行）： ``` bash scripts/start-dashboard.sh ``` 在浏览器中打开：**http://127.0.0.1:5002** 从 Scanner UI 同步扫描记录（**Sync Now** 按钮）或通过 CLI： ``` bash scripts/sync-dashboard.sh ``` ## 安全模型 1. 除了 `/api/health` 之外，每个 Scanner API endpoint 都需要 **Bearer token**。 2. Flask 仅绑定到 `MANAGEMENT_INTERFACE_IP` — 绝不绑定 `0.0.0.0`。 3. Scapy 在具有 `CAP_NET_RAW` 的 **子进程** 中通过 systemd 运行；Flask 以非特权用户 `stealthpi` 运行。 4. 主动 Web 模式（`web_active`）需要在请求体中设置 `confirm=true`。 5. 所有来自 `.env` 的密钥均通过 `python-dotenv` 加载 — 绝不硬编码。 6. Pi 数据分区应使用 **LUKS 加密**（参见 `SETUP.md`）。 ## PCAP 管理 `PCAPManager` 写入到： ``` {PCAP_STORAGE_DIR}/{scan_id}/{scan_id}_seg001.pcap ``` 当单个分片大小达到 **500 MB** 时，将被 gzip 压缩，未压缩文件会被删除，并打开一个新的分片。在扫描结束时，`finalise()` 会关闭 writer 并返回最终分片（以 8 KB 数据块流式传输）的 SHA-256 摘要。 ## 项目结构 ``` stealthpi/ ├── scanner_app/ │ ├── app.py # Flask entrypoint + spawn_network_scan() │ ├── scan_engine.py # Host/port discovery (Scapy) │ ├── scan_worker.py # Subprocess scan orchestration │ ├── pcap_manager.py # PCAP capture, rotation, hashing │ ├── dpi_module.py # Deep packet inspection │ ├── database.py # SQLite persistence │ ├── auth.py # Bearer token decorator │ ├── config.py # Environment configuration │ ├── port_lists.py # Nmap top-1000 + UDP ports │ ├── requirements.txt │ └── tests/ ├── dashboard_app/ │ ├── config.py # Dashboard environment config │ ├── database.py # Local SQLite (synced scans, alerts, reports) │ ├── sync_client.py # Pull + SHA-256 verify from Scanner API │ ├── requirements.txt │ └── tests/ ├── requirements.txt # All deps (Scanner + Dashboard) ├── run_tests.py # Run both test suites ├── scripts/fix-storage.sh # Fix pcaps ownership after sudo scans ├── .env.example ├── .gitignore └── README.md ``` ### 6. 端到端验证（手动） ``` bash scripts/preflight.sh E2E_TARGET=192.168.142.0/24 .venv/bin/python test_e2e.py --auto-start ``` ## 许可证与使用 本工具旨在用于 PkCERT 监督下的**授权安全评估**。未经授权扫描您不拥有或未获得明确测试许可的网络，可能会违反当地及国际法律。 ## 作者 PkCERT — 渗透测试与研究 国家 CERT，伊斯兰堡

标签：AI风险缓解, 逆向工具