SaudiGuy1/CityShield

# CityShield CityShield 是一个自包含的、容器化的平台，它模拟智慧城市的数字基础设施，针对其生成真实的攻击场景，使用与 MITRE ATT&CK 对齐的检测规则来检测威胁，并执行自动化响应 playbook。它被构建为一个教学和研究环境：每一层——从 3D 城市可视化到抓包网络靶场——都在 Docker Compose 上本地运行。 ## 概述 CityShield 将城市建模为受监控资产（交通信号灯、IoT 传感器中枢、网段）的集合，并在其上运行完整的**检测 → 响应 → 审查**安全工作流： 1. **模拟器** 持续生成真实的流量、IoT 和网络遥测数据。 2. **检测引擎** 根据这些遥测数据评估 75+ 条 YAML 检测规则并发出警报。 3. **响应管理器** 验证自动响应条件并执行 Ansible playbook。 4. 分析师通过 React SOC 控制台对警报进行分类和解决，并查看城市的实时 **3D 数字孪生**。 5. 研究人员在隔离的**研究实验室**中设计攻击场景、调整检测规则并进行工作。 6. 管理人员跟踪团队在**安全意识**方面的进度；整个 UI 是双语的（英语/阿拉伯语）。 OpenSearch 是唯一的单一事实来源——没有关系型数据库。 ## 功能 | 功能 | 描述 | |---|---| | **智慧城市数字孪生** | 交互式 3D 城市（React Three Fiber），其中建筑物代表资产；颜色/高度反映状态和事件量。 | | **攻击模拟** | 针对模拟器和实时网络靶场驱动的内置和自定义攻击场景。 | | **检测引擎** | 75+ 条 YAML 检测规则，涵盖 25+ 种匹配逻辑类型（扫描、暴力破解、C2 beacon、数据泄露、DDoS、勒索软件、横向移动等）。 | | **MITRE ATT&CK 映射** | 精心策划的 MITRE 技术知识库；每条规则和警报都映射到一种技术。 | | **自动化响应** | 12 个 Ansible 响应 playbook（封锁 IP、隔离服务、隔离主机、撤销 token 等），具有基于规则的条件、速率限制和白名单。 | | **SOC 工作流** | 警报分类、手动响应操作、执行历史和完整的审计日志。 | | **警报解决** | 结构化的解决工作流，包含处理结果、备注和解决分析。 | | **研究实验室** | 每用户一个 Ubuntu 容器（nmap、hydra、nikto、tcpdump 等），连接到所有靶场，从 UI 中提供。 | | **安全意识** | 双语培训内容，具有每用户和每团队的进度跟踪。 | | **团队分析** | 针对直接下属意识进度的管理员仪表板。 | | **RBAC** | 五种角色——管理员、分析师、研究员、经理、查看者。 | | **国际化** | 完整的英语/阿拉伯语 UI，支持从右到左（RTL）布局。 | | **深色/浅色主题** | 每个浏览器持久保存的主题切换，具有符合 WCAG 标准的浅色调色板。 | ## 架构 由 Docker Compose 在三个网络上编排的微服务： - `cityshield_network` (bridge) — 所有应用程序服务。 - `cyber_range_net` (内部) — Metasploitable 目标 + Kali 攻击者 + 数据包记录器。 - `iot_range_net` (内部) — IoT 目标 + 数据包记录器。 ``` ┌──────────────┐ ┌──────────────────┐ Browser ───────► │ Frontend │ ─────► │ Backend API │ :3000 │ React/nginx │ /api │ FastAPI :8000 │ └──────────────┘ /ws └────────┬─────────┘ │ ┌───────────────────────────┼──────────────────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌─────────────────┐ ┌────────────────┐ │ OpenSearch │ ◄────────── │ Detection Engine│ │ Response Mgr │ │ :9200 │ │ (rules → alerts)│ │ (Ansible) │ └─────┬──────┘ └─────────────────┘ └────────────────┘ ▲ ┌──────────────┼───────────────┬──────────────────┐ │ │ │ │ ┌───────────┐ ┌───────────┐ ┌──────────────┐ ┌─────────────────┐ │ traffic_ │ │ iot_sim │ │ network_ │ │ scenario_runner │ │ sim │ │ │ │ emulator │ │ │ └───────────┘ └───────────┘ └──────────────┘ └─────────────────┘ └──── logs‑* indices ◄─ Filebeat ◄─ Cyber range / IoT range loggers ``` **数据流：** 模拟器 → `logs-*` 索引 → 检测引擎 → `alerts` → 响应管理器 → Ansible playbook → `action-audit-log`；前端通过 REST `/api/*` 和 WebSocket `/ws/city-telemetry` 读取。 完整设计请参阅 [`docs/architecture.md`](docs/architecture.md)。 ## 技术栈 **前端** — React 18、TypeScript 5、Vite 5、React Three Fiber / drei / postprocessing（3D）、 Recharts、Framer Motion、xterm.js（实验室终端）、axios。在生产环境中由 nginx 提供服务。 **后端** — FastAPI 0.109、Pydantic v2、python‑jose（JWT，HS256）、bcrypt、opensearch‑py、PyYAML、 Docker SDK（研究实验室配置）。Python 3.11。 **数据存储** — OpenSearch 2.11（单节点）+ OpenSearch Dashboards。 **微服务（Python 3.11）** — detection_engine、response_manager、scenario_runner 和三个 模拟器（traffic_sim、iot_sim、network_emulator）。 **网络靶场** — Metasploitable 2（目标）、Kali（攻击者）、tcpdump 数据包记录器；带有 FastAPI IoT 目标的 IoT 靶场。 **基础设施** — Docker Compose、Filebeat（日志传送）、Ansible（12 个响应 playbook）。 ## 用户角色 | 角色 | 权限 | 默认着陆页 | |---|---|---| | **管理员** | 完全访问权限，包括用户管理。 | 概述 | | **分析师** | 对警报进行分类/分析，执行手动响应操作，解决分析。 | 概述 | | **研究员** | 设计场景，管理检测规则，配置自动响应，使用研究实验室。 | 概述 | | **经理** | 查看直接下属的意识进度（团队分析）。 | 团队分析 | | **查看者** | 对安全意识内容的只读访问权限。 | 意识 | RBAC 在后端（`app/core/rbac.py`）强制执行，并在前端的路由守卫中镜像。 ## 安装说明 **前置条件：** Docker Desktop 4.x+（Compose 2.x+），建议 16 GB 内存，约 20 GB 可用磁盘空间。 ``` git clone CityShield cd CityShield cp .env.example .env # then edit secrets — see Environment Variables below docker compose up --build # build and start the full platform ``` 然后打开： | 服务 | URL | |---|---| | 前端（SOC 控制台） | http://localhost:3000 | | 后端 API + Swagger | http://localhost:8000/docs | | OpenSearch | http://localhost:9200 | | OpenSearch Dashboards | http://localhost:5601 | 模拟器（8001–8003）**仅在内部**运行，不会发布到主机。 **默认账户**（在 `.env` 中定义，首次登录后请更改）： | 角色 | 用户名 | 密码 | |---|---|---| | 管理员 | `admin` | `CityShield@Admin2026` | | 研究员 | `researcher` | `CityShield@Researcher2026` | ## Docker 部署 ``` docker compose up --build # build images and start everything docker compose up -d # start in the background docker compose ps # service + health status docker compose logs -f backend # follow a service’s logs docker compose down # stop all services docker compose down -v # stop and wipe volumes (full reset) ``` 仅启动核心应用程序路径（跳过重量级的 Kali / Metasploitable 网络靶场）： ``` docker compose up -d opensearch backend frontend \ traffic_sim iot_sim network_emulator \ detection_engine response_manager scenario_runner dashboards ``` Linux 主机必须先提高 OpenSearch mmap 限制：`sudo sysctl -w vm.max_map_count=262144`。 ## 云端部署 (Railway) CityShield 可以在 [Railway](https://railway.app) 上在线发布以进行演示 **这不会影响本地的 `docker-compose` 工作流**——同样的 Dockerfiles 被重用，通过每个服务对应的 `railway.json` 文件以及运行时模板化的 nginx 配置来选择云行为。 - **已就绪支持云端：** 前端、后端、OpenSearch、三个模拟器、 检测引擎、场景运行器（以及一个降级模式的响应管理器）。 - **仅限本地（在 Railway 上已排除）：** 网络靶场（Kali 风格的攻击者、 Metasploitable、抓包记录器）、IoT 靶场以及 每位研究员专用的 Docker 实验室——它们需要 Docker socket / 原始 socket，这是 Railway 无法提供的。 最快的演示 = 三个服务：`opensearch`（私有）+ `backend` + `frontend` （公开）。添加模拟器 + 检测引擎以获得实时事件和警报。 👉 **完整的分步指南：** [`RAILWAY_DEPLOYMENT.md`](./RAILWAY_DEPLOYMENT.md) （要创建的服务、环境变量、要点击的内容以及已知限制）。 环境变量模板：[`.env.railway.example`](./.env.railway.example)。 ## 环境变量 将 `.env.example` 复制到 `.env` 并进行调整。关键变量： | 变量 | 用途 | 默认值 | |---|---|---| | `OPENSEARCH_URL` / `OPENSEARCH_USER` / `OPENSEARCH_PASS` | 数据存储连接。 | `http://opensearch:9200` / `admin` / … | | `BACKEND_JWT_SECRET` | **请更改此项。** 用于 JWT 的签名密钥（使用 ≥32 个随机字符）。 | placeholder | | `BACKEND_ACCESS_TOKEN_EXPIRE_MINUTES` | Access-token 生命周期。 | `60` | | `CORS_ALLOWED_ORIGINS` | 允许调用 API 的逗号分隔的浏览器源。 | `http://localhost:3000,http://127.0.0.1:3000` | | `DEFAULT_ADMIN_USER` / `DEFAULT_ADMIN_PASS` / `DEFAULT_ADMIN_EMAIL` | 初始化的默认管理员账户。 | `admin` / `CityShield@Admin2026` / … | | `DEFAULT_RESEARCHER_USER` / `DEFAULT_RESEARCHER_PASS` / `DEFAULT_RESEARCHER_EMAIL` | 初始化的默认研究员账户。 | `researcher` / … | | `THREAT_INTEL_PROVIDER` / `ABUSEIPDB_API_KEY` | 警报富化（`mock` 或 `abuseipdb`）。 | `mock` | | `DETECTION_POLL_INTERVAL_SECONDS` / `DETECTION_QUERY_WINDOW_SECONDS` | 检测频率/回溯窗口。 | `30` / `300` | | `RESPONSE_POLL_INTERVAL_SECONDS` / `RESPONSE_ENABLED` | 响应管理器频率 / 主开关。 | `30` / `true` | | `SCENARIO_POLL_INTERVAL_SECONDS` | 场景运行器频率。 | `5` | | `TRAFFIC_SIM_EVENT_RATE` / `IOT_SIM_EVENT_RATE` / `NETWORK_EMULATOR_EVENT_RATE` | 合成事件率。 | `2` / `3` / `1` | | `USE_MOCK_CITY_COMPONENTS` | 用于 3D 城市的确定性演示数据。 | `true` | | `LOG_LEVEL` | 后端/服务日志级别。 | `INFO` | `.env` 已被 git 忽略，**不会**被提交。 ## API 文档 交互式 Swagger UI 位于 **http://localhost:8000/docs**（OpenAPI JSON 位于 `/openapi.json`）。 主要路由组（全部位于 `/api` 下，除 `/auth/login` 和 `/health` 外均受 JWT 保护）： | 组 | 示例 | |---|---| | 认证 (Auth) | `POST /auth/login` | | 用户 (Users) | `GET/POST /users`，角色管理 | | 规则 (Rules) | `GET/POST/PUT /rules`，自动响应配置 | | 场景 (Scenarios) | `GET /scenarios`，启动运行 | | 警报 (Alerts) | `GET /alerts`，解决 | | 操作 (Actions) | `GET /actions`，`POST /actions/execute/{alert_id}`，`GET /actions/audit` | | 设备 (Devices) | `GET /devices`，注册，特定设备的操作 | | 指标 (Metrics) | `GET /metrics`，`/metrics/mttd`，`/metrics/mttr`，`/metrics/accuracy` | | 概览 (Overview) | `GET /overview/stats`，`/overview/city-components` | | 意识 (Awareness) | `GET /awareness/progress/*` | | MITRE | `GET /mitre/techniques` | | 提案 (Proposals) | attack-proposal 审查工作流 | | 实验室 (Lab) | research-lab 配置 | | WebSocket | `GET /ws/city-telemetry` | 详情请参阅 [`docs/api.md`](docs/api.md)。 ## 截图 _在此处添加截图。_ | 视图 | 图像 | |---|---| | SOC 概览 + 3D 城市 | `docs/screenshots/overview.png` _(占位符)_ | | 警报和响应操作 | `docs/screenshots/alerts.png` _(占位符)_ | | 检测规则 | `docs/screenshots/rules.png` _(占位符)_ | | 安全意识 | `docs/screenshots/awareness.png` _(占位符)_ | ## 项目结构 ``` CityShield/ ├── backend/ # FastAPI backend │ ├── app/ │ │ ├── main.py # entry point: startup seeding, routers, CORS, WebSocket │ │ ├── api/ # 16 route modules + threat_knowledge │ │ ├── core/ # config, security (JWT/bcrypt), rbac │ │ ├── models/ # Pydantic models │ │ ├── services/ # business logic (attack engine, metrics, actions, …) │ │ ├── db/ # OpenSearch client + index mappings │ │ ├── data/ # detection_rules.json, mitre_techniques.json │ │ └── utils/ # logging │ └── tests/ # pytest suite (79 tests) ├── frontend/ # React + TypeScript + Vite │ └── src/ │ ├── pages/ # Overview, Alerts, Rules, Devices, scenarios, … │ ├── components/ # UI + 3D smart‑city (smartcity/) │ ├── hooks/ # data, websocket, theme, language │ └── i18n/ # EN/AR dictionary ├── services/ # microservices │ ├── detection_engine/ # rule runtime + 75 YAML rules + enrichment │ ├── response_manager/ # Ansible executor + playbooks_map.yml │ ├── scenario_runner/ # drives simulators from scenario_runs │ ├── simulators/ # traffic_sim, iot_sim, network_emulator │ ├── attacker/ range_logger/ # cyber range (Kali + tcpdump) │ ├── iot_target/ iot_range_logger/ │ └── researcher-lab/ # per‑user lab image ├── infrastructure/ │ ├── ansible/playbooks/ # 12 response playbooks │ ├── filebeat/ # log shipping config │ └── dashboards/ # OpenSearch saved objects ├── scripts/ # bootstrap, metrics, dataset, verification scripts ├── data/sample/ # sample log events ├── docs/ # technical docs (architecture, threat model, API, rules, …) │ └── academic/ # academic deliverables: report, paper, slides, proposals (non‑runtime) ├── docker-compose.yml # 17 services, 3 networks, 2 volumes ├── .env.example # environment template ├── SETUP_GUIDE.md # macOS & Windows setup guide ├── SECURITY_REPORT.md # security review & hardening checklist └── README.md ``` ## 安全特性 - **JWT 认证**（HS256），使用 bcrypt 哈希密码。 - **基于角色的访问控制**在每个受保护路由的服务器端强制执行。 - **可配置的 CORS 允许列表**（`CORS_ORIGINS`）——不允许带凭据的通配符。 - **通过环境变量管理密钥**（`.env`，被 git 忽略）；没有密钥提交到仓库。 - **网络隔离**——网络靶场和 IoT 靶场运行在 `internal` Docker 网络上。 - 用于应用程序/模拟器镜像的**非 root 容器**。 - 在 `action-audit-log` 中对每个响应操作进行**完整的审计日志记录**。 - 自动响应的**逐规则护栏**：最低严重性、富化要求、速率限制、 冷却时间、子网白名单和可选的人工确认。 ## 未来工作 源自当前实现： - 启用 OpenSearch 安全插件 + TLS（目前为了本地使用而禁用）。 - 在 `/auth/login` 上添加 API 速率限制 / 暴力破解保护。 - 扩大自动化测试覆盖率（后端集成测试；前端单元/E2E 测试）。 - 对庞大的前端包（3D + 重量级页面）进行代码拆分，以加快初始加载速度。 - 针对生产环境的外部密钥管理（Vault / 云密钥管理器）。 - 用于多节点 / 高可用部署的 Kubernetes manifests。 ## 快速开始 / 完整设置指南 刚接触该项目？请按照分步的、特定于操作系统的指南进行操作： **➡ [SETUP_GUIDE.md](SETUP_GUIDE.md)**（macOS 和 Windows）。 ## 许可证 参见 [LICENSE](LICENSE)。

标签：AMSI绕过, Docker Compose, IP 地址批量处理, PE 加载器, 威胁检测, 安全运营, 安全靶场, 扫描框架, 插件系统, 攻击模拟, 数字孪生, 智慧城市, 版权保护, 系统提示词, 自动化响应, 自动化攻击, 驱动签名利用