AhmedamineJebali1/active-directory-audit-platform

**AD Audit AI** 是一个多用户平台，可自动化对 Active Directory 环境的安全审计。上传 BloodHound JSON 或 ZIP 导出文件——或通过 LDAP 直接连接到域控制器——该平台将提取每条通往特权账户的可行攻击路径，使用可插拔的 LLM 对其进行评分，将每一跳映射到 MITRE ATT&CK，并生成可交付的法语版 PDF 报告。 ## 功能 | | | |---|---| | **真正的 BloodHound CE 支持** | 解析实际的 SharpHound 2.x / BloodHound CE v6 ZIP 格式、BloodHound v5 JSON、BloodHound v4 分区格式以及简单的自定义格式。与语言环境无关——适用于法语 / 德语 / 英语域控制器 | | **正确合成 DCSync** | 对 Domain 对象同时拥有 `GetChanges` 和 `GetChangesAll` 权限的主体将生成一个合成的 `DCSync` 边——与 BloodHound 自身的推导逻辑相匹配 | | **实时 LDAP 收集** | 连接到域控制器（LDAP 或 LDAPS），解析用于 ACL 边的二进制安全描述符，解析 `primaryGroupID`、`msDS-AllowedToDelegateTo`、`msDS-AllowedToActOnBehalfOfOtherIdentity`、`sIDHistory`、Kerberoastable、AS-REP roastable。基于 SMB 的边（AdminTo、HasSession 等）会被明确标记为启发式方法 | | **AI 驱动的评分** | 可插拔的 LLM 提供商——Mistral、Gemini、OpenAI、Anthropic、OpenRouter、Ollama。通过 `response_format` 强制执行严格的 JSON 输出。当 LLM 不可用时提供启发式后备方案，确保平台绝不会产生空结果 | | **MITRE ATT&CK 矩阵** | 将每一条 BloodHound 边映射到 MITRE 技术。任务视图展示按检测次数着色的战术 × 技术热力图 | | **PDF 报告** | 通过 WeasyPrint + Jinja2 生成的多页样式报告：封面、执行摘要、路径列表、MITRE 附录、ISO 27001 / NIST CSF 合规性映射 | | **带 RBAC 的多用户支持** | 三个全局角色（admin / manager / auditor）加上每个任务的成员资格（lead / contributor / viewer）。每个审计员只能看到他们被添加到的任务 | | **审计日志** | 记录每一个修改性请求（POST/PATCH/PUT/DELETE）及其用户、IP、路由、延迟和状态。提供管理员查看器和过滤 UI | | **邀请 + 重置流程** | 管理员可以通过电子邮件邀请用户；用户通过一次性 token 设置自己的密码。提供带速率限制且无电子邮件枚举的忘记密码流程 | | **实时进度** | 通过 WebSocket 流式传输 pipeline 阶段，并带有 HTTP 轮询后备机制 | | **100% 本地模式** | Ollama 提供商将 AD 数据保留在本地——不会向外部 API 发送任何内容 | ## 快速开始 ### 前置条件 - **Docker** ≥ 24 和 **Docker Compose v2**（运行 `docker compose version` 进行检查） - 一个空闲的 TCP 端口 **443**（如果发生冲突，请在 `docker-compose.yml` 中进行更改） - 约 2 GB 可用磁盘空间（Postgres + Neo4j + 应用镜像） - 可选：LLM API 密钥（Mistral、Gemini、OpenAI、Anthropic 或 OpenRouter）。如果没有，平台将在 **mock** 模式下运行并显示模拟分析 ### 一键设置 ``` # 1. Clone the repo git clone https://github.com/AhmedamineJebali1/active-directory-audit-platform.git cd active-directory-audit-platform # 2. 从模板创建你的 .env cp .env.example .env # 3. 生成一个安全的 secret key（运行以下命令之一并将结果粘贴到 .env 中作为 APP_SECRET_KEY） # Linux/macOS: openssl rand -hex 32 # Windows PowerShell: # [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) # 4. 编辑 .env —— 至少需要包含： # APP_SECRET_KEY=<粘贴上面的输出> # SEED_ADMIN_PASSWORD=<你自己的密码，≥ 12 个字符，混合多种类型> # POSTGRES_PASSWORD=<随机值> # NEO4J_PASSWORD=<随机值> # 5. Launch docker compose up -d --build # 6. 等待约 30 秒让 stack 启动，然后检查： docker compose ps # all services should be "running" / "healthy" docker compose logs backend # look for "db_schema_ready_alembic" # 7. 在浏览器中打开 https://localhost # 开发环境使用自签名 cert —— 接受警告，或者导入 caddy/data/caddy/pki/authorities/local/root.crt ``` ### 首次登录 使用您在 `.env` 中设置的凭据： ``` Email: admin@adauditai.local (or whatever SEED_ADMIN_EMAIL is set to) Password: ``` 第一个用户始终是管理员。使用侧边栏中的 **Utilisateurs** 来邀请团队成员。 ### 开发模式（热重载） ``` docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build ``` 这会将后端源代码作为卷挂载并运行 `uvicorn --reload`。前端更改需要重新构建前端容器（nginx 提供静态文件服务）。 ### 故障排除 | 症状 | 修复方法 | |---|---| | 浏览器无法访问 `https://localhost` | 运行 `docker compose ps` —— `caddy` 是否在 `0.0.0.0:443→443` 上运行？如果另一个进程占用了 443，请释放它或更改绑定 | | 日志中出现 "Configuration de production invalide" | `APP_ENV=production` 需要非默认的 `APP_SECRET_KEY`、`SEED_ADMIN_PASSWORD`、`POSTGRES_PASSWORD`、`NEO4J_PASSWORD`。请设置它们或使用 `APP_ENV=development` | | 登录返回 500 | 迁移未应用。运行 `docker compose exec backend alembic upgrade head`，然后重启 backend | | 登录后立即显示 "Session expirée" | 您可能输入了错误的密码或触发了 5 次尝试 / 5 分钟的锁定。等待 15 分钟或运行 `docker compose restart backend` 清除内存中的桶 | | 分析始终显示 `llm=mock` | 转到侧边栏中的 **Configuration LLM**（仅限管理员），选择您的提供商，粘贴 API 密钥，然后点击 "Tester la connexion" | | 上传时提示 "Aucun chemin d'attaque trouvé" | 当提取的图中没有从非特权用户到特权组的路径时，这是正常的。尝试更大的 BloodHound 导出文件——小型的实验室域通常没有可利用的路径 | ### 部署到真实域名 1. 在 `.env` 中设置 `APP_ENV=production` 2. 设置 `PUBLIC_DOMAIN=adaudit.your-domain.com` 3. 将该 DNS 记录指向主机 4. 向公网开放端口 **80** 和 **443** 5. 运行 `docker compose up -d --build` Caddy 会自动签发 Let's Encrypt 证书。在生产环境中会自动启用 HSTS。 ## LLM 提供商设置 选择任何受支持的提供商。您稍后也可以通过侧边栏中的 **Configuration LLM** 进行更改（仅限管理员）——应用内的配置会覆盖 `.env`。 | 提供商 | 模型 | API 密钥 URL | |---|---|---| | **Mistral** | `mistral-small-latest`, `mistral-large-latest` | https://console.mistral.ai/api-keys | | **Google Gemini** | `gemini-2.0-flash`, `gemini-1.5-pro` | https://aistudio.google.com/apikey | | **OpenAI** | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | https://platform.openai.com/api-keys | | **Anthropic** | `claude-sonnet-4-5`, `claude-opus-4-5` | https://console.anthropic.com | | **OpenRouter** | 许多模型，包括免费层的 Llama、Gemma、Mistral | https://openrouter.ai/keys | | **Ollama** | 本地 —— `llama3.1:8b`, `mistral:7b` 等 | 无需密钥 —— 在主机上运行 `ollama serve` | | **mock** | 确定性的模拟输出 —— 仅用于测试 | 平台会向每个支持它的提供商发送 `response_format={"type":"json_object"}`。如果模型拒绝该参数，它将自动在不带该参数的情况下重试。 ## 架构 ``` ┌──────────────────────────────────────────────────────────┐ │ Browser (Auditor) │ │ Alpine.js · Chart.js · Cytoscape.js │ └─────────────────────────┬────────────────────────────────┘ │ HTTPS / WebSocket ┌───────▼────────┐ │ Caddy │ Reverse proxy + Auto-TLS └───────┬────────┘ │ ┌─────────────▼──────────────────┐ │ FastAPI Backend │ │ │ │ ┌───────────────────────────┐ │ │ │ Pipeline Modules │ │ │ │ ingestion → paths │ │ │ │ → mitre → agent → report │ │ │ └──────────────┬────────────┘ │ │ │ │ │ ┌─────────────▼───────────┐ │ │ │ LLM Providers │ │ │ │ Mistral · Gemini │ │ │ │ OpenAI · Anthropic │ │ │ │ OpenRouter · Ollama │ │ │ └─────────────────────────┘ │ └────────┬────────────┬───────────┘ │ │ ┌──────────▼──┐ ┌─────▼──────┐ │ PostgreSQL │ │ Neo4j │ │ (app + logs)│ │ (graph) │ └─────────────┘ └────────────┘ ``` ## 工作流 1. 在 `https://localhost`（或您的 `PUBLIC_DOMAIN`）**登录** 2. **创建任务**（admin 或 manager），包含客户名称 + 任务代码 3. **上传 BloodHound JSON / ZIP**，拖放或点击。或使用实时 LDAP 收集器 4. 通过 WebSocket 观看 **进度条** 更新，经历提取 → 路径提取 → MITRE 丰富 → AI 分析 5. 浏览： - **Analyse** —— pipeline 状态 + 操作 - **Graphe AD** —— 交互式 Cytoscape 图 - **Chemins d'attaque** —— 带有风险 + 评分过滤器的可排序表格 - **Matrice MITRE** —— 战术 × 技术热力图 6. 点击任何路径查看详细视图：SVG 迷你图、MITRE 技术、AI 解释、嵌入式修复手册、在相关路径间的上一个/下一个导航 7. **下载** PDF 报告或按路径划分的修复 ZIP 包 8. 通过 Utilisateurs 页面**邀请团队成员**（仅限管理员） ## 技术栈 | 层级 | 技术 | |---|---| | 后端 | Python 3.11, FastAPI 0.115+, Uvicorn, WebSocket | | 数据库 | PostgreSQL 16（应用数据），Neo4j 5 Community（图） | | ORM / 迁移 | SQLAlchemy 2, Alembic（启动时自动应用） | | 图分析 | NetworkX 3，带有每个源-目标对实际时间预算的 BFS | | LLM 编排 | 带有 JSON 模式强制的自定义多提供商抽象 | | 验证 | Pydantic v2 | | PDF 生成 | WeasyPrint 62, Jinja2 3 | | 身份验证 | python-jose (JWT), passlib + bcrypt, token-version 吊销 | | 前端 | HTML5, CSS3, Alpine.js 3, Chart.js 4, Cytoscape.js 3 —— 零构建步骤 | | 反向代理 | Caddy 2（在生产环境中通过 Let's Encrypt 自动启用 HTTPS） | | 容器化 | Docker, Docker Compose v2 | | 测试 | pytest, pytest-asyncio, httpx | ## 项目结构 ``` ad-audit-ai/ ├── backend/ │ ├── app/ │ │ ├── api/v1/ # REST endpoints │ │ │ ├── auth.py # /login, /refresh, /logout, /invite, /reset │ │ │ ├── engagements.py # Mission CRUD + member management │ │ │ ├── analyses.py # Upload, pipeline, /detect-format preview │ │ │ ├── paths.py # Attack paths with filters │ │ │ ├── reports.py # PDF download │ │ │ ├── stats.py / mitre.py # Stats + MITRE coverage │ │ │ ├── ldap_collector.py # Live LDAP collection │ │ │ ├── llm_settings.py # LLM provider config UI backend │ │ │ ├── admin.py # Admin audit log + user management │ │ │ └── ws.py # WebSocket real-time progress │ │ ├── core/ │ │ │ ├── security.py # JWT + RBAC dependencies │ │ │ ├── engagement_access.py # Per-engagement membership gate │ │ │ ├── audit.py # Audit log middleware │ │ │ ├── rate_limit.py # Login bucket │ │ │ ├── auth_tokens.py # Invite + reset token issuance │ │ │ ├── password_policy.py # 12+ chars, 3-of-4 classes │ │ │ └── notifications.py # Email service (console + SMTP) │ │ ├── models/ # SQLAlchemy ORM │ │ ├── schemas/ # Pydantic v2 request/response │ │ └── modules/ │ │ ├── ingestion.py # BloodHound JSON/ZIP → NetworkX │ │ ├── paths.py # BFS path extraction with budget │ │ ├── agent.py # LLM agent + heuristic fallback │ │ ├── mitre.py # MITRE enrichment │ │ ├── report.py # WeasyPrint PDF generation │ │ ├── remediation.py # Per-path mitigation playbook │ │ ├── ldap_collector.py # Binary SD parser + LDAP queries │ │ └── llm_providers/ # Mistral, Gemini, OpenAI, Anthropic, OpenRouter, Ollama │ ├── data/ │ │ ├── mitre_mapping.json # 60+ edge types → MITRE techniques │ │ ├── compliance_mapping.json # MITRE → ISO 27001 / NIST CSF │ │ └── sample_graph.json # Synthetic test export │ ├── templates/ # Jinja2 PDF template │ ├── alembic/versions/ # 0001–0006 schema migrations │ └── tests/ # Unit + integration tests ├── frontend/ │ ├── public/ # HTML pages (Alpine.js, no build) │ ├── js/ # Vanilla JS modules │ ├── css/ # Tokens + components + toast │ └── nginx.conf # Cache control + security headers ├── caddy/ # Caddyfile (PUBLIC_DOMAIN-driven) ├── docs/ # Architecture docs ├── docker-compose.yml # Production stack └── docker-compose.dev.yml # Dev override (hot reload, exposed ports) ``` ## API 参考 Swagger UI: `https://localhost/api/docs` ``` # Auth POST /api/v1/auth/login POST /api/v1/auth/refresh POST /api/v1/auth/logout GET /api/v1/auth/me POST /api/v1/auth/invite (admin) POST /api/v1/auth/accept-invite POST /api/v1/auth/forgot-password POST /api/v1/auth/reset-password # Engagements + 成员 GET /api/v1/engagements POST /api/v1/engagements (admin/manager) PATCH /api/v1/engagements/{id} (lead-on-engagement or admin) GET /api/v1/engagements/{id}/members POST /api/v1/engagements/{id}/members DELETE /api/v1/engagements/{id}/members/{user_id} # 分析 POST /api/v1/analyses/detect-format # Preview before full pipeline POST /api/v1/engagements/{id}/analyses # Upload → launch pipeline POST /api/v1/engagements/{id}/ldap-collect # Live LDAP collection GET /api/v1/analyses/{id} # Status GET /api/v1/analyses/{id}/events # WS replay buffer + error_message GET /api/v1/analyses/{id}/graph # Cytoscape data GET /api/v1/analyses/{id}/paths # ?risk=critique&min_score=7 GET /api/v1/analyses/{id}/mitre # Coverage map GET /api/v1/analyses/{id}/stats GET /api/v1/analyses/{id}/report.pdf # Remediation GET /api/v1/analyses/{id}/paths/{path_id}/remediation-script # Markdown GET /api/v1/analyses/{id}/remediation-bundle.zip # All paths zipped # 管理 GET /api/v1/admin/audit-logs (admin) GET /api/v1/admin/users (admin) PATCH /api/v1/admin/users/{id} (admin) POST /api/v1/admin/users/{id}/disable (admin) POST /api/v1/admin/users/{id}/enable (admin) POST /api/v1/auth/admin/users/{id}/force-logout (admin) # LLM GET /api/v1/llm/providers GET /api/v1/llm/config PUT /api/v1/llm/config (admin) POST /api/v1/llm/test (admin) # WebSocket WS /ws/analyses/{id} # Real-time pipeline events ``` ## 运行测试 ``` # 所有测试 docker compose exec backend pytest -q # 仅 ingestion + paths 逻辑（无需 DB） docker compose exec backend pytest tests/unit/test_ingestion.py tests/unit/test_paths.py -q ``` ## 安全与道德 此工具**仅**用于对您拥有或获得明确书面测试许可的 Active Directory 环境进行安全审计。 - 使用 Ollama 提供商时，所有 AD 数据均保留在本地 - INFO 日志级别下不记录任何 AD 标识符（默认 `AUDIT_DEBUG_DATA=false`） - 审计日志中记录每一个修改性操作 - JWT 访问 token 将在 15 分钟后过期；刷新 token 在 7 天后过期 - 通过 `users.token_version` 进行服务器端会话吊销——注销会使所有会话失效 - 登录按（电子邮件，IP）进行速率限制；5 次失败尝试后锁定 15 分钟 - 密码策略：≥ 12 个字符，包含 {大写字母，小写字母，数字，特殊符号} 中的 3 种 - 纵深防御请求头（在生产环境中启用 HSTS、X-Frame-Options DENY、CSP、Permissions-Policy） - 在 `production` 模式下拒绝使用默认密钥启动 ## 许可证 [MIT](LICENSE)

标签：Active Directory, AV绕过, BloodHound, FastAPI, LLM, Plaso, Unmanaged PE, Web报告查看器, 攻击路径分析, 测试用例, 特权检测, 请求拦截, 逆向工具