aws-samples/sample-ai-security-posture-management

# AWS 上的 AI 安全态势管理 (AI SPM) 发现、评估并保护您环境中运行的 AI agents —— 完全构建于 AWS 原生服务之上。AI SPM 连接到 [LiteLLM](https://docs.litellm.ai/) 网关、[Temporal](https://temporal.io/) 和 [AWS X-Ray](https://docs.aws.amazon.com/xray/)，为安全团队提供跨越三大支柱的统一仪表板： - **监控 (Observe)** — 持续发现并盘点 AI agents（LiteLLM 模型和密钥、Temporal workflows、Bedrock agents、SageMaker endpoints、AI Lambdas），并结合 X-Ray 行为基线和实时的服务依赖关系图进行丰富。 - **治理 (Govern)** — 一个策略引擎，根据映射到 **OWASP LLM Top 10**、**NIST AI RMF** 和 **MITRE ATLAS** 的 10 条内置规则评估 agent 配置和由追踪推导出的行为。 - **防御 (Defend)** — 通过 LiteLLM callback 和 X-Ray 追踪分析进行运行时威胁检测（prompt 注入、数据泄露、memory 投毒、速率限制、异常拓扑），并提供可配置的 **monitor** 或 **enforce**（内联阻断）模式。  ## 特色用例 — 使用 AI 规划的团队销售与活动管理（酒店业） 酒店、度假村和会议中心越来越多地通过多 agent AI 来运营**团队销售和活动管理**：接收到针对会议、婚礼或企业团建的入站 RFP 后，会启动协作 agent 来验证线索、检查空间和客房可用性、制定菜单、起草宴会活动订单、对套餐进行定价并生成提案 —— 所有这些都会从 PMS、CRM、餐饮和支付系统中提取数据。 这些 agent 是自主的、具有**高权限**（客人 PII、协议定价、合同、支付），并且会接收**不受信任的入站内容**（RFP 邮件和文档） —— 这正是 AI SPM 旨在**监控、治理和防御**的精准风险特征。隐藏在 RFP 中的恶意指令、权限过大的销售密钥，或是突然访问支付 API 的规划 agent，在这里都可以被检测到。 包含了一个可以直接运行的基线，方便您查看此端到端流程： ``` export SPM_CONFIG_FILE="$(pwd)/config/hospitality-group-sales.example.json" ``` - **配置文件：** [`config/hospitality-group-sales.example.json`](config/hospitality-group-sales.example.json)（9 个团队销售/活动 workflows 及其允许的依赖项） - **完整说明：** [`docs/use-cases/group-sales-event-management.md`](docs/use-cases/group-sales-event-management.md) ## 架构 AI SPM 作为现有 AWS 环境的**扩展**进行部署。它不会创建 VPC、ECS 集群或 ALB —— 您需要将这些作为参数提供，AI SPM 会添加其自己的 ECS 服务、DynamoDB 表、IAM 角色、ALB 监听器和 CloudFront 分配。 | 组件 | 服务 | 用途 | |-----------|---------|---------| | SPM API | ECS Fargate (FastAPI) | 发现、策略评估、运行时监控、REST API | | SPM UI | ECS Fargate (Next.js) | 安全仪表板 | | 数据 | DynamoDB (4 个表) | 资产盘点、发现结果、策略、运行时事件 (TTL) | | 认证 | Amazon Cognito | 仪表板身份验证 | | 边缘 | CloudFront + ALB | 仪表板分发 | | 遥测 | AWS X-Ray + ADOT | 追踪摄取和行为基线 | 有关详细信息和数据流，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 前置条件 这是一个扩展，因此它需要一个现有的平台来进行监控： - 一个 **AWS 账户**，拥有创建 DynamoDB、ECS、IAM、ELB 和 CloudFront 资源的权限。 - 一个现有的 **VPC**，包含私有子网（用于出站 AWS API 访问的 NAT gateway 或 VPC endpoints）。 - 一个现有的 **ECS Fargate 集群**、**Application Load Balancer**、ECS **任务执行角色**、ECS **安全组**，以及一个 **Cloud Map** 私有 DNS 命名空间。 - 一个 **LiteLLM** 代理和（可选）一个用于发现的 **Temporal** 服务器。 - 用于可选的语义注入分类器的 **Amazon Bedrock** 模型访问权限。 - 用于仪表板身份验证的 **Amazon Cognito** 用户池 + 应用客户端。 - 工具：`aws` CLI、`finch` 或 `docker`、Python 3.11+、Node.js 20+。 ## 仓库布局 ``` . ├── spm/ # Python backend (FastAPI) │ ├── api/main.py # REST API + transparent LLM proxy │ ├── core/ # db, models, auth (Cognito), tracing, config │ ├── scanner/ # LiteLLM / Temporal / X-Ray / AWS discovery │ ├── engine/policy_engine.py# 10 Govern rules │ └── defender/ # runtime monitoring, detectors, correlation ├── spm-ui/ # Next.js dashboard ├── infra/ │ ├── 01-spm-platform.yaml # tables, IAM, ECS services, target groups │ └── 02-spm-cdn.yaml # ALB listener + CloudFront ├── config/ │ ├── spm-config.example.json # KNOWN_WORKFLOWS / EXPECTED_DEPS (generic) │ ├── hospitality-group-sales.example.json # Featured hospitality use-case baseline │ └── litellm-callback.example.yaml # how to register the Defend callback ├── docs/ │ ├── ARCHITECTURE.md │ └── use-cases/group-sales-event-management.md # Featured use case ├── Dockerfile.spm-api ├── deploy.sh ├── generate_architecture_diagram.py └── .env.example ``` ## 快速开始 ### 1. 在本地运行后端 ``` python -m venv .venv && source .venv/bin/activate pip install -e . # 指向您的平台（DynamoDB 表必须存在，或使用本地 mock） export AWS_REGION=us-east-1 export LITELLM_URL=http://localhost:4000 export LITELLM_KEY=your-litellm-admin-key export TEMPORAL_ADDRESS=localhost:7233 # COGNITO_POOL_ID 未设置 => 认证已禁用（仅限本地） uvicorn spm.api.main:app --reload --port 8001 # 健康检查： curl localhost:8001/spm/health ``` ### 2. 在本地运行仪表板 ``` cd spm-ui npm install export NEXT_PUBLIC_API_URL=http://localhost:8001 export NEXT_PUBLIC_COGNITO_POOL_ID=... # optional for local export NEXT_PUBLIC_COGNITO_CLIENT_ID=... npm run dev # http://localhost:3001 ``` ### 3. 部署到 AWS ``` cp .env.example .env # 编辑 .env 以包含您的 VPC、subnets、cluster、ALB、Cognito、LiteLLM 等。 source .env ./deploy.sh ``` `deploy.sh` 会构建并将两个镜像推送到 ECR，然后部署两个 CloudFormation 堆栈。完成后： 1. 在您的 ALB 安全组上，允许来自 CloudFront 面向源的托管前缀列表的 SPM 监听器端口（默认为 `8090`）上的入站流量。 2. 在您的 LiteLLM 配置中注册 Defend callback（参见 [`config/litellm-callback.example.yaml`](config/litellm-callback.example.yaml)）。 ## 配置 所有配置均通过环境变量进行（12-factor 应用原则）。关键配置包括： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `ENVIRONMENT_NAME` | `ai-spm` | DynamoDB 表名的前缀 | | `LITELLM_URL` | `http://localhost:4000` | LiteLLM 代理基础 URL | | `LITELLM_KEY` | _(空)_ | LiteLLM 管理员密钥（在生产环境中请使用 Secrets Manager） | | `TEMPORAL_ADDRESS` | `localhost:7233` | Temporal 前端地址 | | `AWS_REGION` | `us-east-1` | boto3 客户端的区域 | | `COGNITO_POOL_ID` / `COGNITO_CLIENT_ID` | _(空)_ | 仪表板身份验证（为空则禁用） | | `SPM_CONFIG_FILE` | _(未设置)_ | 包含 `known_workflows` / `expected_dependencies` 的 JSON 路径 | | `SPM_MONITORED_SERVICES` | _(空)_ | 用于新依赖项警报的、以逗号分隔的服务名过滤器 | | `SPM_CLASSIFIER_MODEL_ID` | `us.anthropic.claude-3-5-haiku-20241022-v1:0` | 用于语义注入检测的 Bedrock 模型 | | `SPM_POLL_INTERVAL_SEC` | `10` | 运行时监控轮询间隔 | | `SPM_PLUGINS` | _(空)_ | 第三方插件模块（detectors/rules/scanners/sinks）的以逗号分隔的导入路径 | | `SPM_BEDROCK_GUARDRAIL_ID` / `SPM_BEDROCK_GUARDRAIL_VERSION` | _(空)_ / `DRAFT` | 在代理中启用 Amazon Bedrock Guardrails 强制执行 | | `SPM_APPROVED_MODELS` | _(空)_ | 用于 `unapproved_model` 规则的、以逗号分隔的模型允许列表 | | `SPM_REQUIRE_GUARDRAIL` | _(空)_ | 设置为 `true` 以激活 `missing_guardrail_association` 规则 | | `SPM_SECURITY_HUB_ENABLED` | _(空)_ | 设置为 `true` 以将发现结果导出到 AWS Security Hub (ASFF) | | `SPM_GUARDDUTY_ENABLED` | _(空)_ | 设置为 `true` 以摄取 GuardDuty AI Protection 发现结果 | | `SPM_ANALYZE_IDENTITY` | _(空)_ | 设置为 `true` 以分析 agent 执行角色权限（ASI03；需要 IAM 读取权限） | | `SPM_GUARDIAN_MODE` | `off` | Guardian 自动响应：`off` / `recommend` / `auto` | | `SPM_INTENT_LLM` | _(空)_ | 设置为 `true` 以启用 Bedrock 意图一致性分类器 | | `SPM_INTENT_BASELINE_FACTOR` | `3.0` | 触发行为漂移标记的、超出基线的 token 数量乘数 | | `SPM_SNS_TOPIC_ARN` | _(空)_ | 用于高严重性运行时警报的 SNS 主题 | | `SPM_EVENT_BUS_NAME` | _(空)_ | 用于高严重性运行时事件的 EventBridge 总线 | 特定于环境的知识（您期望的 workflows 及其允许的下游依赖项）是可选的，通过 `SPM_CONFIG_FILE` 提供。请参阅 [`config/spm-config.example.json`](config/spm-config.example.json)。默认值为空，因此发现功能可以在不进行任何配置的情况下对任何平台生效。 ## 治理规则 规则是已注册的插件（参见[可扩展性](#extensibility)），映射到 **OWASP LLM Top 10 (2025)**、**OWASP Agentic AI 威胁**、**NIST AI RMF** 和 **MITRE ATLAS**。 | 规则 | 严重性 | 框架 | |------|----------|-----------| | `overprivileged_key` | 高 | OWASP LLM06, Agentic T6, NIST | | `unrestricted_model_access` | 高 | OWASP LLM06, MITRE, NIST | | `missing_guardrails` | 中 | OWASP LLM10, NIST | | `excessive_spend` | 中 | OWASP LLM10, NIST | | `stale_agent` | 低 | NIST | | `high_retry_rate` | 高 | OWASP LLM10, NIST | | `latency_anomaly` | 中 | MITRE | | `excessive_llm_calls` | 中 | OWASP LLM06, Agentic T6, MITRE | | `missing_trace_propagation` | 低 | NIST | | `unexpected_dependency` | 高 | Agentic T2, MITRE, OWASP LLM06 | | `jailbreak_activity` | 高 | OWASP LLM01, Agentic T1, MITRE | | `sensitive_data_exposure` | 严重 | OWASP LLM02, MITRE, NIST | | `insecure_output_handling` | 高 | OWASP LLM05, MITRE | | `excessive_agency` | 高 | OWASP LLM06, Agentic T6, MITRE | | `unapproved_model` | 中 | NIST, Agentic T15 | | `missing_guardrail_association` | 中 | OWASP LLM01, NIST | 此外还有 **5 条 Amazon Bedrock 态势规则**（Guardrail 强度/PII、知识库加密、模型调用日志记录、agent Guardrail 关联）以及一条 **agent 身份 / NHI** 规则（`excessive_agent_privilege`, ASI03） —— 请参阅 [docs/bedrock-security.md](docs/bedrock-security.md)。在 `GET /spm/api/plugins` 检查所有已加载的规则。 ## 运行时探测器 (Defend) 探测器也是插件。内置探测器包括：正则表达式 + Bedrock 语义的 **prompt 注入**、**越狱**、**系统提示词提取**、**memory 投毒**、**速率限制**、**PII/机密泄露**、**不安全的输出处理**、**MCP/工具使用**、**过度权限**以及 **Amazon Bedrock Guardrails**（内容过滤器、拒绝的主题、PII 脱敏）。支持在 **monitor** 或 **enforce**（内联阻断）模式下运行。 （可选）通过 `pip install "ai-spm[security]"` 分层使用同类最佳的 **OSS 检测套件**（无供应商锁定）：ProtectAI **LLM Guard**（机器学习 prompt 注入 + 机密信息）和 Microsoft **Presidio** (PII)。它们在安装后会自动注册，未安装时则不执行任何操作。 ### 基于意图的检测 + 从构建到运行时的关联 `intent_alignment` 探测器会推断 agent 的**运行时行为**是否与其**构建/配置**的方式相匹配：它将运行时看到的模型、工具和 token 使用情况与 agent 的资产盘点记录（批准的模型、预期的依赖项、行为基线）进行关联，并跟踪每个会话的**意图/行为漂移**（会话中途出现新的模型/工具）。可选的 Bedrock 分类器 (`SPM_INTENT_LLM=true`) 用于判断 agent 的操作摘要是否与其声明的目的一致。 ### Guardian — 自主的渐进式响应 Guardian 编排器（`POST /spm/api/guardian/run`，受 `SPM_GUARDIAN_MODE` = `off` | `recommend` | `auto` 控制）会获取近期的高/严重事件并应用**相称的**响应 —— 警报 → 阻断 → 遏制（隔离 workflow / 吊销模型访问权限 —— 通过现有的修复措施执行，并写入经过审计的 `guardian_action` 轨迹。 ## 深入的 Amazon Bedrock 安全 专用的 Bedrock 扫描程序可发现 **Guardrails**（过滤强度、PII、拒绝的主题）、**Knowledge Bases**（KMS 加密）、**模型调用日志记录**和 **Bedrock Agents**，外加一个 **Bedrock AgentCore** 扫描程序（运行时、MCP 网关、记忆） —— 并附带针对 Bedrock 的治理规则。 完整详情：[docs/bedrock-security.md](docs/bedrock-security.md)。 ## 衡量您的防御能力（红蓝对抗基准测试） `POST /spm/api/redteam/run` 会针对您**实时**的探测器堆栈运行精选的攻击语料库（注入、越狱、提取、数据泄露、不安全的输出）以及无害的对照组，并返回客观的**防御有效性得分** —— 检出率、误报率以及各类别的细分情况。使用它来证明（而不仅仅是声称）在启用 Guardrails / OSS 套件之前和之后的覆盖范围。 ## AIDR 集成 高严重性的发现结果和运行时事件会分发到用于 AI 检测与响应的可插拔 sinks：**AWS Security Hub** (ASFF `BatchImportFindings`)、**Amazon SNS** 和 **Amazon EventBridge**。AI SPM 还通过 `POST /spm/api/integrations/guardduty/ingest` (`SPM_GUARDDUTY_ENABLED=true`) **摄取 Amazon GuardDuty AI Protection** 发现结果（移除 Guardrail、禁用调用日志记录、异常的 Bedrock 使用情况），并且可以分析 **agent 执行角色权限**以防范非人类身份风险（ASI03, `SPM_ANALYZE_IDENTITY=true`）。 标准对齐：规则被标记到 **OWASP LLM Top 10 (2025)**、**OWASP Agentic Applications Top 10 (ASI01–ASI10, 2025 年 12 月)**、**NIST AI RMF**、**MITRE ATLAS**，并映射到 **AWS SRA for AI** ([docs/bedrock-security.md](docs/bedrock-security.md))。 ## 可扩展性 AI SPM 在设计上是可扩展的。四个基于装饰器的注册中心 —— **detectors** (Defend)、**rules** (Govern)、**scanners** (Observe) 和 **sinks** (AIDR) —— 让您无需修改核心代码即可添加功能。在任何可导入的地方放入一个包含已装饰函数的模块，并将 `SPM_PLUGINS` 指向它： ``` from spm.core.registry import detector, Detection @detector("acme.secret_scanner", phases=("post",)) def scan_secrets(ctx): if "BEGIN RSA PRIVATE KEY" in ctx.response_text: return [Detection("private_key_leak", "critical", {"model": ctx.model}, block=True)] return [] ``` ``` SPM_PLUGINS="acme.spm_plugins" uvicorn spm.api.main:app ``` 在 `GET /spm/api/plugins` 检查所有已加载的内容。完整指南：[docs/extending.md](docs/extending.md)。它与商业 AI agent 安全平台的对比：[docs/comparison.md](docs/comparison.md)。 ## 测试 ``` pip install -e ".[dev]" pytest -q ``` 测试套件涵盖了插件注册中心、针对红蓝对抗语料库的检测逻辑（断言在无害对照组上的召回率 ≥80% 且零误报）、风险评分引擎，以及针对 moto 模拟的 DynamoDB 的 `db.py`。CI 会在每次推送时运行（参见 `.github/workflows/tests.yml`）。 ## 安全 - **身份验证：** 设置 `COGNITO_POOL_ID`/`COGNITO_CLIENT_ID`。如果未设置，API 会将每个调用者视为匿名用户 —— 这仅供本地开发使用。 - **机密信息：** 切勿硬编码 LiteLLM 主密钥。为了方便起见，提供的 CloudFormation 接受它作为 `NoEcho` 参数；对于生产环境，请将其存储在 **AWS Secrets Manager** 中，并通过任务定义的 `Secrets` 进行注入。 - **CORS：** 出于示例目的，API 使用了宽松的 `*` CORS 策略。在生产环境使用之前，请将其限制为您的仪表板源。 - **Enforce 模式：** 内联阻断（`/spm/api/defender/mode` = `enforce`）会拒绝实时的 LLM 流量。请先在 `monitor` 模式下验证检测规则。 - **最小权限：** 审查 `infra/01-spm-platform.yaml` 中的 IAM 策略，并根据您的需求将 `Resource: '*'` 条目（X-Ray、发现）的范围缩小。 有关如何报告安全问题，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md#security-issue-notifications)。 ## 清理 ``` aws cloudformation delete-stack --stack-name ai-spm-cdn --region "$AWS_REGION" aws cloudformation delete-stack --stack-name ai-spm-platform --region "$AWS_REGION" # 可选择删除 ECR 仓库：ai-spm-spm-api、ai-spm-spm-ui ``` ## 许可证 本库基于 Apache-2.0 许可证授权。请参阅 [LICENSE](LICENSE) 文件。

标签：AI安全态势管理, AMSI绕过, AWS云原生, 大语言模型安全, 威胁检测, 安全合规审计, 机密管理, 请求拦截, 运行时防护, 逆向工具