Alqaly/smart-city-ids
GitHub: Alqaly/smart-city-ids
面向智慧城市 IoT 场景的 Kubernetes 原生入侵检测研究原型，整合 Falco、Suricata 与 LLM 辅助分析，支持治理控制的自动化响应。
Stars: 1 | Forks: 0
# 智慧城市 IDS
面向智慧城市场景 IoT 工作负载的 Kubernetes 原生入侵检测与响应平台，集成了：
- **Falco**（运行时/容器检测）
- **Suricata**（网络检测）
- **LLM 辅助告警分析**（多 Provider 路由/故障转移）
- **治理控制的 Kubernetes 响应动作**（手动/辅助/自主）
本仓库包含：
- 一个可工作的演示器/原型系统，以及
- 毕业项目/答辩文档及支持材料。
## 范围（外部评审人员必读）
这是一个**研究/毕业设计原型**，而非生产级 SOC 平台。部分内容面向演示（IoT 模拟器、攻击脚本、评审准备文档），而核心运行时组件是真实且可测试的。
为避免声明过时造成的混淆：
- 以此 `README.md` + [`docs/INDEX.md`](docs/INDEX.md) 作为**当前入口**
- 将 `docs/_archive/` 和 `docs/archive/` 视为**历史存档**
- 通过实时端点（`/health`、`/api/metrics`）和 `kubectl` 验证运行时声明
## 系统功能
- 在 Kubernetes 中监控 IoT 及平台工作负载
- 接入来自 Falco 和 Suricata 转发器的告警
- 执行 LLM 分析（支持 Provider 故障转移；实际可用性取决于密钥/额度/配额）
- 在自动化执行前应用治理策略
- 将告警存储于 PostgreSQL，支持内存降级及自动恢复至数据库
- 提供 Web Dashboard（`/ui`）及运维 API
## 快速开始（演示/本地验证）
### 1. 环境预检
```
bash scripts/pre-demo-check.sh
```
此项检查会验证：
- 集群可达性
- 核心 Pod
- Dashboard/API 可用性
- 登录
- **数据库持久化模式**（并检测 `memory-fallback`）
### 2. 打开 Dashboard
```
xdg-open http://localhost:30800/ui 2>/dev/null || open http://localhost:30800/ui
```
默认演示凭据：
- `admin / admin`
### 3. 运行实时攻击演示（可选）
```
bash scripts/run-live-attacks.sh --duration 30 --show-alerts 3
```
## 访问入口（典型 K3s NodePort 配置）
| Service | URL |
|---|---|
| Dashboard | `http://localhost:30800/ui` |
| Health | `http://localhost:30800/health` |
| Metrics API | `http://localhost:30800/api/metrics` |
| Prometheus | `http://localhost:31106` |
| Grafana | `http://localhost:30300` |
如果你在本地使用 `uvicorn` 运行 `ids-api`，UI/API 可能在 `http://localhost:8000`。
## 项目结构（高层概览）
| Path | Purpose |
|---|---|
| `services/` | IDS API、转发器、服务组件 |
| `smart-city-services/` | IoT 模拟器（交通摄像头、医疗、停车等） |
| `k8s-manifests/` | Kubernetes 清单及平台配置 |
| `scripts/` | 部署、验证、演示及运维自动化脚本 |
| `docs/` | 技术文档、运维手册、Q&A、学术支持、存档 |
| `CAPSTONE_2_REPORT.*` | 最终报告交付物 |
## 文档（权威索引）
从这里开始：
- [`docs/INDEX.md`](docs/INDEX.md) — 权威文档地图 + 信任模型
按受众分类的关键文档：
### 外部专家 / 评审人员
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md)
- [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md)
- [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md)
- [`docs/OPERATIONS.md`](docs/OPERATIONS.md)
### 演示 / 运维人员
- [`docs/DEMO_DAY_RUNBOOK.md`](docs/DEMO_DAY_RUNBOOK.md)
- [`docs/DEMO_QA_CHECKLIST.md`](docs/DEMO_QA_CHECKLIST.md)
- [`docs/DEMO_CHEAT_SHEET.md`](docs/DEMO_CHEAT_SHEET.md)
- [`docs/LLM_CONTROL_AND_TROUBLESHOOTING.md`](docs/LLM_CONTROL_AND_TROUBLESHOOTING.md)
### 学术 / 答辩
- [`docs/EXAMINER_QA_30.md`](docs/EXAMINER_QA_30.md)
- [`docs/EXAMINER_IOT_QA_20.md`](docs/EXAMINER_IOT_QA_20.md)
- [`docs/ACADEMIC_CONTEXT.md`](docs/ACADEMIC_CONTEXT.md)
- [`docs/CAPSTONE_EVIDENCE_MATRIX.md`](docs/CAPSTONE_EVIDENCE_MATRIX.md)
## LLM Provider 说明（运行现状）
系统支持多个 Provider（如 Kimi、xAI、OpenAI、Anthropic、Gemini），但运行时健康状态取决于：
- 有效的 API 密钥
- 配额/计费
- 模型访问权限
- Provider 侧服务中断
Dashboard 显示的 Provider 状态可能是：
- 已配置但不可用（密钥/配额无效）
- 因多次失败处于熔断冷却期
- 运行正常但空闲
这是多 Provider 韧性设计下的预期行为。
## 数据库持久化行为（重要）
`ids-api` 使用 PostgreSQL 作为主存储，当数据库不可用时可降级为内存存储。
近期修复：
- 服务现在会在瞬态数据库启动/竞态失败后**自动重试 DB 连接并恢复至 PostgreSQL**
- `scripts/pre-demo-check.sh` 会显式报告持久化降级
在分享截图/声明前请先执行此检查：
```
curl -s http://localhost:30800/health | jq '{status, storage_type, components}'
```
## 常用命令
```
# 部署代码更改 (基于 ConfigMap 的热重载路径)
bash scripts/deploy-code.sh
# 演示就绪 (更广泛的检查)
bash scripts/demo-readiness.sh --quick
# E2E 验证 (快速)
bash scripts/e2e-verbose-test.sh --quick
# 完整脚本验证
bash scripts/comprehensive-test.sh
```
## 分享本仓库（建议）
在分享给专家前：
1. 运行 `bash scripts/pre-demo-check.sh`
2. 确认数据库已连接（非 `memory-fallback`）
3. 使用 [`docs/INDEX.md`](docs/INDEX.md) 引导他们查看当前文档
4. 避免引用已存档文档作为当前行为依据
## 许可证
参见 [`LICENSE`](LICENSE)。
标签：CISA项目, DLL 劫持, Falco, HTTP/HTTPS抓包, IoT仿真, JSONLines, LLM分析, Metaprompt, PostgreSQL, SOAR, StruQ, Suricata, TGT, Web截图, 入侵检测系统, 大语言模型, 威胁情报, 子域名突变, 安全仪表盘, 安全数据湖, 安全编排与自动化响应, 安全运营中心, 容器安全, 开发者工具, 异常检测, 态势感知, 攻防演练, 敏感词过滤, 智慧城市, 测试用例, 物联网安全, 现代安全运营, 策略控制, 网络安全, 网络映射, 网络流量分析, 自定义请求头, 请求拦截, 逆向工具, 防御治理, 隐私保护, 零信任, 高可用架构