cyclonite69/shadowcheck-web

# ShadowCheck - SIGINT 取证平台 [](https://github.com/cyclonite69/shadowcheck-static/stargazers) [](https://github.com/cyclonite69/shadowcheck-static/network) [](https://github.com/cyclonite69/shadowcheck-static/issues) [](LICENSE) [](https://nodejs.org/) [](https://www.postgresql.org/) [](https://redis.io/) [](https://github.com/cyclonite69/shadowcheck-static/commits) [](https://github.com/cyclonite69/shadowcheck-static) 🛡️ **生产级 SIGINT 取证和无线网络分析平台。** 实时威胁检测、通过 PostGIS 进行地理空间关联以及交互式分析仪表板。 ## 当前系统状态 - **React/Vite 前端** 已完全集成 TypeScript 支持（`client/src/` 路由如 `/geospatial-intel`、`/analytics`、`/ml-training`、`/endpoint-test`） - **现代模块化后端架构**，在 `server/src/api/`、`server/src/services/` 和 `server/src/repositories/` 中组织服务 - **集成资产服务**：主 Express 服务器原生提供来自 `dist/` 的编译前端资产，并带有优化的安全标头 - **通用过滤器系统**，支持 20 多种过滤器类型，支持跨所有页面进行复杂查询 - **DevContainer 支持**，通过 VS Code 集成提供一致的开发环境 - **静态服务器**，具有用于生产部署和 Lighthouse 审计的安全标头 - **PostGIS 物化视图**，用于具有预计算威胁情报的快速浏览器页面 - **ETL 管道**位于 `etl/` 中，具有模块化的加载/转换/提升步骤，为浏览器视图提供数据；暂存表保持 UNLOGGED 以提高摄入速度 - **机器学习**，支持多种算法（逻辑回归、随机森林、梯度提升）和超参数优化 - **Redis 集成**处理缓存、会话管理和速率限制 ## 功能 - **仪表板：** 具有威胁指示器和交互式指标卡的实时网络环境概览。 - **地理空间分析：** 具有空间关联、聚类、热力图、路线和 **统一网络工具提示** 的交互式 Mapbox 可视化。 - **天气 FX 系统：** 具有雨/雪粒子效果、动态雾和观测点历史天气查询的实时大气可视化。 - **机构办公室数据集：** [新增] 56 个外地办事处（100% ZIP+4 覆盖率）和 334 个驻点机构（93.4% ZIP+4 覆盖率），带有用于地理空间关联的 PostGIS 坐标点。 - **地理空间浏览器：** 具有叠加层和时间线视图的基于地图的网络探索。 - **网络分析：** 通过通用过滤深入分析单个网络特征和行为模式。 - **威胁检测：** 通过多种算法进行 ML 驱动的监控设备和异常识别。 - **分析统计：** 通过 Chart.js 可视化进行网络模式分析的高级图表和图形。 - **地址丰富：** 多 API 场所和业务识别（4 个来源：OpenCage、LocationIQ、Abstract、Overpass）。 - **设备分类：** 自动识别设备类型和行为分析。 - **网络标记：** 手动分类和标记检索网络。 - **三边测量：** 通过多次观测进行 AP 位置计算及精度估算。 - **机器学习：** 具有超参数优化和模型版本控制的多算法威胁检测。 - **通用过滤器：** 20 多种过滤器类型，支持复杂的时间、空间和行为查询。 - **WiGLE 集成：** 本地 WiGLE 数据库搜索及实时 API 查询。 - **Kepler 集成：** 支持过滤器的 Kepler.gl 就绪 GeoJSON 端点。 - **家庭位置和标记：** 保存的位置及距家庭距离过滤器。 - **数据导出和备份：** CSV/JSON/GeoJSON 导出以及管理员保护的备份。 - **身份验证和角色：** 基于会话的登录及管理员门控操作。 - **管理员设置：** 由 AWS Secrets Manager 支持的 Mapbox/WiGLE/Google Maps 配置。 - **DevContainer 支持：** 通过 VS Code 集成提供一致的开发环境。 - **安全标头：** 具有 CSP、HTTPS 强制和 Lighthouse 优化的生产就绪部署。 - **管理员功能：** 系统管理界面，具有配置管理、用户设置和基于角色的门控。 - **管理员数据库安全**：多用户模型，包含只读的 `shadowcheck_user` 和特权的 `shadowcheck_admin`。 完整功能目录请参见 `docs/FEATURES.md`。 ## Kepler.gl 数据策略 - 除非通过查询参数明确请求，否则 Kepler 端点 **无默认限制**。 - 使用过滤器代替上限；Kepler.gl 专为大型数据集设计。 ## 近期改进（2026 年 2 月） ✅ **机构办公室数据集完成** - **外地办事处**：共 56 个，56 个 ZIP+4 (100%)，0 个仅 ZIP5。 - **驻点机构**：共 334 个，312 个 ZIP+4 (93.4%)，22 个仅 ZIP5。 - **数据完整性**：所有 390 条主要记录中，0 个缺失的城市、州、邮政编码、电话、网站或坐标。 - **标准化**：完整的地址和电话标准化（10 位数字）并保留原始值。 ✅ **天气 FX 和大气可视化** - **实时天气叠加**：基于地图中心的实时 Open-Meteo 数据，提供动态雾、雨和雪效果。 - **粒子系统**：基于 canvas 的高性能粒子引擎，实现逼真的雨（垂直条纹）和雪（正弦飘动）效果。 - **历史天气背景**：通过后端代理查看任何过去观测点的天气状况（温度、气压、能见度）。 - **后端代理**：新的 `/api/weather` 端点，用于安全地获取外部天气数据，而不会暴露密钥或触发 CSP 问题。 ✅ **TypeScript 迁移和构建管道** - **完整的 TypeScript 迁移**：转换了 60 多个文件，包括服务器实用程序、中间件、ETL 脚本和构建工具 - **生产构建管道**：用于 Docker 部署的编译 TypeScript 服务器消除了运行时 ts-node 开销 - **类型安全**：为数据库操作、API 响应和服务层添加了全面的接口和类型 - **构建优化**：前端和服务器分别编译，具有适合容器化部署的路径解析 ✅ **Redis 实施** - **威胁分数缓存**：Redis 以 5 分钟为间隔缓存威胁分数。 - **分析缓存**：Redis 缓存分析聚合数据。 - **会话管理**：Redis 处理会话存储。 - **速率限制**：Redis 后端强制执行每个 IP 15 分钟内 1000 次请求的限制。 ✅ **数据完整性修复** - 修复了 GeoSpatial 表显示不正确默认值的问题（signal: 0 dBm, channel: 0, frequency: 0 MHz） - 解决了分析小部件故障（时间活动、随时间变化的无线电类型、威胁分数趋势） - 修复了最大距离计算，使用真实的 PostGIS 地理距离而不是约 238m 的信号近似值 - 解决了威胁分数列排序问题（rule_score、ml_score、ml_weight、ml_boost 现已可排序） ✅ **API 和后端改进** - Networks API 现在使用最新观测数据以获取准确的实时信息 - 通过带有 OUI 前缀匹配的 radio_manufacturers 表添加了制造商字段填充 - 修复了 WiGLE 观测点渲染，使用了正确的 schema 命名空间（app 与 public） - 增强了分析端点，具有适当的空值处理和适当的数据源 ✅ **前端增强** - 修复了数据转换器字段名称不匹配问题（network_type → type, avg_score → avgScore） - 为 temporal、radio-time 和 threat-trends 分析添加了缺失的 API 调用 - 改进了地理距离显示和无效值处理 ✅ **测试和质量** - 为 networks API 数据完整性添加了全面的回归测试 - 增强了所有端点的错误处理和验证 ## 架构 **后端：** Node.js/Express REST API，配合 PostgreSQL + PostGIS + Redis（具有 Repositories 和 Services 的模块化架构） **前端：** React + Vite 配合 TypeScript（浏览器和仪表板） **数据库：** PostgreSQL 18 配合 PostGIS 扩展（566,400+ 位置记录，173,326+ 唯一网络） **缓存：** Redis v4+ 用于会话、速率限制和分析 **开发：** DevContainer 支持，配合 VS Code 集成 **部署：** 生产构建通过 `server/server.ts` 中的集成资产处理程序提供服务。 ## 前置条件 - Node.js 20+ - PostgreSQL 18+ 配合 PostGIS - Redis 4.0+ - TypeScript 5.0+（包含在 devDependencies 中） ## 快速开始 ### 本地开发 ``` git clone https://github.com/cyclonite69/shadowcheck-static.git cd shadowcheck-static npm install docker-compose up -d ``` ### 家庭实验室部署 ``` git clone https://github.com/cyclonite69/shadowcheck-static.git cd shadowcheck-static ./deploy/homelab/scripts/setup.sh ``` 硬件要求和详细设置请参见 [deploy/homelab/README.md](deploy/homelab/README.md)。 ### AWS 生产环境 **🚀 快速开始：** 参见 [deploy/aws/QUICKSTART.md](deploy/aws/QUICKSTART.md) ``` # 启动实例（从本地机器） ./deploy/aws/scripts/launch-shadowcheck-spot.sh # 通过 SSM 连接 aws ssm start-session --target INSTANCE_ID --region us-east-1 # 运行自动设置 bash curl -fsSL https://raw.githubusercontent.com/cyclonite69/shadowcheck-static/master/deploy/aws/scripts/setup-instance.sh | sudo bash cd /home/ssm-user git clone https://github.com/cyclonite69/shadowcheck-static.git shadowcheck cd shadowcheck ./deploy/aws/scripts/deploy-complete.sh # 更新部署 git pull origin master ./deploy/aws/scripts/scs_rebuild.sh ``` **文档：** - [QUICKSTART.md](deploy/aws/QUICKSTART.md) - 完整部署指南 - [WORKFLOW.md](deploy/aws/WORKFLOW.md) - 开发工作流 - [README.md](deploy/aws/README.md) - AWS 基础设施详情 - [DEPLOYMENT_CHECKLIST.md](deploy/aws/DEPLOYMENT_CHECKLIST.md) - 验证清单 - [ssm-embedded-session-policy.json](deploy/aws/iam/ssm-embedded-session-policy.json) - Admin UI 嵌入式 SSM 所需的 IAM 策略 ## 详细设置 ### 1. 克隆并安装 ``` git clone https://github.com/your-username/shadowcheck-static.git cd shadowcheck-static npm install ``` ### 2. 数据库和 Redis 设置 使用 Docker 进行本地设置（推荐），以便 PostGIS、Redis、bootstrap 授权和迁移保持同步： ``` docker compose up -d ``` 对于 AWS/EC2，请使用 `deploy/aws/scripts/` 中的部署脚本（特别是 `scs_rebuild.sh`），而不是手动运行遗留 SQL。 ### 3. 环境配置 在 AWS Secrets Manager 中配置密钥，并通过环境变量导出任何本地覆盖： ``` DB_USER=shadowcheck_user DB_HOST=shadowcheck_postgres DB_NAME=shadowcheck_db DB_PASSWORD=your_password DB_PORT=5432 REDIS_HOST=shadowcheck_static_redis REDIS_PORT=6379 PORT=3001 ``` 有关非密钥选项，请参见 `.env.example`。 ### 4. 运行迁移 迁移由标准运行器应用： ``` # Local/dev docker compose up -d # AWS/EC2 ./deploy/aws/scripts/scs_rebuild.sh ``` 如果必须手动运行，请使用 `sql/run-migrations.sh`，并使用部署脚本所用的相同凭据和 schema/search_path 设置。 ### 5. 启动服务器 ``` npm start ``` 服务器运行在 `http://localhost:3001` ## 页面 - 仪表板 (React): `/` 和 `/dashboard` - 地理空间情报 (React): `/geospatial` 或 `/geospatial-intel` - 地理空间浏览器 (React): `/geospatial-explorer` - 分析统计 (React): `/analytics` - API 测试 (React): `/endpoint-test` - ML 训练 (React): `/ml-training` - 管理: `/admin` - WiGLE (React): `/wigle` - Kepler (React): `/kepler` ## API 端点 ### 网络和观测 - `GET /api/networks` - 具有通用过滤的分页网络列表 - `GET /api/v2/networks` - 版本 2 分页网络 API - `GET /api/networks/observations/:bssid` - 特定网络的所有观测记录 - `GET /api/networks/search/:ssid` - 按 SSID 搜索网络 - `GET /api/networks/tagged` - 列出用户标记的网络 - `GET /api/location-markers` - 检索保存的地图标记 - `GET /api/home-location` - 获取当前家庭/基地坐标 ### 威胁分析和 ML - `GET /api/threats/quick` - 高性能威胁检测概览 - `GET /api/threats/detect` - 详细的基于移动的取证分析 - `GET /api/ml/status` - 检查 ML 模型训练状态和统计信息 - `POST /api/ml/train` - 在标记数据上触发 ML 模型重训练 ### 分析和情报 - `GET /api/analytics/dashboard-metrics` - 仪表板卡的关键指标 - `GET /api/analytics/*` - 各种统计分布端点（时间、信号等） - `GET /api/weather` - 用于地图叠加的当前天气代理 (Open-Meteo) - `GET /api/wle/api-status` - 检查 WiGLE API 连接 - `GET /api/mapbox-token` - 安全检索 Mapbox API token ### 数据管理和管理员 - `POST /api/network-tags/:bssid` - 手动分类网络 (管理员) - `POST /api/admin/import-sqlite` - Turbo SQLite 数据库导入 (管理员) - `POST /api/admin/cleanup-duplicates` - 删除冗余观测数据 (管理员) - `GET /api/export/networks` - 将过滤后的网络导出为 CSV/JSON - `POST /api/admin/aws/instances/:id/start` - 启动 EC2 实例 (管理员) - `POST /api/admin/aws/instances/:id/stop` - 停止 EC2 实例 (管理员) ### 身份验证 - `POST /api/auth/login` - 基于会话的身份验证 - `POST /api/auth/logout` - 使当前会话失效 - `GET /api/auth/status` - 检查当前身份验证状态 实现详情请参见 `server/server.ts` 和 `server/src/utils/routeMounts.ts`。 ## 机器学习 ShadowCheck 包含多算法威胁检测，具有模型训练和超参数优化功能。 ### 训练端点 **POST** `/api/ml/train` 在数据库中所有标记网络上训练逻辑回归模型。 **请求：** ``` curl -X POST http://localhost:3001/api/ml/train ``` **响应：** ``` { "ok": true, "model": { "type": "logistic_regression", "accuracy": 0.92, "precision": 0.88, "recall": 0.95, "f1": 0.91, "rocAuc": 0.94 }, "trainingData": { "totalNetworks": 45, "threats": 18, "falsePositives": 27 }, "message": "Model trained successfully" } ``` **错误：** - `400`：少于 10 个标记网络（最低要求） - `503`：ML 模型模块不可用 ### 状态端点 **GET** `/api/ml/status` 检查模型训练状态和标记统计信息。 ### 高级 ML 迭代 通过网格搜索和交叉验证测试多种算法： ``` pip install -r scripts/ml/requirements.txt python3 scripts/ml/ml-iterate.py ``` 测试 Logistic Regression、Random Forest 和 Gradient Boosting 并进行超参数调优。 ### 用于训练的特征 - 观测计数（网络检测） - 看到的唯一天数 - 地理分布（位置聚类） - 信号强度（RSSI 最大值） - 距家庭位置的距离范围 - 行为标志（在家与外出时看到） ## 项目结构 ``` shadowcheck-static/ ├── client/ │ ├── src/ │ │ ├── components/ # ⚛️ React components (TypeScript) │ │ ├── App.tsx # ⚛️ Main React app │ │ └── main.tsx # ⚛️ Frontend entry point │ └── vite.config.ts # ⚛️ Frontend build config (TypeScript) ├── server/ │ ├── src/ │ │ ├── api/ # 🔧 REST API routes (TypeScript) │ │ ├── services/ # 🔧 Business logic (TypeScript) │ │ ├── middleware/ # 🔧 Express middleware (TypeScript) │ │ └── utils/ # 🔧 Server utilities (TypeScript) │ ├── server.ts # 🔧 Main server entry point │ └── static-server.ts # 🛠️ Benchmark static server ├── deploy/ # 🚀 Deployment configs (AWS, etc.) │ └── aws/ # AWS-specific deployment ├── etl/ # 📊 ETL pipeline (TypeScript) ├── scripts/ # 🛠️ Utility scripts (TypeScript) ├── tests/ # 🧪 Jest tests (TypeScript) ├── sql/ # 🗄️ Database migrations & functions ├── docs/ # 📚 Documentation ├── tsconfig.json # ⚙️ TypeScript config (client) ├── tsconfig.server.json # ⚙️ TypeScript config (server) └── docker-compose.yml # 🐳 Docker configuration ``` **📖 详细的前端/后端组织请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。** 文档索引另请参见 [docs/README.md](docs/README.md)。 ## 开发 **运行开发服务器：** ``` npm run dev ``` **运行测试：** ``` npm test ``` ## 配置 关键环境变量（参见 `.env.example`）： - `DB_*` - PostgreSQL 连接 - `REDIS_*` - Redis 连接 - `PORT` - 服务器端口（默认值：3001） - `NODE_ENV` - development 或 production ## 安全 - 在生产环境中使用强数据库凭据。 - 每 60-90 天轮换密码（参见 `deploy/aws/docs/PASSWORD_ROTATION.md`）。 - 在反向代理层启用 HTTPS/TLS。 - 通过速率限制限制 API 访问（通过 Redis 启用）。 - 详细的安全指南请参见 `SECURITY.md`。 ### 安全标头和 Lighthouse 审计 为了进行准确的 Lighthouse 最佳实践审计，请使用基准静态服务器： ``` npm run build npm run serve:dist # 然后针对 http://localhost:4000 运行 Lighthouse ``` 集成服务器（`server/server.ts`）默认也应用高安全性标头。 ### 第三方 Cookie 通知 **预期的 Lighthouse 警告：** 来自 `api.mapbox.com` 的“使用第三方 Cookie”。 这是使用 Mapbox GL JS 时的预期行为。Mapbox 设置 Cookie 用于： - 会话管理和速率限制 - 遥测（可以通过 `mapboxgl.config.COLLECT_TELEMETRY = false` 禁用） - 瓦片缓存 这些 Cookie 是 Mapbox 功能所必需的，如果不自托管所有地图瓦片，则无法消除。 ### SEO 索引 默认情况下，`robots.txt` 禁止所有爬取（开发/预发布）。对于生产环境： ``` npm run build:public # Sets ROBOTS_ALLOW_INDEXING=true ``` ## 文档 `docs` 目录中提供了其他文档。导航请参见 [docs/README.md](docs/README.md)。 ## 维基（图表和视觉文档） `.github/wiki/` 中的维基包含重图表文档，是架构和流程视觉的主要来源。 - [维基首页](.github/wiki/Home.md) - [架构 (维基)](.github/wiki/Architecture.md) - [数据流 (维基)](.github/wiki/Data-Flow.md) - [部署指南 (维基)](.github/wiki/Deployment-Guide.md) ## 贡献 代码标准和工作流请参见 `CONTRIBUTING.md`。 ## 行为准则 参见 `CODE_OF_CONDUCT.md`。 ## 许可证 MIT。详情请参见 `LICENSE`。

标签：DFIR, Express, GEOINT, GNU通用公共许可证, HTTP/HTTPS抓包, MITM代理, Node.js, PostGIS, PostgreSQL, React, Redis, SIGINT, Syscalls, TypeScript, Vite, 代码示例, 位置追踪, 信号情报, 前端仪表盘, 后端架构, 地理空间情报, 安全插件, 实时威胁检测, 态势感知, 插件系统, 搜索引擎查询, 数据分析, 无线网络分析, 测试用例, 网络安全, 自动化攻击, 请求拦截, 逆向工具, 隐私保护