jhammant/AutoSecScan

# 🛡️ AutoSecScan **LLM 辅助的安全扫描与报告** — 免费且开源。 AutoSecScan 封装了顶级的开源扫描器（nmap、nuclei、semgrep、trivy、gitleaks、osv-scanner），并使用 LLM 对**结果进行分类**：它标记误报，根据真实世界的影响重新评估严重程度，用通俗易懂的语言解释每个发现，并建议具体的修复方案。它可以通过命令行运行，生成 **JSON / HTML / PDF** 报告，并且可以**每天通过 cron 运行**或在 **git commit/push 之后运行**。你可以将其视为一个自托管、可自定义的 Aikido 替代方案 —— 涵盖了你的**基础设施（IP/主机）**和**代码（代码库）**。 LLM 可以是**完全本地化**的（Ollama 或 **LM Studio**），通过 **Claude Code Router** 路由，调用 **Anthropic API**，通过 **aiondemand** 按需启动，或是任何兼容 **OpenAI** 的 endpoint —— 可通过**规模层级**（small / medium / big / massive）和**风格**（standard / *uncensored*）进行选择。 它有两种运行模式：确定性的**固定 pipeline** 模式，或**agentic 模式**（`--agent`）。在 agentic 模式下，LLM *自行管理扫描* —— 查看已发现的内容并决定下一步操作，直到满意为止。 ## ⚠️ 授权说明 — 请先阅读此部分 AutoSecScan 的设计旨在防止滥用： - **严格的白名单。** 除了 `authorization.authorized_hosts` / `authorized_repos` 之外，*绝不*扫描任何内容。未列出的目标在发送任何数据包之前就会被拒绝。 - **每次运行的认证要求。** 每次运行都需要你证明已获授权 —— 可以是交互式的，或在自动化场景下使用 `--i-have-permission`。 - **没有“扫描一切”的开关。** 特意没有提供全局覆盖功能。 你需对自己的使用方式负全部责任。仅扫描你拥有的或获得明确书面测试许可的内容。 ## 功能 | | | |---|---| | **网络 / 主机扫描** | `nmap`（端口/服务/版本），`nuclei`（CVE 及配置错误模板），`nikto`（Web 服务器） | | **代码 / 依赖扫描** | `semgrep`（SAST），`trivy`（依赖项 + IaC + 密钥），`gitleaks`（已提交的密钥），`osv-scanner`（已知漏洞依赖项） | | **AI 分类** | 误报检测，严重性重新排序，通俗解释，具体修复建议，执行摘要 | | **可插拔 LLM** | Ollama · Claude Code Router · Anthropic · aiondemand · 任何兼容 OpenAI 的 endpoint | | **模型选择** | 规模层级 `small\|medium\|big\|massive` × 风格 `standard\|uncensored` (abliterated/heretic) | | **报告** | 结构化 **JSON**，独立 **HTML** 和 **PDF** | | **自动化** | 日常 **cron**，**git hooks** (post-commit / pre-push)，对 CI 友好的 `--fail-on` 退出码 | | **优雅降级** | 缺失的扫描器会被跳过并附带安装提示；缺失的 LLM 依然可以生成报告 | ## 安装 ### 最快捷 — 一行命令（CLI + Claude 技能） ``` curl -fsSL https://raw.githubusercontent.com/jhammant/AutoSecScan/main/install.sh | bash ``` ### Docker（推荐 — 集成了所有扫描器 + PDF 支持） ``` docker build -t autosecscan . docker run --rm autosecscan doctor # 扫描 repo，报告将保存在 host 上： docker run --rm -v "$PWD:/work" -v "$PWD/reports:/reports" \ autosecscan scan --repo /work --no-net --i-have-permission --format sarif,pdf --out /reports ``` 该镜像捆绑了 nmap、nuclei、semgrep、trivy、gitleaks、osv-scanner 以及 PDF 库 — 宿主机上无需安装任何内容。已发布的镜像将位于 `ghcr.io//autosecscan`（参见 `.github/workflows/release.yml`）。 ### 从 PyPI 安装 ``` pipx install autosecscan # or: pip install autosecscan autosecscan doctor ``` （扫描器需单独安装 — 见下文 — 或使用捆绑了它们的 Docker 镜像。） ### 从源码安装 ``` git clone https://github.com/jhammant/AutoSecScan && cd AutoSecScan python3 -m venv .venv && . .venv/bin/activate pip install -e . # add '.[pdf]' for PDF output (needs pango/cairo) ``` ### 在 Claude Code 中使用 直接从此代码库安装插件 — 无需克隆： ``` /plugin marketplace add jhammant/AutoSecScan /plugin install security-scan@autosecscan ``` 然后让 Claude *“在我部署前进行安全扫描”*，*“有泄露的密钥吗？”*，或 *“对预发环境的 URL 进行渗透测试”*，它就会运行扫描、进行分类并提供修复建议。（或者直接将 [`security-scan` 技能](./integrations/claude-code/) 复制到 `~/.claude/skills/` 中。） ### 在 CI 中使用 (GitHub Action) ``` # .github/workflows/security.yml - uses: jhammant/AutoSecScan@v0.1.0 with: repo: . fail-on: high # fail the build on real high/critical findings format: sarif,json # 然后你可以选择将 .security/*.sarif 上传到 code scanning ``` 安装你需要的任何扫描器（全部可选 — 运行 `autosecscan doctor` 查看检测到了什么）： ``` # macOS (Homebrew) brew install nmap nuclei nikto trivy gitleaks osv-scanner pango pip install semgrep ``` ## 快速开始 ``` autosecscan init # write a starter config you can edit autosecscan authorize add-host 127.0.0.1 autosecscan authorize add-repo ~/dev/myapp autosecscan doctor # what scanners + which LLM are available? # 扫描 host 和 repo，AI-triaged，完整报告： autosecscan scan \ --target 127.0.0.1 \ --repo ~/dev/myapp \ --tier medium --flavor standard \ --format json,html,pdf --out ./reports \ --i-have-permission ``` 报告将生成在 `./reports/scan-.{json,html,pdf}` 中。 ## Agentic 模式 — LLM 管理扫描 默认情况下，AutoSecScan 运行固定的 pipeline。使用 `--agent` 时，LLM 将逐步驱动扫描：它从发现阶段开始，查看发现的结果，然后选择下一个扫描器/目标 — 例如 *nmap 发现了 Web 服务 → LLM 针对它运行 nuclei → 查看结果 → 深入挖掘* — 直到它认为评估已经完成才会停止。 ``` autosecscan scan --target 127.0.0.1 --agent --tier big --flavor uncensored \ --i-have-permission --max-steps 12 ``` 在工作时你会看到 LLM 的推理流 (`🧠 step N: ...`)。 **这并不会削弱安全性。** agent 只能： - 运行**已知的、已安装的**扫描器（绝不运行任意命令）， - 针对在每一步都**重新通过授权白名单**的目标（LLM 虚构但未获授权的目标会被拒绝，不予扫描）， - 使用作为 argv 传递的**经过过滤的**参数（无 shell），并受 `--max-steps` 和单步超时的限制。 在这里，强大的模型会很有帮助 — 这非常适合使用大型的 uncensored/abliterated 模型（经过安全调优的模型通常会拒绝进行攻击性安全推理）。 ### LLM 可以自己添加工具吗？ 可以，但有限制。使用 `--allow-install` 时，如果 agent 决定需要一个未安装的扫描器（比如它发现了一个 Web 应用并想使用 `nuclei`），它可以在扫描过程中安装它然后使用： ``` autosecscan scan --target 127.0.0.1 --agent --allow-install --i-have-permission # 🧠 step 2: 我发现了一个 web service；我需要 nuclei 来检查它的 CVE。 # ⬇ step 2: 正在安装 nuclei (brew install nuclei) # ▶ step 3: nuclei → http://127.0.0.1:8080 ``` 这种安全边界是刻意设计的：LLM 只能从**精选的配置映射**（`nuclei`、`semgrep`、`trivy`、`gitleaks`、`osv` → 固定的 pip/brew/go 命令）中进行安装 — 它**无法虚构或运行任意的安装命令**。默认关闭。 **级别 2 — 运行没有专用解析器的白名单工具** (`--allow-tools`)。 agent 可以调用你加入白名单的任何工具（`sslscan`、`testssl`、`httpx`、`whatweb`、`wpscan`、`sqlmap`、`nikto`）；其 stdout 将作为原始证据被捕获，LLM 会在后续步骤和分类期间对其进行解释： ``` autosecscan scan --target 127.0.0.1 --agent \ --allow-tools sslscan,httpx,nikto --i-have-permission ``` 依然受到限制：仅限**你**允许的工具，仅针对**已授权的**目标，仅限使用带有过滤参数的 argv，以及**每个工具固定的调用模板**（绝不是自由格式的命令行）。 **级别 3 — LLM 编写自己的探测程序** (`--allow-codegen`，⚠ 危险)。agent 可以编写一个独立的 Python 探测程序并运行它 — 这在没有现成工具能检查它想要验证的具体内容时非常有用： ``` autosecscan scan --target hammant.io --agent --allow-codegen --i-have-permission # 🛠 step 3: LLM 编写了工具 'header_check'；正在 sandboxed (docker) 中运行 # 已保存脚本：reports/generated_tools/header_check.py ``` 因为这会执行模型编写的代码，所以防护措施非常严格： - **默认关闭。** 需要 `--allow-codegen`。 - **在 Docker 中沙盒化**（默认）：脚本以只读方式挂载，容器**无法访问你的文件系统**，并且 CPU/内存/pids 都有上限 — 宿主机不会受到损害。（`--codegen-sandbox subprocess` 会在宿主机上以非沙盒方式运行；请仅在临时的一次性 VM 中使用。） - **仅限 Python**，以标准库为导向；**黑名单预检**会拒绝明显具有破坏性或外泄意图的代码；**每个生成的脚本都会被保存**到 `reports/generated_tools/` 供你审查；目标也会被重新授权。 添加一个全新的、*已解析的*扫描器只需进行少量代码修改（继承 `Scanner`，解析该工具的 JSON，添加安装配置） — 参见 `autosecscan/scanners/`。 ## 选择 LLM 无需修改配置即可针对每次运行进行选择： ``` autosecscan models # list the whole provider × flavor × tier catalog autosecscan scan ... --provider ollama --tier big autosecscan scan ... --provider lmstudio --tier big --flavor uncensored # LM Studio, OpenAI API autosecscan scan ... --provider lmstudio-native --tier big --flavor uncensored # LM Studio native /api/v1/chat (reasoning models) autosecscan scan ... --provider ccr --tier medium # Claude Code Router autosecscan scan ... --provider anthropic --tier big autosecscan scan ... --provider ondemand --tier massive --flavor uncensored # remote GLM abliterated autosecscan scan ... --model qwen2.5-coder:32b # exact model override ``` ### 推荐模型 分类和（特别是）agentic 模式在功能强大的模型下推理效果更好。粗略指南： | 用途 | 最低配置 | 推荐配置 | |-----|---------|-------------| | **分类**（解释 / 修复 / 误报过滤） | 7B (`--tier medium`，默认) | 14B–32B (`--tier big`) | | **Agentic 渗透测试** (`--agent`) | 14B | 32B+ / 强大的推理模型 (`--tier big/massive`) | 避免在 `--agent` 模式下使用 ≤3B 的模型 — 它们会误用操作协议并搞乱 JSON（AutoSecScan 会发出警告并尝试恢复，但质量会受到影响）。默认配置（`--tier medium`，7B coder 模型）足以应对分类任务。对于每晚进行的渗透测试，请拉取更大的模型并运行 `--tier big`（或将 provider 指向托管/abliterated 的 32B+ 模型）。 **LM Studio** 在 `http://127.0.0.1:1234` 上会被自动检测到，通过两个 provider 运行：`lmstudio`（兼容 OpenAI 的 `/v1/chat/completions`）和 `lmstudio-native`（LM Studio 的原生 `/api/v1/chat`，它支持**推理模型**以及 `{system_prompt, input} → {output:[…]}` 格式）。默认配置会将它们的层级映射到你机器上找到的 abliterated/heretic 版本 — 运行 `autosecscan models` 查看它们，或设置 `LMSTUDIO_*` 环境变量。 **Uncensored / abliterated 模型**（`--flavor uncensored`）在这里很重要：经过安全调优的模型通常会拒绝推理漏洞利用、payload 或具体的漏洞细节 — 而这正是一款安全工具所需要的分析。为 Ollama 拉取一个，例如 `ollama pull huihui_ai/qwen2.5-abliterate:7b`，或者直接将层级指向你已有的模型。 **aiondemand（远程启动，例如大型的 GLM abliterated 模型）。** 设置 provider 的生命周期命令，以便仅在分类窗口（或 agentic 运行）期间开启远程 GPU endpoint，并在之后将其销毁。`uncensored/massive` 层级已预连接到一个 GLM abliterated 模型 — 请将 `AIONDEMAND_GLM` 指向你的部署所提供的确切 ID： ``` llm: provider: ondemand tier: massive flavor: uncensored # -> ${AIONDEMAND_GLM:-huihui-ai/GLM-4.6-abliterated} providers: ondemand: base_url: ${AIONDEMAND_BASE_URL}/v1 api_key: ${AIONDEMAND_API_KEY} spin_up_cmd: "aiondemand up --model {model} --wait" # {model} is substituted spin_down_cmd: "aiondemand down" health_path: /models health_retries: 30 health_interval: 5 ``` `uncensored/massive` 层级默认指向 [`huihui-ai/Huihui-GLM-5.2-abliterated-GGUF`](https://huggingface.co/huihui-ai/Huihui-GLM-5.2-abliterated-GGUF)。 ``` export AIONDEMAND_BASE_URL=https://my-endpoint.example.com export AIONDEMAND_GLM="huihui-ai/Huihui-GLM-5.2-abliterated-GGUF" # or your served alias autosecscan scan --target 10.0.0.5 --agent --provider ondemand --tier massive --flavor uncensored --i-have-permission ``` ## 自动化 **每日 cron**（默认 02:00） — 为**持续渗透测试**而构建： ``` autosecscan install-cron --target hammant.io --agent \ --schedule "0 2 * * *" \ --notify "https://hooks.slack.com/services/XXX" # or a Discord webhook / shell command autosecscan list-cron autosecscan remove-cron ``` 在两次运行之间，AutoSecScan 会记住它已经发现的内容（基于目标集合，存储在 `~/.autosecscan/state/` 中），因此每日 cron **仅针对新发现的内容发出警报**，而不会因为相同的问题再次打扰你。报告和 CLI 摘要都会标记新发现，并且 `--notify` 仅在出现达到或超过 `--notify-min`（默认为 `high`）的新发现时触发。如果通知失败，绝不会中断扫描。 **Git hook** — 每次推送时扫描代码（如果发现 High+ 级别的问题则进行拦截）： ``` autosecscan install-hook ~/dev/myapp --hook pre-push --blocking --fail-on high autosecscan remove-hook ~/dev/myapp --hook pre-push ``` **CI 门控** — 当真实发现达到阈值时返回非零退出码： ``` autosecscan scan --repo . --no-net --i-have-permission --fail-on high ``` ## 隐私与数据外发 分类阶段会将发现结果发送给 LLM — 而这些结果可能包含密钥（来自 gitleaks/trivy）或源代码。AutoSecScan 根据 provider 类型进行处理： - **本地模型**（Ollama，LM Studio）：数据绝不会离开你的机器。 - **托管模型**（Anthropic，远程 aiondemand，OpenAI）：在发送结果之前会对密钥进行**脱敏处理**（`llm.redact_secrets`，默认开启）。 - **`llm.local_only: true`**：完全拒绝托管 provider — 如果所选模型是托管的，则跳过 AI 分类，从而确保不会有任何扫描数据离开本机。 报告包含敏感的发现结果，并且以 `0600` 权限写入。有关负责任使用和数据处理策略，请参阅 [SECURITY.md](./SECURITY.md)。 ## 配置 配置是分层的（后者覆盖前者）：内置默认值 → `~/.config/autosecscan/config.yaml` → `./config.yaml` → `--config PATH`。字符串支持 `${ENV}` 和 `${ENV:-default}` 展开，从而使密钥/endpoint 不会硬编码在文件中。有关所有选项，请参阅 [`config.example.yaml`](./config.example.yaml)。 ## 工作原理 ``` targets ──▶ authorization gate ──▶ scanners (network + code) ──▶ normalized findings │ LLM triage ◀────────────┘ (FP detection, re-rank, explain, fix, summary) │ JSON · HTML · PDF report ``` 扫描器会首先运行（不需要 LLM）；仅在分类阶段才会调用 LLM — 因此对于远程/按需 endpoint，只会按分钟计费，而不是整个扫描过程。 ## 开发 ``` pip install -e '.[dev]' pytest ``` ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。在采取行动之前，应验证 AI 辅助的发现结果；本工具仅用于辅助人类判断，不能取代人类的判断。

标签：AI风险缓解, CISA项目, DevSecOps, DLL 劫持, LNA, 上游代理, 大语言模型, 实时处理, 插件系统, 请求拦截, 逆向工具