MeAkash77/Cloud-Infrastructure-Security-Automated-Remediation-Platform

# ACSRF — Agentic Cloud Security & Remediation Framework        **一个多智能体 AI 框架，它利用图推理自主映射 AWS 攻击路径，并生成 Terraform 修复代码 —— 由 LangGraph、Neo4j 和可插拔的 LLM（Gemini / Ollama）驱动。**  ## 🏗️ 系统架构 ``` flowchart LR subgraph SRC["Data Source"] AWS["AWS Account
IAM · EC2 · SG · S3"] end subgraph PIPE["Data Pipeline"] direction TB ENUM["Enumerate
Boto3 Agent"] INGEST["Ingest
MERGE into Neo4j"] SUMMARY["Graph Summary
Token Gate"] ENUM --> INGEST --> SUMMARY end subgraph LOOP["🔍 Investigation Loop
(max 15 cycles)"] direction TB CORR["Correlation Agent
Planner + Executor
Multi-turn Cypher"] IAMA["IAM PrivEsc Agent
Rule Engine + LLM"] CORR -- "IAM_CHECK" --> IAMA IAMA -- "Result" --> CORR end subgraph DASH["🖥️ Web Dashboard (React/Vite)"] direction TB API["FastAPI Backend
(REST & SSE)"] UI["React UI
(Visualizations & Analytics)"] API <--> UI end subgraph DECISION["Decision & Remediation"] direction TB HITL["Human in the Loop
HITL checkpoint"] INTERVIEW["Interviewer Agent
Business Context"] REM["Remediation Agent
Terraform HCL"] ESC["Human Escalation
Loop Limit / Cancel"] HITL --> INTERVIEW --> REM end subgraph EXT["External Services"] direction TB NEO4J[("Neo4j
Graph DB")] LLMB["LLM Backend
Gemini / Ollama"] end subgraph OUT["Outputs"] direction TB AUDIT["Audit Log
orchestrator_audit.json"] VIZ["Graph Viz
graph_viz.html"] TF["Terraform Patches
artifacts/remediation/*.tf"] CKPT[("Checkpointer
orchestrator.db")] end AWS --> ENUM SUMMARY --> CORR CORR -- "QUERY" --> NEO4J NEO4J -- "Rows" --> CORR INGEST --> NEO4J CORR --> LLMB IAMA --> LLMB CORR -- "DONE" --> HITL CORR -- "Limit" --> ESC HITL -- "Denied" --> AUDIT ESC --> AUDIT REM --> TF REM --> AUDIT CORR -.-> VIZ NEO4J <--> API CKPT <--> API AUDIT -.-> API ``` ## 💡 愿景 ACSRF 无法完全归入任何现有的行业类别。它不是 CSPM 工具——那些工具基于静态清单运行，而非推理。它不是 CIEM 工具——那些工具孤立地分析权限，而不是分析它们如何链接在一起。它也不是传统的 CNAPP——那些是供应商平台，而不是自主智能体。 ACSRF 与众不同：它是一个**推理系统**，将云环境视为一个图，并提出疑问——*鉴于所有配置错误的情况，攻击者可能做出的最恶劣行为是什么，我们该如何阻止它？* 在进攻性安全领域有一句名言：*“防御者以列表思考，攻击者以图谱思考。”* ACSRF 正是建立在这一确切前提之上。在安全工具领域中，最接近的参考点是 **BloodHound** —— 但是 BloodHound 映射的是本地环境中的 Active Directory 攻击路径，而 ACSRF 为**云**做同样的事情，并且其 AI 层不仅能可视化图表，还能主动在图上进行**推理**并**编写修复方案**。 它首先作为一个 **Blue Team** 工具运行。其核心任务是在攻击路径被完全利用*之前*找到它们。在“假定违规”模型下运行时，它不问 *攻击者是如何进入的？* —— 而是问 *鉴于他们已经进来了，他们能接触到什么，他们能走多远？* 它自主执行此项调查，使得单个安全工程师就能显现出红队演练需要数天或数周才能映射出的爆炸半径。 ### 🕸️ 攻击路径可视化 ACSRF 在浏览器中原生提供了一个交互式的、BloodHound 风格的可视化工具。它映射出身份、权限和网络规则，清晰地展示了看似孤立的配置错误是如何连接形成关键攻击路径的。  正如网络安全领域的大多数事物一样，它本质上是双刃剑。为防御者揭示爆炸半径的同一个推理引擎，同样可以轻易地被用于进攻性的环境映射——这使 ACSRF 成为一个强大的**自动化红队侦察工具**。 ## 工作原理 ACSRF 被构建为一个 **LangGraph 多智能体状态机**，由 **Neo4j** 图数据库提供支持，能够使用开源模型（通过 **Ollama**）完全在本地运行，以避免 API 成本、合规性和数据隐私问题。 ### 智能体 | # | Agent | 角色 | 关键细节 | |---|-------|------|-------------| | 1 | **Enumeration Agent** | 使用只读的 Boto3 调用提取实时的 AWS 配置（EC2、IAM、S3、安全组） | 输出原始及标准化后的 JSON 工件 | | 2 | **Graph Ingestion** | 使用健壮的仅 `MERGE` Cypher 协议将枚举的数据映射到 Neo4j | 幂等 —— 可安全重新运行而不会产生重复项 | | 3 | **Graph Summary** | 计算图的全局概览（节点计数、关系统计、安全指标） | 根据图大小和后端能力对深度分析进行 Token 限制 | | 4 | **Deterministic Graph Scan** | **IAM Engine / Path Finder**：在 LLM 运行之前执行结构化的 BFS/最短路径查询以寻找漏洞 | 以确定性的结构化证据作为调查的种子 | | 5 | **Correlation Agent** | 充当自动化安全分析师的多轮推理 AI，搜寻复杂的多跳攻击路径 | Planner/Executor 架构；最多 15 个调查循环；动态生成 Cypher 并根据数据库响应进行枢纽分析 | | 6 | **IAM PrivEsc Agent** | 评估 IAM 策略是否允许特定的权限提升向量 | **优先使用确定性规则引擎**（21+ 个提升向量） → 仅在不确定时回退到 LLM | | 7 | **NL2Cypher Agent** | 将简单的英文安全问题转化为只读的 Neo4j Cypher 查询 | 具备 schema 感知的提示和上下文缓存；安全层阻止写操作 | | 8 | **Interviewer Agent** | 在修复之前为人类操作员生成有针对性的业务上下文问题 | 确保 Terraform 修复保留合法的访问模式 | | 9 | **Remediation Agent** | 为已批准的发现生成 Terraform (HCL) 补丁 | 接收已补充详细的策略文档、相邻依赖关系、共享/托管策略检测结果以及人类的业务上下文 | ### Orchestrator **LangGraph Orchestrator** 将整个流水线作为已编译的状态图进行管理： - **9 个节点函数**通过条件路由边连接 - **共享状态**包含使用 `operator.add` reducer 的累积字段（`findings`、`audit_log`、`investigation_log`） - **HITL 中断点** —— 执行在 `hitl_gate` 和 `human_escalation` 节点之前暂停 - **SQLite 检查点** —— 持久化完整的流水线状态，支持跨会话的 `--resume` - **取消传播** —— 每个节点都会检查 `cancel_requested` 以实现优雅关闭 ### 确定性分析（IAM Engine） ACSRF 并非仅仅依赖 LLM 进行分析。为了增加其分析的确定性，系统运行了两个高置信度引擎来识别结构性和基于权限的风险。 #### 🔍 确定性路径查找器 **Deterministic Graph Scan** 执行一套高性能的 Cypher 查询，以识别结构性的“低垂果实”漏洞： - **结构性攻击路径**：通过安全组和 IAM 关系链，查找从 `Internet` 到关键资源的直接路径。 - **暴露向量**：识别所有具有 `isPublic: true` 或来自 `0.0.0.0/0` 的 `CAN_REACH` 关系的资源。 - **横向移动**：映射允许攻击者在环境之间进行枢纽分析的共享 IAM 角色或安全组。 - **交互式路径查找**：**Web Dashboard** 包含一个 Bloodhound 风格的交互式浏览器，允许用户手动发现并可视化云环境中任意两个节点之间的攻击路径。 - **性能控制**：所有查询均使用类型化关系、硬深度限制（BFS 风格）以及严格的 10 秒事务超时。 #### 🛡️ 确定性 IAM 规则引擎 **IAM PrivEsc Agent** 使用数学上严密的评估器（受 PMapper 启发），它实现了完整的 **Rhino Security Labs** 权限提升分类法： - **显式拒绝优先**：始终检查覆盖任何 `Allow` 的全局 `Deny` 语句。 - **21+ 提升向量**：确定性地评估诸如 `sts:AssumeRole`、`iam:PassRole`、`UpdateAssumeRolePolicy` 和 `CreateAccessKey` 等向量。 - **安全回退**：如果语句使用了复杂的 `Conditions`、`NotAction` 或 `NotResource` 结构，引擎将返回 `UNCERTAIN`，并且只有在那时它才会交给 LLM 进行深度推理。 | 类别 | 示例 | |----------|----------| | **信任操纵** | `UpdateAssumeRolePolicy` | | **凭证篡改** | `CreateAccessKey`, `CreateLoginProfile`, `UpdateLoginProfile` | | **策略附加** | `AttachRolePolicy`, `PutUserPolicy`, `CreatePolicyVersion` | | **服务提升** | `iam:PassRole` + `ec2:RunInstances` 或 `lambda:CreateFunction` | | **代码注入** | `lambda:UpdateFunctionCode` | | **安全绕过** | `DeletePermissionsBoundary` | | **资源接管** | `iam:AddUserToGroup` | ## 🛰️ 人工干预 (HITL) 当调查完成（或达到循环限制）时，流水线会暂停并进入 **HITL 检查点** —— 这是一个交互式 CLI（或 Web Dashboard），在生成任何修复代码之前，人类操作员会在此处审查、验证和处理发现。 **命令：** - `list` —— 查看所有发现的严重程度和批准状态 - `explain ` —— 使用调查日志生成 AI 风险解释 - `verify [question]` —— 针对实时 NL2Cypher 查询 Neo4j 以独立验证发现 - `approve ` / `reject ` —— 处理发现 - `fix` —— 进入强制性的业务上下文访谈，然后生成 Terraform - `exit` —— 中止且不进行修复 `fix` 命令会触发 **Interviewer Agent**，它为每个已批准的发现生成一个有针对性的问题。操作员的回答将作为业务上下文注入到 **Remediation Agent** 中，以便它生成不会破坏合法访问的修复方案。 ## 项目状态 ### 已完成 - [x] **图数据流水线** —— 可靠的 AWS 到 Neo4j 摄取，使用仅 MERGE 的 Cypher - [x] **LangGraph Orchestrator** —— 8 节点状态机，具备条件路由、HITL 中断和 SQLite 检查点 - [x] **多轮关联引擎** —— Planner/Executor 架构，具备 15 个循环的调查回路 - [x] **IAM 评估引擎** —— 确定性规则引擎（21+ 个提升向量，Rhino Security Labs 分类法），带有 LLM 回退 - [x] **Remediation Agent** —— 生成 Terraform HCL，带有策略补充、共享策略检测和相邻依赖发现 - [x] **HITL 检查点** —— 用于发现审查、AI 解释、NL2Cypher 验证和修复批准的交互式界面 - [x] **业务上下文访谈** —— 在修复前通过 Interviewer Agent 强制收集人类上下文 - [x] **本地 AI 支持** —— Ollama 集成，具备基于意图的模型路由 - [x] **自然语言查询** —— 具备 schema 感知提示和上下文缓存的 NL2Cypher - [x] **交互式可视化** —— 自动生成 `vis.js` HTML 攻击路径图 - [x] **LLM 故障转移** —— 带有指数退避的自动 Gemini 模型故障转移链 - [x] **Web Dashboard** —— React/Vite 前端和 FastAPI 后端，用于流水线可视化、工件和交互式图表 - [x] **系统自我安全与强化** —— API 认证、防止 BOLA 和 LLM 护栏（提示词注入和 Cypher 写操作拦截） ### 路线图 - [ ] **扩展 AWS 资源覆盖范围** —— 摄取并建模 Lambda、VPC、RDS、CloudFront 等。 - [ ] **基于角色的访问控制 (RBAC)** —— 用于流水线管理和执行的精细权限控制 ## ⚙️ 快速开始 ### 前置条件 - **Python 3.10+** - **Node.js 18+ & npm**（用于 Web Dashboard） - **Neo4j** —— 推荐：在 `localhost:7687` 上运行 Docker `neo4j:5` - **LLM 后端** —— [Gemini API 密钥](https://aistudio.google.com/apikey) 或在本地运行的 [Ollama](https://ollama.ai) - **AWS 凭证** —— 用于目标账户的只读 IAM 密钥 ### 安装 **选项 A —— 可编辑安装（推荐）** 在虚拟环境中全局注册 `acsrf` CLI 命令。不需要设置 `PYTHONPATH`。 ``` git clone https://github.com/Ojasveer955/Agentic-Cloud-Security-and-Remediation-Framework.git cd Agentic-Cloud-Security-and-Remediation-Framework python -m venv .venv ./.venv/Scripts/activate # On Linux/macOS: source .venv/bin/activate pip install -e . ``` **选项 B —— （最基础的）Pip 安装** 使用 `requirements.txt`。在每次会话之前，您必须将 `PYTHONPATH` 设置为 `src`。 ``` python -m venv .venv ./.venv/Scripts/activate pip install -r requirements.txt # 设置 PYTHONPATH（每个新 terminal session 都需要） $env:PYTHONPATH = "src" # PowerShell # export PYTHONPATH=src # Bash ``` ### 环境设置 复制示例环境文件并使用您的进行编辑： ``` cp .env.example .env ``` 为后端生成安全的 API 密钥： ``` python scripts/generate_api_key.py ``` 编辑 `.env` 以配置您的 LLM 后端、AWS 凭证、API 密钥和 Neo4j 连接。请参阅下方的 [配置参考](#-configuration-reference)。 ### 首次运行 ``` # 1. 初始化 Neo4j constraints（一次性设置） acsrf init-db # 2. 运行完整 pipeline acsrf ``` ## 使用指南 ### 默认 —— 完整流水线 ``` acsrf ``` 运行完整的编排流水线：枚举 AWS 环境、构建 Neo4j 图，并启动 Correlation + IAM Agent 以自主搜寻攻击路径。当发现漏洞时，HITL 控制塔将被激活以供人工审查。 ``` acsrf --question "What EC2 instances can assume a privileged role?" ``` 覆盖 **Correlation Agent 调查**的起始问题/假设。默认情况下，它会查找从互联网到管理员权限的路径，但您可以将多智能体 AI 指向特定的假设。 ``` acsrf --resume ``` 通过其线程 ID（每次运行开始时打印）恢复先前暂停的流水线运行。 ### 子命令 | 命令 | 描述 | |---------|-------------| | `acsrf init-db` | 初始化 Neo4j 唯一性约束。首次使用前运行一次。 | | `acsrf enum-real` | 仅运行 AWS 枚举 Agent（无推理）。获取 IAM、EC2、安全组和 S3 数据并摄取到图中。 | | `acsrf run-queries` | 针对图执行预定义的 Cypher 查询包并打印结果。 | | `acsrf query-nl ""` | 通过 NL2Cypher Agent 提出自然语言安全问题（单次查询，无推理循环）。 | | `acsrf query-nl "" --no-summary` | 与上述相同，但跳过 LLM 摘要步骤并返回原始查询结果。 | | `acsrf serve --port 8000` | 原生启动 FastAPI 仪表板 API 服务器。 | ### NL2Cypher 查询示例 ``` acsrf query-nl "Show me all publicly exposed EC2 instances" acsrf query-nl "Which roles can escalate privileges?" acsrf query-nl "What is the blast radius from the internet to admin roles?" --no-summary ``` ### Web Dashboard 全新的交互式 Web Dashboard 运行一个由 FastAPI 后端驱动的 React/Vite 前端。您必须同时启动这两个服务器。 **1. 启动 FastAPI 后端** ``` acsrf serve --port 8000 ``` **2. 启动前端开发服务器** ``` cd frontend npm install npm run dev ``` 前端将在 `http://localhost:5173` 提供。 ## 配置参考 所有配置均通过您的 `.env` 文件中的环境变量完成。 ### 核心配置 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `LLM_BACKEND` | `gemini` | LLM 后端：`gemini` 或 `ollama` | ### 安全配置 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `ACSRF_API_KEY` | — | 用于认证的 API 密钥。使用 `python scripts/generate_api_key.py` 生成 | | `RATE_LIMIT_WINDOW_MINUTES` | `1` | 速率限制窗口（分钟） | | `RATE_LIMIT_MAX_REQUESTS` | `100` | 每个速率限制窗口的最大请求数 | ### Neo4j | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `NEO4J_URI` | `bolt://localhost:7687` | Neo4j 连接 URI | | `NEO4J_USER` | `neo4j` | Neo4j 用户名 | | `NEO4J_PASSWORD` | `password` | Neo4j 密码 | ### AWS | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `AWS_ACCESS_KEY_ID` | — | AWS 访问密钥（推荐只读） | | `AWS_SECRET_ACCESS_KEY` | — | AWS 秘密密钥 | | `AWS_DEFAULT_REGION` | `us-east-1` | 要枚举的 AWS 区域 | ### Gemini | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `GEMINI_API_KEY` | — | Google Gemini API 密钥 | | `GEMINI_MODEL` | `gemini-2.0-flash` | 默认 Gemini 模型 | ### Ollama（本地 AI） | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama 服务器端点 | | `OLLAMA_MODEL` | `deepseek-r1:32b` | 全局默认模型 | | `OLLAMA_PLANNER_MODEL` | *（回退到 OLLAMA_MODEL）* | 用于 Correlation Agent 策略规划器的专用模型 | | `OLLAMA_CODER_MODEL` | *（回退到 OLLAMA_MODEL）* | 用于代码生成任务的专用模型 | ## 项目结构 ``` src/acsrf/ ├── main.py # CLI entrypoint & argparse dispatcher ├── cli/ │ ├── commands.py # Standalone subcommands (init-db, enum-real, etc.) │ ├── control_tower.py # HITL checkpoint interactive CLI │ ├── orchestrate.py # Full pipeline runner with resume support │ └── neo4j_helpers.py # Neo4j driver factory ├── agents/ │ ├── enum_agent.py # AWS enumeration (Boto3) │ ├── s3_access_analyzer.py # S3 public/policy access analyzer │ ├── correlation/ # Multi-turn attack path investigation │ │ ├── agent.py # Planner/Executor cycle logic │ │ ├── planner_prompts.py # Strategic planner system prompts │ │ └── prompts.py # Executor & explanation prompts │ ├── iam_privesc/ # IAM privilege escalation analysis │ │ ├── agent.py # LLM-based policy evaluation │ │ ├── rule_engine.py # Deterministic escalation evaluator │ │ └── prompts.py # IAM analysis prompts │ ├── nl2cypher/ # Natural language → Cypher translation │ │ ├── agent.py # Query generation & safety layer │ │ ├── schema_context.py # Graph schema for prompt injection │ │ └── prompts.py # NL2Cypher system prompts │ ├── interviewer/ # Business context question generation │ │ ├── agent.py # Single-shot question generator │ │ └── prompts.py # Interviewer prompts │ └── remediation/ # Terraform patch generation │ ├── agent.py # Remediation code generator │ └── prompts.py # Remediation system prompts ├── orchestrator/ │ ├── graph.py # LangGraph state graph builder │ ├── state.py # Shared state schema (ACSRFState) │ └── nodes.py # All 9 node functions ├── api/ # FastAPI Backend │ ├── app.py # API Factory and CORS configuration │ ├── schemas.py # Pydantic data schemas │ ├── events.py # SSE pipeline event streaming │ └── routes/ # Pipeline, findings, graph endpoints ├── graph/ │ ├── ingest_real.py # AWS → Neo4j MERGE ingestion │ ├── schema_init.py # Uniqueness constraint initializer │ └── viz.py # vis.js HTML visualization generator ├── llm/ │ ├── backend.py # LLMBackend protocol + Gemini implementation │ └── ollama_backend.py # Ollama HTTP backend └── queries/ └── query_pack.py # Predefined Cypher security queries frontend/ # React / Vite Web Dashboard ├── src/ │ ├── components/ # Reusable UI components │ ├── store/ # Client-side state management (Zustand) │ └── App.jsx # Dashboard root application ├── package.json # Frontend dependencies └── vite.config.js # Vite frontend configuration docs/ ├── schema.md # Neo4j graph schema reference ├── demo_queries.cypher # Example Cypher queries └── architecture/ # Supplementary architecture diagrams ├── orchestrator_flow.md # LangGraph state machine diagram ├── hitl_workflow.md # Human in the Loop (HITL) workflow ├── graph_schema.md # Neo4j node/relationship diagram └── llm_routing.md # LLM backend routing architecture ``` ## 输出 所有工件均写入 `artifacts/` 目录： | 文件 | 描述 | |------|-------------| | `aws_enum_raw.json` | 未处理的 Boto3 API 响应 | | `aws_enum_normalized.json` | 已清理和结构化的数据，用于图摄取 | | `graph_viz.html` | 交互式 `vis.js` 攻击路径图（在识别到路径时自动生成） | | `orchestrator_audit.json` | 每个 Agent 节点、路由决策和 LLM 状态转换的完整透明追踪记录 | | `orchestrator.db` | LangGraph 状态的 SQLite 持久化（支持跨会话的 `--resume`） | | `nl2cypher_last_result.json` | 最后一次 NL2Cypher 查询结果 | | `remediation/*.tf` | 生成的 Terraform 修复补丁（每个批准的发现对应一个） | ## 架构深度解析 有关详细的图表和设计原理，请参阅： - **[Orchestrator 流程](docs/architecture/orchestrator_flow.md)** —— 包含所有节点、条件边和中断点的 LangGraph 状态机 - **[HITL 工作流](docs/architecture/hitl_workflow.md)** —— 人工干预 (HITL) 工作流、业务上下文访谈和修复触发器 - **[图 Schema](docs/architecture/graph_schema.md)** —— Neo4j 节点类型、关系和唯一性约束 - **[LLM 路由](docs/architecture/llm_routing.md)** —— 后端选择、Gemini 故障转移链、Ollama 支持和基于意图的模型路由 - **[安全强化](docs/security.md)** —— API 认证、防止 BOLA、提示词注入护栏和写操作拦截 ## 许可证 MIT 许可证。有关更多详细信息，请参阅 [LICENSE](LICENSE)。

标签：AI风险缓解, AWS安全, DLL 劫持, PyRIT, Web报告查看器, 图推理, 多智能体系统, 大语言模型, 攻击路径分析, 模块化设计, 自动化修复, 逆向工具