hafych/nmap-automator

# Nmap Automator **一个专注于安全的 Nmap 编排 API 和仪表板，用于可重复、经授权的网络侦察。** [](https://github.com/hafych/nmap-automator/actions/workflows/ci.yml) [](https://www.python.org/) [](https://nmap.org/) [](LICENSE) Nmap Automator 将 Nmap 变成了对操作员友好的工作流：启动或调度扫描， 在浏览器中跟踪任务，对静态结果进行加密，盘点 Kali 工具，并导出 干净的 JSON、JSONL、Markdown 和 XML，供分析流水线和 AI 助手使用。 ## 为什么选择 Nmap Automator？ 运行一条 Nmap 命令很容易。安全地操作可重复扫描则比较困难。本项目 在 Nmap 周围添加了所需的控制和工件，同时没有隐藏扫描器本身。 | 需求 | Nmap Automator 添加的内容 | | --- | --- | | 可重复侦察 | 即时和周期性的 TCP、SYN、UDP、OS、Aggressive 和 Ping 扫描 | | 可用的控制界面 | 异步 Quart API 加上响应式浏览器仪表板 | | 更安全的操作 | API key 身份验证、目标边界、速率限制、并发限制和超时 | | 受保护的结果 | Fernet 加密、原子替换和仅限所有者的文件权限 | | 利于自动化的输出 | XML、JSON、JSONL、Markdown、清单以及具备服务感知能力的侦察计划 | | Kali 可见性 | 基本工具清单和 13 个官方 metapackage 配置文件 | | AI 辅助分析 | 紧凑的观察流和仅供审查的后续命令建议 | ## 快速开始 ### Docker Compose ``` git clone https://github.com/hafych/nmap-automator.git cd nmap-automator cp .env.example .env python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())" openssl rand -hex 32 ``` 将生成的值放入 `.env` 中的 `FERNET_KEY` 和 `API_AUTH_TOKEN`，然后运行： ``` docker compose up --build -d docker compose ps ``` 打开 [http://127.0.0.1:5000](http://127.0.0.1:5000)，输入 API token，并针对 授权的目标运行 TCP 扫描。 ### 本地 Python 要求：Python 3.10+、`PATH` 中包含 Nmap、一个 Fernet key 以及一个强 API token。 ``` # Debian、Ubuntu 或 Kali sudo apt-get update && sudo apt-get install -y nmap # macOS brew install nmap python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt cp .env.example .env python autonmap.py ``` 该服务默认绑定至 `127.0.0.1:5000`。默认的 `TCP` 配置文件 是无特权的；`SYN`、`UDP`、`OS` 以及部分 `Aggressive` 可能需要提升网络 权限。 ## 工作原理 ``` flowchart LR Operator[Operator or API client] -->|API key| Quart[Quart API and dashboard] Quart --> Limits[Validation, rate limits, concurrency, timeouts] Limits --> Nmap[Nmap] Nmap --> Parse[Result parsing] Parse --> Encrypt[Fernet-encrypted storage] Parse --> Export[JSON, JSONL, XML, Markdown] Parse --> Planner[Review-only recon planner] Inventory[Kali tool inventory] --> Quart Planner --> Export ``` 计划器从不执行其建议。它会验证并对扫描字段进行 shell 引号处理， 将每个命令标记为 `ready`、`missing` 或 `unknown`，然后将执行操作留给操作员。 ## 核心工作流 ### 运行即时扫描 ``` export API_TOKEN='replace-with-your-token' curl -X POST http://127.0.0.1:5000/scan \ -H "X-API-KEY: $API_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"target":"127.0.0.1","scan_type":"TCP"}' ``` 支持的 `scan_type` 值：`TCP`、`SYN`、`UDP`、`OS`、`Aggressive` 和 `Ping`。 目标可以是 IP、有边界的 CIDR、`localhost` 或语法有效的 DNS 名称。 ### 调度和管理周期性扫描 ``` curl -X POST http://127.0.0.1:5000/schedule \ -H "X-API-KEY: $API_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"target":"192.168.1.0/24","scan_type":"TCP","interval":30}' curl -H "X-API-KEY: $API_TOKEN" http://127.0.0.1:5000/tasks curl -X DELETE -H "X-API-KEY: $API_TOKEN" \ http://127.0.0.1:5000/tasks/192.168.1.0%2F24-TCP ``` ### 创建可供 AI 读取的扫描工件 运行 Nmap 并创建一个完整的工件包： ``` python kali_ai_scan.py deps python kali_ai_scan.py run 127.0.0.1 \ --profile tcp \ --scan-timeout 1800 \ --out ai_reports ``` 或者安全地导入现有的 Nmap XML： ``` python kali_ai_scan.py parse nmap.xml --out ai_reports/imported-scan ``` 每个包包含： - `nmap.xml` — 规范的原始 Nmap 输出。 - `hosts.json` — 结构化的主机、端口和服务。 - `observations.jsonl` — 紧凑的主机和服务观察结果。 - `summary.md` — 人类可读的扫描摘要。 - `manifest.json` — 来源、工具链状态、路径和统计数据。 导入的 XML 会使用 `defusedxml` 进行解析，并且上限为 64 MiB。工件目录使用 模式 `0700`；原始文件和派生文件在 POSIX 系统上以仅限所有者的模式 `0600` 原子写入。 ### 盘点 Kali 工具 清单 endpoint 会检查基本命令、已安装的软件包和 13 个官方 Kali metapackage 配置文件。`expand=1` 会跟踪 metapackage 依赖项，速度较慢。 ``` curl -H "X-API-KEY: $API_TOKEN" \ 'http://127.0.0.1:5000/tools?expand=0' curl -H "X-API-KEY: $API_TOKEN" \ 'http://127.0.0.1:5000/tools/ai-context?format=jsonl&expand=0' ``` ### 生成侦察计划 ``` curl -X POST \ -H "X-API-KEY: $API_TOKEN" \ -H 'Content-Type: application/json' \ --data-binary @scan-result.json \ 'http://127.0.0.1:5000/recon/plan?format=markdown' ``` ## API 接口 健康检查和仪表板路由是公开的。操作路由需要配置的 API token， 除非明确禁用了身份验证。 | 方法 | 路由 | 用途 | | --- | --- | --- | | `GET` | `/` 和 `/ui` | 浏览器仪表板 | | `GET` | `/health` | 服务和 Nmap 健康状况 | | `GET` | `/api/docs` | 运行时 API 描述 | | `POST` | `/scan` | 即时扫描 | | `POST` | `/schedule` | 周期性扫描 | | `GET` | `/tasks` | 列出已调度的任务 | | `DELETE` | `/tasks/` | 取消已调度的任务 | | `GET` | `/tools` | Kali 工具清单 | | `GET` | `/tools/ai-context` | JSONL 或 Markdown 清单上下文 | | `POST` | `/recon/plan` | JSON 或 Markdown 后续计划 | ``` curl http://127.0.0.1:5000/health curl http://127.0.0.1:5000/api/docs ``` ## 安全模型 默认部署有意设计为本地和单操作员模式： - 默认需要身份验证； - 服务器和 Compose 端口绑定至 loopback； - 扫描类型被列入允许列表，且目标受边界限制； - 子进程使用 argv 而不是 shell； - Nmap XML 使用具有 XXE 防护的解析器； - 结果文件使用 Fernet 加密并原子写入； - 默认容器以非 root 用户身份运行，具有只读的根文件系统和 `no-new-privileges`。 这不是一个多租户授权系统。在公共或多用户部署之前，请添加 限定范围的身份、任务/结果所有权、持久的共享速率限制以及明确的目标 授权策略。有关支持的部署基准 和私有漏洞报告流程，请参阅 [SECURITY.md](SECURITY.md)。 ## 配置 所有选项均为环境变量，可以放置在 `.env` 中。 | 变量 | 默认值 | 用途 | | --- | ---: | --- | | `FERNET_KEY` | 必需 | 用于加密存储结果的密钥 | | `API_AUTH_TOKEN` | 必需 | API 身份验证标头中预期的 token | | `API_AUTH_REQUIRED` | `true` | 仅针对隔离的本地开发禁用 | | `API_AUTH_HEADER` | `X-API-KEY` | 携带 API token 的标头 | | `APP_HOST` | `127.0.0.1` | 绑定地址 | | `APP_PORT` | `5000` | 监听端口 | | `MAX_CONCURRENT_SCANS` | `2` | 最大并发扫描数 | | `MAX_SCHEDULED_TASKS` | `100` | 最大保留的周期性扫描数 | | `SCAN_TIMEOUT_SECONDS` | `1800` | Nmap 进程总超时时间 | | `NMAP_HOST_TIMEOUT_SEC` | `300` | Nmap 单主机超时时间 | | `NMAP_MAX_RETRIES` | `2` | Nmap 探测重试次数 | | `MAX_TARGET_ADDRESSES` | `4096` | 接受的最大 CIDR 范围 | | `MAX_REQUEST_BODY_BYTES` | `1048576` | 最大 JSON 请求体大小 | | `MAX_REQUESTS_PER_WINDOW` | `10` | 每个客户端的高成本请求限制 | | `MAX_RATE_LIMIT_CLIENTS` | `10000` | 最大保留的客户端桶数 | | `RATE_LIMIT_WINDOW_SECONDS` | `60` | 速率限制窗口 | | `MIN_SCHEDULE_INTERVAL_MINUTES` | `1` | 最小周期性扫描间隔 | | `MAX_SCHEDULE_INTERVAL_MINUTES` | `10080` | 最大间隔（以分钟为单位） | | `RESULTS_DIR` | `encrypted_results` | 加密结果目录 | | `SCAN_LOG_PATH` | `logs/scan_log.txt` | 轮换的应用程序日志 | | `TOOL_INVENTORY_CACHE_SECONDS` | `300` | Kali 清单缓存生存期 | | `INITIAL_TASKS` | `[]` | 启动周期性扫描的 JSON 数组 | | `TELEGRAM_BOT_TOKEN` | 空 | 可选的 Telegram bot token | | `TELEGRAM_CHAT_ID` | 空 | 可选的 Telegram 目标 | 启动任务示例： ``` INITIAL_TASKS=[{"target":"192.168.1.0/24","scan_type":"TCP","interval":30}] ``` ## 加密结果 API 结果仅以加密形式存储。请单独备份 `FERNET_KEY`；如果 密钥丢失，现有结果将无法恢复。 ``` # 打印 plaintext python decrypt.py encrypted_results/.json # 将 plaintext 写入仅限所有者的文件 python decrypt.py encrypted_results/.json -o result.json ``` ## Docker 说明 默认的 Compose 配置文件仅持久化日志和加密结果。默认的容器配置中 特意未启用特权扫描类型。 ``` docker compose logs -f docker build -f dockerfile -t nmap-automator . docker run --rm \ -p 127.0.0.1:5000:5000 \ -e API_AUTH_TOKEN \ -e FERNET_KEY \ nmap-automator ``` ## 开发 ``` python -m pip install -r requirements-dev.txt ruff format --check . ruff check . python -m coverage run -m unittest discover -v python -m coverage report bandit -q -ll -r . \ -x ./.venv,./test_autonmap.py,./test_decrypt.py,./test_kali_ai_scan.py,./test_recon_planner.py,./test_tool_inventory.py pip-audit -r requirements.txt ``` CI 会测试 Python 3.10、3.12 和 3.14，强制执行代码覆盖率和格式化，运行 Bandit，并 审计依赖项。Dependabot 会跟踪 pip、GitHub Actions 和 Docker 的更新。 ## 项目布局 | 路径 | 职责 | | --- | --- | | `autonmap.py` | Quart API、验证、调度、扫描、加密和关闭 | | `ui.py` | 独立的操作员仪表板 | | `kali_ai_scan.py` | Nmap 运行器、安全的 XML 解析器和工件生成器 | | `tool_inventory.py` | Kali 软件包和命令清单 | | `recon_planner.py` | 具备服务感知能力、可供 AI 读取的后续计划 | | `decrypt.py` | Fernet 结果解密实用工具 | | `test_*.py` | 单元和异步 API 回归测试 | ## 贡献 欢迎提交 bug 报告、重点改进和特定于平台的验证。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并对安全漏洞使用私下报告。 如果 Nmap Automator 对您的工作流有所帮助，请考虑为该仓库加星，以便其他操作员 能够发现它。 ## 许可证 GNU General Public License v3.0。请参阅 [LICENSE](LICENSE)。

标签：CTI, Nmap, Python, Web看板, 插件系统, 无后门, 虚拟驱动器, 请求拦截, 逆向工具