rsp2k/nautobot-app-scanner
GitHub: rsp2k/nautobot-app-scanner
面向 Nautobot 的 nmap 扫描集成插件，可直接扫描 IPAM 目标并将发现的网络资产与漏洞信息展示在现有设备页面中。
Stars: 0 | Forks: 0
# nautobot-app-scanner
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](https://docs.nautobot.com/)
[](https://github.com/rsp2k/nautobot-app-scanner/releases)
**在 Nautobot 中运行 nmap。** 扫描 IPAM 定义的目标，将主机 / 端口 / 服务 / CVE 存储为一等模型，并将结果直接显示在您的团队已经在使用的 `dcim.Device`、`ipam.IPAddress` 和 `ipam.Prefix` 页面上。
## 功能简介
| | |
|---|---|
| **现有的目标** | 扫描 `ipam.Prefix` 和 `ipam.IPAddress` 记录 —— 无需维护单独的目标列表。 |
| **两种执行模型** | 在 Nautobot worker (`LocalBackend`) 内部运行 nmap，或者卸载到一个或多个远程 agent (`RemoteBackend`)，以覆盖 Nautobot 无法访问的 DMZ / OT / 分支网段。 |
| **默认只读** | 扫描输出存在于*独立的* `DiscoveredHost` / `DiscoveredPort` / `NseFinding` 模型中。提升为 IPAddress 和提升为 Device 是明确的、受权限控制的应急通道。 |
| **随时可见** | `TemplateExtension` 将扫描仪面板注入到 Device / IPAddress / Prefix 详情页中，因此您可以在查找其他所有内容的相同位置找到扫描数据。 |
| **真正的 nmap，而非包装器** | 配置文件是 nmap 参数字符串（如 `-sS -sV -O --top-ports 1000` 等）。预置的目录涵盖发现、端口扫描、OS 指纹、全 TCP、漏洞、路由追踪和 UDP。30 秒内即可编写您自己的配置。 |
| **一流的作业机制** | 扫描通过 Nautobot Jobs 进行调度 —— 调度、审计跟踪、日志流、重试、JobResult 页面全部随附。 |
## 工作原理
```
flowchart TD
job([RunScan Job])
subgraph local["LocalBackend — in Celery worker"]
direction TB
localScan["Scan
status=running"] nmap1["nmap subprocess
parser.parse_xml
parser.persist"] localDone["Scan
status=completed"] localScan --> nmap1 --> localDone end subgraph remote["RemoteBackend — standalone agents"] direction TB remoteScan["Scan
status=pending
ingestion_token=uuid"] agent["Agent polls /pending-scans/
runs nmap locally
POSTs XML to /ingest/"] remoteDone["Scan
status=completed"] remoteScan --> agent --> remoteDone end job --> localScan job --> remoteScan host[(DiscoveredHost)] port[(DiscoveredPort)] vuln[(NseFinding)] trace[(TraceRouteHop)] localDone --> host remoteDone --> host host --> port host --> trace port --> vuln ``` 本地后端由两个容器（Nautobot + worker）和一个单一的 Python 依赖项组成。远程 agent 是位于 Docker 容器中的单个 Python 文件 —— 包含的三个 compose 变体涵盖了 host-network、bridge-network 和 dev-bridge 场景。 ### 扫描数据的显示位置
## 安装说明
```
pip install nautobot-app-scanner
```
然后在 `nautobot_config.py` 中：
```
PLUGINS = ["nautobot_scanner"]
```
…并执行：
```
nautobot-server migrate
nautobot-server post_upgrade
```
迁移附带了 7 个配置目录（`discovery`、`top-100-tcp`、`os-detect`、`full-tcp`、`vuln`、`topology`、`udp-common`），通过 `get_or_create` 进行预置 —— 您的修改将在后续迁移中得以保留。
## 快速入门 —— 开发环境
```
git clone https://github.com/rsp2k/nautobot-app-scanner
cd nautobot-app-scanner
cp development/.env.example development/.env
# 编辑 development/.env：设置 DOMAIN 并轮换 changeme- secrets
make build
make up
make migrate
```
浏览至 `https://${DOMAIN}/`（Caddy 负责处理 TLS）并使用预置的超级用户登录。然后执行 **Apps > Scanner > Scanner Agents > Add** 添加本地 agent，执行 **Jobs > Run Scan**，并从您的 IPAM 中选择一个 `Prefix` 作为目标。
完整的开发指南 —— 包括 docker external-network 设置和 `smoke_local_scan.py` 助手脚本 —— 位于 [docs/dev/dev_environment.md](docs/dev/dev_environment.md)。
## 远程 Agent
为了扫描 Nautobot 无法访问的网络网段（DMZ、OT、分支机构、合作伙伴对等连接），[`agent/`](agent/) 目录提供了一个容器化的参考 agent。相同的镜像，三种 compose 变体：
| 模式 | 使用场景 | Compose 文件 |
|---|---|---|
| **Host network** | LAN 扫描、SPAN 端口、物理接口、OT 网段 | `agent/docker-compose.host-mode.yml` |
| **Bridge / attached** | 清点特定 docker overlay 内部的服务 | `agent/docker-compose.bridge-mode.yml` |
| **Dev-bridge** | 针对开发堆栈进行本地开发 | `agent/docker-compose.dev-bridge.yml` |
Agent 身份验证为每个 `ScannerAgent` 使用专用的 `auth.User`（通过 signal 自动创建），并使用 DRF Token 作为 bearer 凭证。任何语言的自定义 agent 都可以遵循 [Agent Protocol](docs/dev/agent_protocol.md) 进行交互 —— 它仅包含三个 HTTP endpoint。
## 文档
| | |
|---|---|
| **[App 概览](docs/user/app_overview.md)** | App 存储了什么以及它如何与 Nautobot 的其余部分集成 |
| **[运行扫描](docs/user/running_scans.md)** | 通过 Jobs 调度、计划、重叠策略、取消 |
| **[扫描配置文件](docs/user/scan_profiles.md)** | 7 个内置配置，如何编写您自己的配置，NSE 脚本处理 |
| **[提升已发现的主机](docs/user/promotion.md)** | 提升为 IPAddress 和提升为 Device 的工作流 |
| **[Scanner Agent](docs/user/agents.md)** | 本地与远程对比、活性检测、离线标记 |
| **[安装远程 Agent](docs/admin/install_remote_agent.md)** | 操作部署演练 —— 6 个步骤及故障排除 |
| **[Agent Protocol](docs/dev/agent_protocol.md)** | 针对自定义 agent 的 REST 契约 |
| **[架构决策](docs/dev/architecture.md)** | 为什么这个 App 是现在这样的（以及什么是故意排除在范围之外的） |
完整的 MkDocs 站点随 App 一起打包 —— 安装后，在 App 内的 **Apps > Scanner > docs** 处浏览，或使用 `mkdocs serve` 在本地构建。
## *未* 包含的内容
一些被特意排除在外的常见需求 —— 每一项在[架构决策](docs/dev/architecture.md)中都有原因：
- **从扫描自动同步 IPAM** —— 误报将变成永久性的 IPAM 记录。请使用提升功能。
- **自定义 cron 调度器** —— Nautobot 内置的 Job 调度器已经做到了这一点。无需重复造轮子。
- **`ARPBinding` 模型** —— `DiscoveredHost.mac_address` 已经捕获了 ARP 解析的 MAC。
- **`ServiceFingerprint` 模型** —— 指纹字段直接存在于 `DiscoveredPort` 上；无论如何，nmap 的 `-sV` 都会使用 `service_name` 生成它们。
## 许可证
[Apache-2.0](LICENSE) — © Ryan Malloy
status=running"] nmap1["nmap subprocess
parser.parse_xml
parser.persist"] localDone["Scan
status=completed"] localScan --> nmap1 --> localDone end subgraph remote["RemoteBackend — standalone agents"] direction TB remoteScan["Scan
status=pending
ingestion_token=uuid"] agent["Agent polls /pending-scans/
runs nmap locally
POSTs XML to /ingest/"] remoteDone["Scan
status=completed"] remoteScan --> agent --> remoteDone end job --> localScan job --> remoteScan host[(DiscoveredHost)] port[(DiscoveredPort)] vuln[(NseFinding)] trace[(TraceRouteHop)] localDone --> host remoteDone --> host host --> port host --> trace port --> vuln ``` 本地后端由两个容器（Nautobot + worker）和一个单一的 Python 依赖项组成。远程 agent 是位于 Docker 容器中的单个 Python 文件 —— 包含的三个 compose 变体涵盖了 host-network、bridge-network 和 dev-bridge 场景。 ### 扫描数据的显示位置
| **在 `dcim.Device` 详情页上** 在导入时通过与 `Device.primary_ip4/6` 的 IP 匹配进行自动关联 —— 无需手动关联步骤。  | **在 `ipam.Prefix` 详情页上** 覆盖率统计数据（扫描的 IP 百分比、存活主机、最近的扫描）缓存 5 分钟，因此 /16 网段不会导致页面卡顿。  |
标签：CTI, 请求拦截, 逆向工具