drfeelgood85/CSW-Vulnerability-Scanner
GitHub: drfeelgood85/CSW-Vulnerability-Scanner
针对 Cisco Secure Workload 的本地化漏洞风险仪表盘，将原始漏洞数据通过多源威胁情报富化后提供加权风险评分、补丁建议和修复场景建模，帮助安全团队做出高效的补丁优先级决策。
Stars: 0 | Forks: 0
# CSW 漏洞扫描器
一个专为 **Cisco Secure Workload (CSW)** 设计的 Web 应用程序，能将原始漏洞数据转化为可操作的风险仪表盘 —— 提供补丁建议、场景建模、直接 API 集成以及可导出的报告。
可在单台计算机上本地运行，或通过反向代理在共享 VM 上运行。
🇪🇸 **[Versión en español →](README.es.md)**
## 功能
- 通过 **直接调用 CSW API** 或 **上传 CSV** 进行离线处理
- 在您完整的 CSW 标签分类体系中进行 **基于标签的过滤**
- 针对 CISA KEV、Microsoft MSRC 和 NVD 的 **API 富化**
- **风险评分** — 每台主机的综合得分：`CRITICAL×12 + Active_Breach×10 + Malware×8 + Predicted×6 + HIGH×3 + Popular×1`
- **补丁建议卡片**，按操作系统、.NET、SQL Server、浏览器分组，包含 KB 编号和链接
- **修复场景建模** — 选择目标版本，查看已解决的 CVE/主机
- **全范围快速见效 (Fleet-Wide Quick Wins)** — 按影响力排名的热门软件包，支持单包 CSV 导出
- **生产就绪** — gunicorn (Linux/macOS) 或 waitress (Windows)，HTTP Basic Auth，CSP，nginx 反向代理
## 快速入门 — 一条命令
在 `git clone` 之后，您唯一需要的命令是：
| 操作系统 | 命令 |
|----------------|-------------------|
| macOS / Linux | `./bootstrap.sh` |
| Windows (PS) | `.\bootstrap.ps1` |
引导 (bootstrap) 脚本将执行以下操作：
1. 验证 Python 3.9+
2. 创建 `.venv` 并安装依赖
3. 复制 `.env.example` → `.env`
4. 复制 `credentials.example.json` → `credentials.json`
然后启动应用：
| 操作系统 | 命令 |
|----------------|----------------|
| macOS / Linux | `./run.sh` |
| Windows (cmd) | `run.bat` |
| Windows (PS) | `.\run.ps1` |
打开 **http://localhost:8010**。
## 前置条件
- **Python 3.9 或更高版本**
- macOS: `brew install python@3.11`
- Ubuntu/Debian: `sudo apt install python3 python3-venv python3-pip`
- RHEL/Rocky: `sudo dnf install python3 python3-pip`
- Windows: [python.org 安装程序](https://www.python.org/downloads/) — 勾选 **Add Python to PATH**
- **Git**
这就够了。无需 Docker，无需 Node，除 Python 之外无需其他系统软件包。
## 配置 CSW 凭证
编辑 `credentials.json`（由 `bootstrap` 创建）：
```
{
"api_key": "...",
"api_secret": "...",
"api_endpoint": "https://your-csw-cluster.example.com"
}
```
在 CSW UI 中找到您的 API 密钥：**User Preferences** → **API Keys**。`credentials.json` 已被 gitignore。
您也可以完全跳过此步骤，直接 **上传从 CSW UI 导出的 CSV 文件**。
## 🔐 安全功能
该应用默认为 localhost 安全使用，并提供了在网络上安全暴露所需的所有配置项。**每个安全设置均通过 `.env` 中的环境变量进行配置**（参见 `.env.example`）。
### 身份验证 — HTTP Basic Auth
默认禁用（localhost 开发环境）。要在 `.env` 中启用，请设置：
```
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD=your-strong-password
```
生产环境模式 — 从文件读取密码（支持无重启轮换）：
```
BASIC_AUTH_USERNAME=admin
BASIC_AUTH_PASSWORD_FILE=/etc/csw-report/password
```
应用会在文件修改时间 (mtime) 更改时重新读取密码。统一的 `csw-auth` CLI 可跨 `.env`、systemd、launchd 和 Windows NSSM 管理启用/禁用/轮换/迁移：
```
bin/csw-auth status # show current auth mode + context
bin/csw-auth enable # generate password file + wire it up
bin/csw-auth rotate # generate a new password (no restart needed)
bin/csw-auth migrate # convert an inline-password setup to file-based
bin/csw-auth disable # turn auth off (loopback only, --force to override)
```
Windows: `bin\csw-auth.ps1 `（或在 cmd.exe 中使用 `bin\csw-auth.bat `）。旧的 `bin/csw-rotate-password` 和 `bin/csw-rotate-password.ps1` 脚本仍然有效，但现在会转发至 `csw-auth rotate` 并发出弃用警告。完整参考：[`docs/AUTH.md`](docs/AUTH.md)。
### 网络暴露防护栏
`run.sh` 拒绝在没有身份验证的情况下静默启动面向网络的实例。如果 `HOST != 127.0.0.1` 且 `BASIC_AUTH_*` 未设置，您将收到明确的警告。
**经验法则：** 绝不要在未同时设置 `BASIC_AUTH_USERNAME` + `BASIC_AUTH_PASSWORD`（或 `BASIC_AUTH_PASSWORD_FILE`）的情况下设置 `HOST=0.0.0.0`。
### Session 密钥
Flask 使用 `SECRET_KEY` 进行 session 签名。
- **开发环境：** 每个进程自动生成随机密钥（重启后 session 将失效 — 这没问题）。
- **生产环境：** 将 `SECRET_KEY` 显式设置为 64 位十六进制字符串：
SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
### 内容安全策略 (CSP)
对每个响应应用严格的 CSP —— 禁止内联脚本，禁止内联样式。所有 JS/CSS 均来自 `static/`，并带有基于哈希的完整性校验。在 `security.py` 中配置。
### 速率限制
默认关闭。在面向网络时启用：
```
RATE_LIMIT_ENABLED=true
```
将 Flask-Limiter 限流应用于 POST 端点（上传、抓取）。
### 上传上限
`MAX_UPLOAD_MB=100`（默认值）。可根据加固部署需求调低。
### 运维端点
| 端点 | 认证 | 用途 |
|-------------|--------|-------------------------------------------------------------|
| `/healthz` | 否 | 存活探针 — 只要进程在运行就始终返回 200 |
| `/readyz` | 是 | 就绪探针 — 验证凭证、缓存目录、报告状态 |
| `/progress` | 是 | 后台任务进度 |
### 威胁模型
有关完整的威胁模型、缓解措施以及明确排除的范围，请参见 [`docs/SECURITY.md`](docs/SECURITY.md)。
## 配置参考（环境变量）
所有变量均位于 `.env` 中（由 `bootstrap` 从 `.env.example` 复制而来）。应用 **不会** 自动加载 `.env` —— 需在运行前手动加载：
```
# macOS / Linux
set -a; source .env; set +a; ./run.sh
```
```
# Windows PowerShell
Get-Content .env | Where-Object { $_ -match '^[^#].*=' } | ForEach-Object {
$k,$v = $_ -split '=',2; Set-Item "env:$k" $v
}
.\run.ps1
```
| 变量 | 默认值 | 用途 |
|----------------------------|---------------|--------------------------------------------------------------|
| `HOST` | `127.0.0.1` | 绑定地址 |
| `PORT` | `8010` | 绑定端口 |
| `BASIC_AUTH_USERNAME` | 未设置 | 启用 Basic Auth（必须与以下两项之一配对使用） |
| `BASIC_AUTH_PASSWORD` | 未设置 | 内联密码（仅用于开发/快速测试） |
| `BASIC_AUTH_PASSWORD_FILE` | 未设置 | 包含密码的文件路径（Docker / K8s 模式） |
| `SECRET_KEY` | 随机 | Flask 密钥。**在生产环境中必须显式设置。** |
| `MAX_UPLOAD_MB` | `100` | 上传 CSV 大小上限 |
| `RATE_LIMIT_ENABLED` | `false` | 在 POST 路由上启用 Flask-Limiter |
| `NVD_API_KEY` | 未设置 | 提高 NVD 富化的速率限制（50次/30秒 相比 5次/30秒） |
| `CSW_CA_BUNDLE` | 未设置 | 用于 CSW API 的自定义 CA（企业 TLS 拦截） |
| `LOG_FORMAT` | `text` | `text` 或 `json` — 生产环境推荐使用 `json` |
| `LOG_LEVEL` | `INFO` | 标准 Python 日志级别 |
| `GUNICORN_WORKERS` | `1` | gunicorn worker 数量 (Linux/macOS) |
| `WAITRESS_THREADS` | `4` | waitress 线程数量 (Windows) |
| `SECURITY_CONTACT` | 维护者 | 覆盖 `/.well-known/security.txt` 中的 mailto |
如果 `BASIC_AUTH_PASSWORD` 和 `BASIC_AUTH_PASSWORD_FILE` 均未设置，**应用将在无身份验证下运行**（开发模式）。在此状态下不要绑定到 `0.0.0.0`。
## 生产环境部署
关于服务安装 (systemd / launchd / NSSM)、nginx 反向代理、TLS 和密码轮换：
- **Linux / macOS:** `sudo bash install.sh`（交互式 —— 提示输入身份验证信息，生成 `SECRET_KEY`，作为服务安装）
- **Windows Server:** `.\install.ps1`（将 waitress 注册为 Windows 服务）
- **详细指南：** [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)
## 验证安装
```
python app.py --version
curl http://localhost:8010/healthz # → 200 OK
```
## 项目布局
| 路径 | 用途 |
|-----------------------------|----------------------------------------------------------|
| `bootstrap.sh` / `.ps1` | 一键安装设置（这是 clone 后的入口点） |
| `run.sh` / `.bat` / `.ps1` | 开发服务器启动器 |
| `install.sh` / `.ps1` | 生产环境服务安装程序 (sudo / admin) |
| `app.py` | Flask 应用工厂 + 入口点 |
| `routes_*.py` | 页面、API、导出、运维蓝图 |
| `auth.py` | HTTP Basic Auth 装饰器 |
| `security.py` | CSP + 安全头 |
| `processing.py` | 流水线编排 |
| `api_enrichment.py` | CISA KEV / MSRC / NVD 查询 + 磁盘缓存 |
| `csw_fetch.py` | CSW API 客户端 |
| `templates/` | Jinja2 模板（`upload.html`, `dashboard.html`） |
| `static/` | JS、CSS、第三方静态资源 |
| `scripts/` | 独立的 CLI 实用工具 |
| `tests/` | Pytest 套件 + fixtures + 快照 |
| `docs/` | 深入的文档 |
| `.env.example` | `.env` 的模板（安全/运行时配置） |
## 文档
| 文件 | 主题 |
|--------------------------------------------|-----------------------------------------------------|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 模块图、数据流、并发、安全模型 |
| [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | 开发设置、命令、PR 规范 |
| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | gunicorn / waitress / nginx / systemd / NSSM 配方 |
| [`docs/SECURITY.md`](docs/SECURITY.md) | 威胁模型与缓解措施 |
| [`docs/performance.md`](docs/performance.md) | 性能基线与复现 |
| [`docs/adr/`](docs/adr/) | 架构决策记录 (MADR) |
## 独立脚本
`scripts/CSW_Vulnerabilities_by_Label.py` 是一个 CLI 实用工具，用于在不运行 Web 应用的情况下转储基于标签过滤的漏洞。用法请参见 `scripts/codemap.md`。
## 许可证
Cisco 内部使用。请联系维护者（见 `/.well-known/security.txt`）。
标签：API集成, CISA KEV, CISA项目, Cisco Secure Workload, CSW, CVE, GPT, Gunicorn, Microsoft MSRC, Nginx, NVD, Python, SecOps, Waitress, 云安全架构, 仪表盘, 反向代理, 可观测性, 场景建模, 安全运营, 导出报告, 微隔离, 扫描框架, 数字签名, 无后门, 无线安全, 本地部署, 漏洞管理, 网络安全, 网络安全审计, 补丁建议, 资产安全, 逆向工具, 隐私保护, 风险评分