pseudocoder204-source/Pulser

# Pulser [](LICENSE) [](https://www.python.org/downloads/) [](https://github.com/pseudocoder204-source/Pulser/stargazers) 一个多扫描器家庭网络安全 pipeline。它将几个开源扫描器组合成一个 agentic 系统，为非技术用户生成一份**通俗易懂**的安全报告： | 扫描器 | 覆盖范围 | |---|---| | **Nmap** | 开放端口、服务/版本检测、CVE 富化、IoT 默认凭据检查 | | **Trivy** | 本地文件系统包漏洞 (Linux/macOS) | | **Nuclei** | 基于 template 的 Web/网络漏洞检查 | | **Lynis** / **Windows audit** | 主机强化审计 (Linux/macOS 通过 Lynis，Windows 通过原生 PowerShell 审计) | | **ClamAV** / **Windows Defender** | 恶意软件扫描 (Linux/macOS 上使用 ClamAV，Windows 上使用 Defender 威胁历史记录) | 每个扫描器都有一个解析器和一个独立的 [LangGraph](https://github.com/langchain-ai/langgraph) 子图。确定性的编排层 (`agent.py`) 以固定的顺序运行扫描器，将所有发现扁平化为单个表格，并**仅**使用 LLM 来重新排序和解释这些发现——绝不会用它来选择扫描什么。有关完整的架构，请参阅 `CLAUDE.md`。  ## 为什么开发这个项目 我是一名 15 岁的自学开发者，这是我的热爱之作。小企业主和普通人想知道他们的设备和网络是安全的，但目前没有单一的工具能用通俗易懂的语言确切地告诉你到底哪里出了问题以及如何修复。我并不想取代 Windows Defender 或现有的那些杀毒软件。我开发 Pulser 是为了给你的网络和设备提供一个快速的“健康体检”：运行它，它会确切地告诉你它发现了什么以及该如何处理，这样你就能获得内心的安宁，而无需成为一名安全专家。 ## 输出示例 ``` ============================================================== SECURITY DIAGNOSTIC REPORT 🔴 CRITICAL RISK ============================================================== The scan found 12 issue(s) that need attention out of 14 item(s) reviewed. ── ISSUES FOUND (12) ────────────────────────────────────── 1. 🔴 [CRITICAL] SSH login could leak information about your smartcard setup Affected : Port 22 — ssh OpenSSH 9.6p1 Ubuntu 3ubuntu13.16 What it means : This device's remote-login software (SSH) has a bug that could let someone learn more about your smartcard setup than they should. Why it matters : This is worth fixing soon to avoid leaking information that shouldn't be public. How to fix: 1. Update the SSH software to the latest version. 2. If you don't use this feature, consider turning it off in your SSH client settings. References: • https://access.redhat.com/errata/RHSA-2024:4312 • https://lists.fedoraproject.org/archives/list/package-announce%40lists.fedoraproject.org/message/AN2UDTXEUSKFIOIYMV6JNI5VSBMYZOFT/ ... ``` ## 环境要求 - Python 3.10+ - 适用于你操作系统的扫描器二进制文件（参见[安装扫描器](CONTRIBUTING_SCAN_DATA.md#install-the-scanners)） - **[Nmap](https://nmap.org/download.html)，由你自行安装。** 出于许可原因，Pulser 不附带 Nmap （参见[许可与致谢](#licensing-and-attributions)）。 请从你的包管理器（`apt install nmap`, `brew install nmap`, `apk add nmap nmap-scripts`）或 nmap.org 安装它，并确保它位于 `$PATH` 中——或者将 `NMAP_BINARY` 指向它。在 Windows 上，LAN 扫描还需要 [Npcap](https://npcap.com/#download)，这也需要由你自行安装。 - 一个 LLM 后端：本地的 [Ollama](https://ollama.com) 模型（默认，参见 下方的[设置 Ollama](#setting-up-ollama)）**或**一个 Anthropic API 密钥 如果没有 Nmap，Pulser 仍然可以运行：端口/服务、CVE 富化和 IoT 默认凭据阶段将报告 `{"status": "unavailable"}`，其余扫描器（Trivy, Nuclei, Lynis, ClamAV）会正常继续。你失去的只是网络扫描结果，而不是整个运行过程。 ## 快速安装 一个安装脚本可以一次性配置好扫描器工具、Python 依赖项和 Ollama 模型。它只负责**安装**，从不进行捆绑——每个工具都来自你的操作系统包 管理器或工具自身的上游发布版本（来自你发行版/`winget` 的 Nmap，来自官方 安装程序的 Trivy 和 Nuclei），因此 Pulser 不会重新分发任何东西。它是幂等的：任何 已存在的组件都会被跳过。 **Linux / macOS:** ``` python3 -m venv .venv && source .venv/bin/activate # recommended ./install.sh ``` **Windows** (PowerShell): ``` python -m venv .venv; .\.venv\Scripts\Activate.ps1 # recommended .\install.ps1 ``` 该脚本会打印出它安装了什么的摘要，以及你还需要自己做些什么。它 故意**不**触碰以下三样东西： - **Npcap**（Windows LAN 扫描）——其许可证禁止重新分发，因此 `install.ps1` 只会 检测它并链接到 [npcap.com](https://npcap.com/#download)；你需要自己安装它。 - **Ollama 本身**——请先从 [ollama.com/download](https://ollama.com/download) 安装它 （该脚本只会拉取*模型*，而不包含 runtime）。安装完成后请重新运行此脚本。 - **CVE 缓存**（约 3.2 GB）——从 Releases 页面下载（参见 [CVE 缓存](#the-cve-cache)）。 想要手动完成？该脚本所做的一切都在下面详细说明了——首先安装 扫描器（[安装扫描器](CONTRIBUTING_SCAN_DATA.md#install-the-scanners)），然后： ``` pip install -r requirements.txt ``` ## 设置 Ollama Pulser 只有一个 LLM 阶段：**report**（撰写通俗英文报告）。Triage （按优先级对发现进行排序）是确定性的 Python 代码，而不是 LLM 调用——我们对三个经过微调的 triage 模型进行了评估，在保留数据上没有一个能胜过简单的严重性层级 + CVSS 排序， 因此该阶段不调用任何 LLM（参见 `notes/FinetuneGuideTriage.txt` 第 5 阶段）。 默认情况下，report 运行在标准的 `llama3.1:8b` 上。Pulser 还发布了一个微调过的 `mark2-report` 模型——该模型基于 report 阶段的实际 prompt/output contract 进行训练—— 在同等规模下，它能比标准模型生成更好的面向家庭用户的报告。 1. **安装 Ollama**——有关 macOS/Windows/Linux 的说明，请参见 [ollama.com/download](https://ollama.com/download)。确保它正在运行（`ollama serve`，或者直接 启动该应用程序——它会在 macOS/Windows 上自动启动一个后台服务）。 2. **拉取模型：** ollama pull pseudocoder204/mark2-report # report 阶段 (微调版) 3. **将 report 阶段指向它：** export OLLAMA_MODEL=pseudocoder204/mark2-report 如果未设置，默认使用 `llama3.1:8b`，因此只有在选择使用微调过的 report 模型时才需要执行此步骤。 ## 运行诊断 ``` # 使用默认的 Ollama backend 扫描您自己的机器（默认目标 127.0.0.1） python3 agent.py [--target IP] [--json] # 使用 Anthropic 替代 Ollama LLM_PROVIDER=claude ANTHROPIC_API_KEY=sk-... python3 agent.py ``` 你还可以独立运行任何单个扫描器的子图： ``` python3 nmap_subgraph.py [target] python3 nuclei_subgraph.py [target] python3 trivy_subgraph.py python3 lynis_subgraph.py python3 clamav_subgraph.py ``` ### CVE 缓存 CVE 富化会读取一个本地的 SQLite 缓存 `vulnerability_cache.db`。它大约有 **3.2 GB**，因此 它**不**在代码库中——请从 Releases 页面下载压缩版本（约 126 MB）并将其 解压到代码库根目录： **Linux / macOS:** ``` gunzip -c vulnerability_cache.db.gz > vulnerability_cache.db ``` **Windows** (PowerShell——默认情况下无法使用 `gunzip`/`gzip`；此命令使用 .NET 的 内置 `GzipStream`，因此不需要额外的工具)： ``` # 从 repo root 运行，并确保 vulnerability_cache.db.gz 已在此文件夹中 # （如果您的浏览器将其保存到了 Downloads，请先将其移动到此处）。 if (-not (Test-Path .\vulnerability_cache.db.gz)) { throw "vulnerability_cache.db.gz not found in $(Get-Location) - move/download it here first." } # Windows PowerShell 5.1 默认不加载 System.IO.Compression（PowerShell Core 会加载）- # 如果没有它，GzipStream 会失败并报错 "Cannot find type [System.IO.Compression.GzipStream]"。 Add-Type -AssemblyName System.IO.Compression $in = [System.IO.File]::OpenRead((Resolve-Path .\vulnerability_cache.db.gz)) # 使用基于 PowerShell 自身位置构建的 path，而不是单纯的相对 string - # .NET 的 Create()/OpenRead() 会根据 Environment.CurrentDirectory 解析相对 path， # 这可能会与 PowerShell 的 $PWD 静默产生差异，并将文件发送到/拒绝在其他位置。 $out = [System.IO.File]::Create((Join-Path (Get-Location) "vulnerability_cache.db")) $gz = New-Object System.IO.Compression.GzipStream($in, [System.IO.Compression.CompressionMode]::Decompress) $gz.CopyTo($out) $gz.Close(); $out.Close(); $in.Close() ``` 如果没有它，pipeline 会创建一个空的缓存，并在首次运行时从 NVD 同步大约 30 天的 近期 CVE（速度较慢，完整性较低）。请设置 `NVD_API_KEY` 以获得更高的 NVD 速率限制。 ## Docker ``` docker build -t mark2 . docker run --rm --network host -e TARGET=192.168.1.1 mark2 ``` 默认镜像**不包含 Nmap**（参见 [许可与致谢](#licensing-and-attributions)），因此网络扫描阶段会 报告 `unavailable`。要恢复这些功能，请**为你自己的本地用途**构建一个包含 Nmap 的镜像： ``` docker build --build-arg INSTALL_NMAP=true -t mark2 . ``` 以这种方式构建的镜像不得被推送到镜像仓库或以其他方式重新分发—— 否则将需要 [Nmap OEM 许可证](https://nmap.org/oem/)。为你自己构建它 并不属于重新分发。 在 Linux 上需要使用 `--network host`，以便 Nmap/Nuclei 可以访问你 LAN 上的主机。有关完整的环境变量和卷挂载（CVE 缓存、ClamAV 清单等）集合，请参见 `CLAUDE.md`。 ## 许可证与致谢 Pulser 基于 **GNU General Public License v2** 授权（参见 [`LICENSE`](LICENSE)）。 Pulser 只是一个编排层：**它不提供任何扫描器二进制文件。** 你需要自行安装 扫描器，Pulser 会将每个扫描器作为单独的程序运行并读取其输出——它从不 包含、链接或修改它们的代码。因此，每个扫描器仍保留其自身的许可证， 使用 Pulser 除了要求你安装这些工具外，对你没有任何其他要求。实际扫描的功劳 归属于它们的作者： | 工具 | 作者 / 维护者 | 许可证 | 在 Pulser 中的作用 | |---|---|---|---| | [Nmap](https://nmap.org) | Nmap Software LLC (Gordon "Fyodor" Lyon) | [Nmap Public Source License](https://nmap.org/npsl/) (NPSL, GPLv2 衍生) | 端口/服务发现，版本检测，IoT 默认凭据 NSE 检查 | | [ClamAV](https://www.clamav.net) | Cisco Systems, Inc. / Talos | [GPL-2.0](https://github.com/Cisco-Talos/clamav/blob/main/COPYING.txt) | 恶意软件扫描 (`clamscan`) | | [Lynis](https://cisofy.com/lynis/) | CISOfy / Michael Boelen | [GPL-3.0](https://github.com/CISOfy/lynis/blob/master/LICENSE) | 主机强化审计 | | [Trivy](https://trivy.dev) | Aqua Security | [Apache-2.0](https://github.com/aquasecurity/trivy/blob/main/LICENSE) | 文件系统包漏洞扫描 | | [Nuclei](https://projectdiscovery.io) | ProjectDiscovery, Inc. | [MIT](https://github.com/projectdiscovery/nuclei/blob/main/LICENSE.md) | 基于 template 的 Web/网络漏洞检查 | 每个工具的完整许可证文本保存在 [`THIRD_PARTY_LICENSES/`](THIRD_PARTY_LICENSES/) 中。 CVE 数据来自 [NVD](https://nvd.nist.gov/)，属于公共领域（NIST 不 认可本项目）。 有两点值得注意：Pulser **不**捆绑 [Nmap](https://nmap.org/download.html) （请自行安装——这是一个刻意的许可选择），并且你应该只扫描你拥有 或被授权测试的系统。 要将 Pulser 商业化打包、将其作为服务托管，或捆绑任何扫描器二进制文件？完整的 许可分析——包括 NPSL/OEM、Docker source-offer、Npcap、托管部署通知——位于 [LICENSING.md](LICENSING.md) 中。

标签：AI风险缓解, C2, CTI, DLL 劫持, Python, Web报告查看器, XXE攻击, 大语言模型, 插件系统, 无后门, 网络安全, 自动化运维, 请求拦截, 逆向工具, 隐私保护