fantasmagorikus/portscan-detection-lab
GitHub: fantasmagorikus/portscan-detection-lab
一个基于 Suricata 与 ELK 技术栈的容器化实验项目，用于检测和可视化 TCP SYN 端口扫描行为。
Stars: 1 | Forks: 0
# 端口扫描检测实验室 — Suricata → Filebeat → Elasticsearch → Kibana
[](README.md)
[](README.pt-BR.md)
一个现代、可复现的实验室，用于通过 Suricata 检测 TCP SYN 端口扫描，通过 Filebeat 将事件传输到 Elasticsearch，并在 Kibana Lens 中可视化所有内容。包含本地检测规则、Saved Objects 导出 (NDJSON)、健康/备份/导出/截图脚本以及双语文档。
## 目录
- [我构建了什么及其原因](#what-i-built--why)
- [架构与流程](#architecture--flow)
- [设计决策](#design-decisions)
- [组件与版本](#components-and-versions)
- [检测规则（本地）](#detection-rules-local)
- [操作手册（设置 → 健康 → 流量 → 卸载）](#runbook-setup--health--traffic--teardown)
- [自动化脚本](#automation-scripts)
- [流量生成 (Nmap)](#traffic-generation-nmap)
- [Kibana 仪表盘与 KQL](#kibana-dashboard--kql)
- [证据与截图](#evidence--screenshots)
- [导出 (NDJSON) 与可复现性](#exports-ndjson--reproducibility)
- [备份与快照](#backup--snapshots)
- [强化与运维说明](#hardening--ops-notes)
- [故障排除](#troubleshooting)
- [项目布局](#project-layout)
- [证据与截图（图库）](#evidence--screenshots-gallery)
- [结果与证据](#results--evidence)
- [许可证、行为准则、安全性](#license-conduct-security)
- [致谢](#acknowledgements)
## 我构建了什么及其原因
- 容器化的 Suricata → Filebeat → Elasticsearch → Kibana 实验室，专注于 TCP SYN 扫描检测。它是攻击性 [Pentest Lab](https://github.com/fantasmagorikus/pentest-lab) 的补充，让你能够展示事物的两面。
- 本地 Suricata 规则：基线 SYN (sid 9900001) + 阈值规则 (sid 9901001)，用于标记 Nmap 扫描。
- 通过 Filebeat Suricata 模块将 EVE JSON 传输到 ECS 数据流中，并通过精心策划的 Kibana 仪表盘进行可视化。
- 运维脚本涵盖健康检查、快照/备份、屏幕截图捕获以及用于可移植性的 NDJSON 导出。
- `.env` 可切换单机 (`lo`) 和 LAN 接口；OWASP Juice Shop (3000/tcp) 提供确定性流量。
检测 TCP SYN 端口扫描，将其与 Juice Shop 流量相关联，并在 Kibana Lens 中呈现全貌。这模仿了 [Pentest Lab](https://github.com/fantasmagorikus/pentest-lab) 的文档风格，以保持两个仓库的一致性。
## 架构与流程
```
┌──────────────────────────────┐ ┌────────────────────────────┐
│ Suricata (EVE JSON) │ │ Filebeat Suricata module │
│ network_mode: host │──────────▶│ ECS data streams / ES │
│ Local rules 9900001 / 9901001│ alerts └────────────┬────────────────┘
└─────────────┬────────────────┘ │
│ HTTP / ECS ▼
┌───────────────┐ ┌───────────────┐
│ Juice Shop │◀───────────── traffic ──▶│ Kibana Lens │
└───────────────┘ └───────────────┘
```
- Suricata：成熟的 IDS，可发出结构化的 EVE JSON（警报、流、统计信息）
- Filebeat Suricata 模块：ECS 映射 + 数据流简化了数据摄取
- Elasticsearch/Kibana：快速搜索、KQL 和基于 Lens 的可视化
- 本地规则：为 SYN 和扫描阈值量身定制的检测，以突出 Nmap 活动
## 设计决策
- Suricata + EVE JSON：成熟的 IDS，具有结构化输出（警报、流、统计信息），非常契合 ELK 数据摄取。
- Filebeat Suricata 模块：自动化的 ECS 映射和数据流减少了自定义解析/schema 的工作量。
- 为 Suricata 启用 Host networking：在 Linux 上需要查看主机流量；通过 `.env` 切换以适应单机 (lo) 或 LAN (NIC)。
- 本地规则：基线 SYN + 阈值规则可产生清晰的扫描信号，无需繁重的规则包；易于解释和复现。
- Kibana Lens + Saved Objects：快速迭代和可移植的视觉效果；NDJSON 导出已附加到发布版本中。
- 快照 + 备份脚本：保存状态和工件，用于可重复的演示和审计。
- 无头模式截图：提供一致的作品集证据，无需手动捕获步骤。
## 组件与版本
- Suricata 8.x (容器 `jasonish/suricata:latest`)
- Filebeat 8.14.3 (容器)
- Elasticsearch 8.14.3 (单节点，实验室环境关闭安全功能)
- Kibana 8.14.3
- OWASP Juice Shop (目标应用) 运行在 `:3000`
## 检测规则（本地）
定义在 `local-rules/local.rules` 中：
```
alert tcp any any -> $HOME_NET any (msg:"LAB - TCP SYN"; flags:S; flow:stateless; sid:9900001; rev:2;)
alert tcp any any -> $HOME_NET any (msg:"LAB - Port Scan (SYN threshold)"; flags:S; flow:stateless; detection_filter: track by_src, count 20, seconds 60; classtype:attempted-recon; sid:9901001; rev:1;)
```
- 9900001：基线 SYN 检测
- 9901001：当某个源在 60 秒内发送 ≥20 个 SYN (by_src) 时引发警报
## 操作手册（设置 → 健康 → 流量 → 卸载）
前置条件 (Linux)：Docker、Docker Compose、`curl`、`jq`、`nmap`。
```
cd homelab-security/suricata-elk-lab
# 1) 配置 interface（单主机 = lo，LAN = 你的 NIC）
cp .env.example .env
# 如有需要，编辑 SURICATA_IFACE
# 2) 启动 stack
docker compose up -d
# 3) 健康检查 + 日志捕获
bash scripts/retomada_check.sh
# 4) 生成流量（单主机示例）
sudo nmap -sS -p 1-10000 127.0.0.1 -T4 --reason
# 5) 探索 dashboard
open http://localhost:5601
# 6) 销毁
docker compose down -v
```
Makefile 快捷方式（单机）：
`make up | make health | make nmap-local | make dashboard | make screenshots | make backup | make down`
## 自动化脚本
- `scripts/retomada_check.sh` — 一次性健康检查清单（服务、日志、curl 检查），包含带时间戳的报告。
- `scripts/backup.sh` — ES 快照 + Suricata 日志 + 配置打包 + 下一步操作检查清单。
- `scripts/kibana_export_dashboard.sh` / `scripts/kibana_rename_dashboard.sh` — Saved Objects 操作。
- `scripts/capture_screenshots.sh` — 无头 Chromium 捕获仪表盘面板，用于文档/作品集。
- `scripts/publish_github.sh` — 通过 `gh` CLI (SSH) 将仓库镜像到 GitHub。
## 流量生成 (Nmap)
- 单机回环：
sudo nmap -sS -p 1-10000 127.0.0.1 -T4 --reason
- LAN 演示（从攻击者主机执行）：
sudo nmap -sS -p 1-1000 -T4 --reason
## Kibana 仪表盘与 KQL
在 `http://localhost:5601` 打开 Kibana。
- 创建 Data View（如果出现提示）：
- 名称：`filebeat-*`
- 时间字段：`@timestamp`
- 仪表盘：“Port Scan Detection (Suricata)”
- 随时间变化的警报（按 signature 堆叠）
- 主要源 IP（警报）
- 主要目标端口（警报）
- 目标端口范围（well-known/registered/dynamic）
- 警报详情（已保存的搜索）
- 实用的 KQL 过滤器：
```
event.module: "suricata" and suricata.eve.event_type: "flow"
event.module: "suricata" and suricata.eve.event_type: "alert"
suricata.eve.alert.signature_id: 9901001
```
## 证据与截图
- Kibana 截图保存在 `docs/screenshots/` (PNG) 下，可以通过 `make screenshots` 重新生成。
- `scripts/capture_screenshots.sh` 将原始 PNG 存储在 `docs/screenshots/` 中，用于 README 嵌入和面试展示。
- 结合 [Pentest Lab](https://github.com/fantasmagorikus/pentest-lab) 的证据，讲述攻击 + 防御的完整故事（例如，Suricata 警报截图与 ZAP 发现相呼应）。
## 导出 (NDJSON) 与可复现性
Saved Objects 导出文件以 NDJSON（换行符分隔的 JSON）格式提供在 `kibana_exports/` 下。导入它以重新创建仪表盘和相关对象。
- 导出（脚本）：
```
bash scripts/kibana_export_dashboard.sh "Port Scan Detection (Suricata)"
```
- 导入（UI）：Kibana → Stack Management → Saved Objects → Import → 选择 `.ndjson` 并确认。
## 备份与快照
使用单个脚本创建 Elasticsearch 快照并归档实验室配置：
```
bash scripts/backup.sh
```
在 `backups//` 下的输出内容包括快照响应、Suricata 日志（如果有）以及关键配置的 tar 包。
## 强化与运维说明
- Suricata 以 `network_mode: host` 运行；请仔细调整 `.env`（没有默认的 NIC 假设）。
- Filebeat 以 root 身份运行，并带有 `-strict.perms=false`，以避免在挂载配置时出现权限垃圾信息。
- Elasticsearch 集群出于实验目的禁用了安全功能——切勿暴露于不受信任的网络中。如果要将其转变为长期运行的 SIEM，请启用 `xpack.security`。
- 如果在云中运行，请将快照（`es-snapshots` volume）和备份（`backups/`）存储在非易失性磁盘之外。
## 故障排除
- Nmap 扫描后无警报
- 确保捕获接口与你的场景匹配（单机为 `lo`，LAN 为你的 NIC）
- 确认规则已加载且 Suricata 运行正常（`docker logs suricata-lab-suricata`）
- 增加扫描强度（例如 `-p 1-10000`）
- Kibana 中无数据
- 检查 Filebeat 配置/输出：
- `docker exec suricata-lab-filebeat filebeat -e -strict.perms=false test config`
- `docker exec suricata-lab-filebeat filebeat -e -strict.perms=false test output`
- 检查 Elasticsearch/Kibana 的可达性（`curl` 9200/5601）
- 时间对齐问题
- 在 Kibana 中，将时区设置为“Browser”并扩大时间窗口
## 项目布局
- `docker-compose.yml` — 容器与 volumes
- `.env` — 捕获接口 (`SURICATA_IFACE`)
- `suricata/suricata.yaml` — EVE JSON 输出（警报、流）
- `local-rules/local.rules` — 实验室检测规则 (9900001 / 9901001)
- `filebeat/filebeat.yml` — Suricata 模块 → Elasticsearch
- `scripts/` — 备份、健康检查、导出/重命名辅助脚本
- `kibana_exports/` — Saved Objects 导出 (.ndjson)
- `Makefile` — 常见任务：`make up|down|health|backup|export|screenshots`
## 证据与截图（图库）
仪表盘概览（最近 15 分钟）：
最近活动（最近 5 分钟）：
随时间变化的警报（按 signature 堆叠）：
主要源（警报）：
主要目标端口（警报）：
主要目标端口（特写）：
警报详情（Discover）：
## 更新日志
有关版本历史和亮点，请参见 CHANGELOG.md。
## 结果与证据
- 摄取的流事件（最近 10 分钟）：109
- 警报（最近 10 分钟）：总计 473
- sid=9901001 (端口扫描阈值)：224
- sid=9900001 (TCP SYN)：249
- 仪表盘和 Saved Objects 导出可在 `kibana_exports/` 中找到
## 许可证、行为准则、安全性
- MIT 许可证 (LICENSE)
- 行为准则 (CODE_OF_CONDUCT.md)
- 安全策略和漏洞报告 (SECURITY.md)
## 致谢
- Suricata IDS, Elastic Beats, Elasticsearch, Kibana
- OWASP Juice Shop
标签：CTI, ELK Stack, Metaprompt, Suricata, 安全实验环境, 应用安全, 插件系统, 版权保护, 现代安全运营, 端口扫描检测, 网络安全, 请求拦截, 越狱测试, 隐私保护