sadiasakharkar/ShadowGraph-Hackathon

# ShadowGraph-Hackathon - AI 数字孪生与身份智能平台 本代码库（`ShadowGraph-Hackathon`）是一个全栈黑客马拉松项目，旨在构建一个模块化的网络安全平台，用于建立和监控数字身份孪生。 ## 核心系统 - 数字身份孪生引擎：基于公共身份信号创建由图数据库支持的孪生体。 - 身份图谱智能：在 Neo4j 中映射身份节点/关系以供探索。 - AI 身份指纹识别：用户名、风格计量、图像 embedding 和异常分析。 - 身份威胁模拟引擎：生成加权风险评分和威胁类别。 - 自主身份防御系统：生成上下文保护警报和行动。 ## Monorepo 结构 ``` ShadowGraph-Hackathon/ frontend/ components/ pages/ three-visualization/ hooks/ services/ styles/ backend/ app/ api/ services/ models/ graph/ security/ ai-services/ app/ image-analysis/ text-analysis/ anomaly-detection/ graph-engine/ graph_engine/ data-pipelines/ scrapers/ identity-matching/ database/ mongo/ neo4j/ infrastructure/ docker/ config/ ``` ## 架构概览 - 前端 (`Next.js + TypeScript + Tailwind + Framer Motion + React Three Fiber`) - 落地页、注册/登录、身份设置、电影化仪表盘。 - 带有可疑（红色光晕）和已验证（绿色光晕）节点的 3D 旋转图谱。 - 节点点击/悬停元数据检查。 - 后端 (`FastAPI`) - 身份验证 (`/api/auth/register`, `/api/auth/login`, Google/GitHub OAuth) - 身份获取 (`/api/identity/signals`) - 身份扫描 + 孪生生成 (`/api/identity/scan`) - 异步扫描编排 (`/scan/start`, `/scan/status`, `/scan/results`) - 版本化图 API (`/graph/latest`, `/graph/version/{id}`) - 威胁模拟 API (`/risk/analysis`) - 风险检索 (`/api/identity/risk`) - 图谱检索 (`/api/graph`) - 警报和防御生命周期 (`/alerts`) - AI 代理路由 (`/api/ai/*`) - AI 服务 (`FastAPI + PyTorch + sklearn`) - `/image-embedding` - `/username-similarity` - `/stylometric-similarity` - `/anomaly-detection` - `/ai/username-similarity` - `/ai/image-similarity` - `/ai/text-similarity` - 数据层 - MongoDB：用户、扫描结果、警报上下文。 - Neo4j：身份图谱节点/边。 - Redis：风险缓存和队列就绪缓存层。 ## 风险评分算法 威胁模拟引擎计算： ``` overall = 0.34*duplication + 0.27*content_misuse + 0.22*deepfake + 0.17*network_anomaly ``` 风险类别： - `critical` >= 0.75 - `high` >= 0.50 - `medium` >= 0.30 - `low` < 0.30 信号包括用户名冲突、头像复用、写作风格重叠和图谱异常。 ## 获取流水线 - 适配器： - GitHub 公开资料 - 公开网站资料 - 跨平台的通用用户名发现 - 资料图像元数据 - 原始信号存储在 MongoDB 集合：`raw_identity_signals`。 - 归一化信号存储在 MongoDB 集合：`normalized_identity_signals`。 - Redis 队列键 `scan_jobs` 支持异步扫描 worker。 - 图谱引擎消费归一化信号以构建 Neo4j 图节点/边。 ## 图谱智能引擎 - Neo4j 类型化 schema： - 节点：`UserIdentity`, `Account`, `Image`, `TextArtifact`, `Repository` - 边：`HAS_ACCOUNT`, `HAS_IMAGE`, `SIMILAR_USERNAME`, `SIMILAR_IMAGE`, `SIMILAR_TEXT`, `CONNECTED_TO` - 每次扫描都会创建一个图谱快照版本 (`GraphVersion`) 并将发现的实体链接到该版本。 - 每个节点和边存储： - `confidence_score` - `source` - `timestamp` - 版本元数据也持久化在 MongoDB 集合 `graph_versions` 中。 - 图谱 schema 详情：`docs/GRAPH_SCHEMA.md`。 ## ML 身份指纹识别流水线 - 用户名相似度流水线： - 数据集：`ai-services/datasets/username_pairs.csv` - 模型：`ai-services/models/username_similarity_model.joblib` - 图像身份流水线： - 数据集：`ai-services/datasets/image_pairs.csv` - 来自 ResNet18 特征提取器的 embedding - 模型：`ai-services/models/image_similarity_model.joblib` - 风格计量文本流水线： - 数据集：`ai-services/datasets/text_pairs.csv` - 特征：句子长度、词汇分布、标点符号模式 - 模型：`ai-services/models/text_similarity_model.joblib` - 评估报告： - `ai-services/reports/evaluation_report.md` - `ai-services/reports/evaluation_summary.json` - 完整流水线指南：`docs/ML_PIPELINES.md`。 ## 威胁模拟引擎 - 从最新的身份图谱模拟攻击路径： - 虚假账户创建 - 图像复用 - 用户名冒充 - 计算： - 攻击可能性 - 影响范围 - 目标平台影响 - 返回可解释的输出： - 风险评分 - 风险因素 - 受影响节点 - 建议措施 - API： - `GET /risk/analysis` ## 引导演示模式 - 仪表盘支持带有种子图谱/风险/警报数据的确定性演示模式。 - 启用方式： - 打开 `http://localhost:3001/dashboard?demo=1` - 或在仪表盘内点击 `Start Guided Demo`。 - 演示模式以固定输出模拟扫描时间线，用于可重复的黑客马拉松演示。 - 离线回退：如果后端 API 不可用，仪表盘会自动切换到种子演示数据。 ## 自主防御工作流 - 将威胁模拟和风险洞察转化为可执行的剧本： - 举报冒充账户 - 启用多因素身份验证 - 保护暴露的资料 - 警报生命周期状态： - `open` - `acknowledged` - `resolved` - API： - `GET /alerts` - `POST /alerts/{id}/acknowledge` - `POST /alerts/{id}/resolve` ## 环境变量 复制 `.env.example` 并根据需要调整： - `NEXT_PUBLIC_API_BASE_URL` - `MONGO_URI`, `MONGO_DB` - `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` - `REDIS_URL` - `JWT_SECRET`, `JWT_ALGORITHM` - `AI_SERVICE_URL` - `CORS_ORIGINS` - `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` - `JWT_AUDIENCE`, `JWT_ISSUER` - `RATE_LIMIT_REQUESTS_PER_MINUTE`, `RATE_LIMIT_WINDOW_SECONDS` - `APP_ENV`, `APP_RELEASE` - `SENTRY_DSN`, `SENTRY_TRACES_SAMPLE_RATE` - `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` - `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` 创建本地运行环境文件： ``` cp .env.example .env ``` ## 可观测性与安全性 - 带有 request-id 关联 (`X-Request-ID`) 的结构化 JSON 日志。 - 通过 `SENTRY_DSN` 可选的 Sentry 错误跟踪。 - 默认启用响应安全头。 - JWT 加固： - audience 和 issuer 声明验证 - 强制执行 `iat`, `nbf`, 和 `exp` - 可配置的 access-token TTL - API 限流中间件： - 请求窗口和最大请求数由环境驱动。 ## 使用 Docker 运行 从代码库根目录（`ShadowGraph-Hackathon/`）： ``` docker compose up --build ``` 服务： - 前端：[http://localhost:3001](http://localhost:3001) - 后端：[http://localhost:8001/docs](http://localhost:8001/docs) - AI 服务：内部容器服务（后端可通过 `http://ai-services:8100` 访问） - Neo4j 浏览器：[http://localhost:7474](http://localhost:7474) 健康检查端点： - 后端服务：`GET /health/backend` - 数据库连接 (MongoDB + Neo4j + Redis)：`GET /health/database` - 从后端到 AI 的连接：`GET /health/ai` ## 本地开发（不使用 Docker） 前端： ``` cd frontend npm install npm run dev ``` 后端： ``` cd backend pip install -r requirements.txt uvicorn app.main:app --reload --port 8000 ``` AI 服务： ``` cd ai-services pip install -r requirements.txt uvicorn app.main:app --reload --port 8100 ``` ## 测试身份扫描流程 1. 打开前端并创建一个账户。 2. 使用用户名（例如 `demoanalyst`）完成设置。 3. 扫描构建数字孪生并将节点/边写入 Neo4j。 4. 仪表盘加载图谱、风险评分和防御警报。 5. 点击/悬停节点以检查元数据。 ## API 冒烟测试（端到端） 以下序列验证注册、登录、信号获取、扫描触发、图谱检索、风险检索和警报： ``` # register curl -s -X POST http://localhost:8001/api/auth/register \ -H "Content-Type: application/json" \ -d '{"email":"demo_user@shadowgraph.ai","password":"ShadowGraph#123","full_name":"Demo User"}' # login (复制 access_token) curl -s -X POST http://localhost:8001/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"demo_user@shadowgraph.ai","password":"ShadowGraph#123"}' # 提交 signal curl -s -X POST http://localhost:8001/api/identity/signals \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"platform":"github","username":"demoanalyst","profile_url":"https://github.com/demoanalyst","bio_text":"security engineer","image_url":"https://example.com/avatar.png"}' # 运行扫描 curl -s -X POST http://localhost:8001/api/identity/scan \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"root_username":"demoanalyst","seed_platforms":["github","x","linkedin"]}' # 读取 graph/risk/alerts curl -s http://localhost:8001/api/graph -H "Authorization: Bearer " curl -s http://localhost:8001/api/identity/risk -H "Authorization: Bearer " curl -s http://localhost:8001/alerts -H "Authorization: Bearer " ``` ## OAuth 认证设置 - 登录和注册页面均支持 Google 和 GitHub 社交登录。 - 在 `.env` 中配置凭证： - `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` - `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` - 将提供商重定向 URL 设置为： - `http://localhost:3001/auth/callback/google` - `http://localhost:3001/auth/callback/github` - OAuth API： - `GET /api/auth/oauth/{provider}/url?redirect_uri=...` - `POST /api/auth/oauth/{provider}/callback` ## 自动化测试 - API 测试 + 集成测试： - `./scripts/run_api_tests.sh` - UI 冒烟测试 (Playwright)： - `./scripts/run_ui_smoke.sh` ## 生产与演示文档 - 生产部署：`docs/PRODUCTION_DEPLOYMENT.md` - 评委演示剧本：`docs/JUDGE_DEMO_RUNBOOK.md` - 一键评委演示脚本：`./scripts/hackathon_judge_demo.sh` ## 获取扫描队列 API ``` # 开始异步 ingestion 扫描 curl -s -X POST http://localhost:8001/scan/start \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"identity_id":"demo-id-1","username":"torvalds","website_url":"https://github.com/torvalds","profile_image_url":"https://avatars.githubusercontent.com/u/1024025?v=4","platforms":["github","x","linkedin","instagram"]}' # 轮询状态 curl -s "http://localhost:8001/scan/status?scan_id=" -H "Authorization: Bearer " # 获取聚合 result payload curl -s "http://localhost:8001/scan/results?scan_id=" -H "Authorization: Bearer " ``` ## 种子数据 - `database/mongo/seed.json` 包含一个演示账户文档。 - `database/neo4j/seed.cypher` 包含一个样本可疑身份关系。 ## 安全与抓取说明 - 抓取工具是模块化的，仅限于公开页面。 - Selenium 扫描器是可选的，默认禁用。 - 此 MVP 专为黑客马拉松和演示用途设计；生产加固应增加： - 健壮的密码策略和 refresh token 流程， - 特定平台的法律合规性检查， - 签名的抓取任务队列和审计日志。

标签：3D可视化, AI安全, AV绕过, Chat Copilot, Docker, FastAPI, MongoDB, Neo4j, OAuth, React Three Fiber, TypeScript, 凭据扫描, 命令控制, 图像分析, 图智能, 安全插件, 安全防御评估, 实时处理, 异常检测, 搜索引擎查询, 数字孪生, 数字身份, 数据采集, 文本分析, 深度伪造检测, 网络安全, 请求拦截, 身份威胁检测, 逆向工具, 隐私保护, 黑客马拉松