bluearchio/bluearch-aws-steward
GitHub: bluearchio/bluearch-aws-steward
一款 MCP 优先的本地化 AWS 只读评估与受控修复规划引擎，帮助用户基于 BlueArch 错误配置目录发现云资源问题并生成可验证的修复方案。
Stars: 0 | Forks: 0
# BlueArch AWS Steward
**BlueArch AWS Steward Beta：一个 MCP 优先、只读的 AWS 建议与修复规划引擎。**
BlueArch AWS Steward 是一个本地化、MCP 优先的 AWS 评估与受控修复引擎。它根据 BlueArch 的错误配置目录评估实时的 AWS 配置，仅返回被可执行规则捕获的资源，构建有证据支撑的修复计划，并验证已批准的更改。
Steward 是独立运行的。它不使用 BlueArch Core、托管登录、托管遥测或本地 AWS 资产清单数据库。AWS 始终是唯一事实来源。
## 它提供什么
- 跨 16 个运行时 scope 的 100 条原生规则。
- 可搜索所有 631 条 `aws-misconfig-db` 目录条目的知识库。
- 使用用户自有的 AWS 凭据进行时间点只读评估。
- 对目标、服务、配置文件和 Region 进行 MCP 原生的意图澄清。
- 提供引导式、聚焦式和完整报告评估模式，支持多目标和多服务选择。
- 支持带有状态、部分结果和取消功能的后台评估。
- 完整的临时发现结果，提供经过过滤、基于游标的分页探索功能，且无需重新扫描 AWS。
- 支持本地 JSON、Markdown、HTML、CSV、SARIF 和 PDF 格式的报告导出。
- 自动选择终端 PDF 格式；prompt 中无需请求报告。
- 在每个呈现的发现结果中提供证据、风险、成本估算状态/置信度以及修复安全性指标。
- 评估过程不应用任何 AWS 更改；受控写入需要批准一个精确的短效计划。
- 结构化的资源标识，并使用 schema `0.2` 对证据进行脱敏处理。
- 为每条原生发现提供规划，并为八条低风险规则提供受控应用。
- 提供一个优先级队列，整合了原生 Steward、实时的 Security Hub、Compute Optimizer、Cost Optimization Hub 以及可选的 Prowler/导出的 JSON 信号。
- 与来源无关的去重机制，附带来源、时效性、置信度、证据、实时验证状态，以及可解释的 0-100 优先级得分。
Steward 是对 Prowler 和 AWS Security Hub 等广泛扫描工具的补充。它不能替代上述任何产品、持续资产盘点工具或自主 AWS 管理员。它的重点在于填补从发现结果到经过审查的 AWS 或 IaC 修复，以及修复后验证这最后一步的本地空白。有关产品定位和路线图，请参阅 [`docs/competitive-strategy.md`](docs/competitive-strategy.md) 和 [`docs/expansion-plan.md`](docs/expansion-plan.md)。
## 安装说明
Steward 需要 Python 3.10 或更高版本。推荐的 `uv` 安装程序可以管理兼容的 Python 运行时，并在 macOS 和 Linux 上运行：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
在 macOS 上，也支持使用 Homebrew：
```
brew install uv
```
预期的正式安装方式是作为一个持久化、隔离的 `uv` 工具：
```
uv tool install bluearch-aws-steward
uv tool update-shell
bluearch-steward --version
bluearch-steward mcp smoke
```
然后为已安装的工具生成稳定的 MCP 配置：
```
bluearch-steward mcp config --runtime installed
```
对于需要按需解析确切发布包的客户端，可以生成锁定版本的 `uvx` 配置：
```
bluearch-steward mcp config --runtime uvx
```
该包尚未发布。发布候选工作流会验证此安装形态而不会实际发布任何内容，但用户只有在首次显式进行 PyPI 发布后才能运行这些命令。目前没有工作流会发布包或创建 GitHub release。
在此之前，请安装存储库的检出内容：
```
git clone https://github.com/bluearchio/bluearch-aws-steward.git
cd bluearch-aws-steward
make dev-sync
```
配置 MCP 客户端以通过 stdio 启动存储库运行时。在本地安装中使用存储库的绝对路径：
```
{
"mcpServers": {
"bluearch-aws-steward": {
"command": "/absolute/path/bluearch-aws-steward/.venv/bin/bluearch-steward-mcp",
"args": [],
"env": {
"AWS_SDK_LOAD_CONFIG": "1",
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
`uv run python -m bluearch_aws_steward mcp config` 会使用绝对环境路径生成此配置结构。更改源码后，请运行 `make dev-sync`，然后重启 MCP 服务器或启动新的 agent 任务。这会重新安装当前检出的代码，而不是允许 MCP 启动时修改环境；已经在运行的 Python 进程不会热重载模块。
有关包的安装、升级、卸载和 MCP 客户端设置流程，请参阅 [`docs/public-installation.md`](docs/public-installation.md)。
随时验证当前活动的运行时：
```
make runtime-info
```
检出版本、已安装的包元数据版本和运行时版本必须匹配。此检查在存储库之外运行，因此 Python 导入工作目录无法隐藏过期的包。
不要在 MCP 配置中放置凭据、SSO token、默认配置文件或默认 Region。Steward 使用 AWS SDK 凭据链，并在可能存在多个上下文时询问用户。
## 首次评估
1. 在对话之外配置 AWS 凭据。AWS SSO 用户可以运行：
aws sso login --profile my-sso-profile
2. 重启或重新连接 MCP 客户端。
3. 询问：
Steward 会立即返回一个评估 ID。客户端会轮询状态，可以读取部分结果，并检索简明的解决方案卡片，而无需重新开始扫描。每一条发现结果在进程内存中均可保持 15 分钟的可查询和可导出状态。50,000 条发现结果的防护机制会报告 `incomplete=true` 及确切原因，而不是默默地截断完整的评估。
只读评估、发现证据和风险、成本估算状态和置信度、单个计划批准以及终端 PDF 选择都是产品的默认行为；用户无需在 prompt 中专门请求它们。
有关聚焦于成本、安全、可靠性、目录、规划和验证的 prompt，请参阅 [`docs/prompt-library.md`](docs/prompt-library.md)。
### 统一建议队列
原生规则仍然是默认选项。当账户启用了其他 AWS 建议来源时，可以选择它们：
```
{
"prompt": "Build one prioritized queue from all available recommendation sources.",
"services": ["all"],
"objectives": ["all"],
"signal_sources": [
"native",
"security-hub",
"compute-optimizer",
"cost-optimization-hub"
]
}
```
Steward 会在同一个时间点评估期间读取每个选定的来源。它会对账户、Region、规范资源和规范问题进行指纹识别；合并相互印证的信号；保留每一条来源凭证；并最终返回一条建议。当前的原生证据可以解决等效的过时配置发现，但范围较窄的原生检测器绝不会使范围更广的 Compute Optimizer 或 Cost Optimization Hub 建议失效。缺少权限或未启用的 AWS 服务会显示在 `capability_errors` 和 `incomplete_sources` 下；它们绝不会被视为正常通过。
`bluearch_query_results` 可以按 `sources` 和 `validation_statuses` 过滤队列。每种报告格式都包含指纹、来源列表、时效性、优先级得分、证据、风险、节省估算/置信度以及修复安全性指标。
## MCP 工作流
```
flowchart LR
U["User intent"] --> C["MCP client"]
C --> A["bluearch_assess"]
A --> Q{"Input needed?"}
Q -->|yes| U
Q -->|no| S["Live AWS reads"]
S --> R["Complete ephemeral snapshot"]
R --> X["Summary, query, or report"]
X --> P["No-write plan"]
P --> G{"Exact plan approved?"}
G -->|no| R
G -->|yes| W["Revalidate and guarded write"]
W --> V["Fresh verification"]
```
主要工具：
| 工具 | 用途 | AWS 写入 |
| --- | --- | --- |
| `bluearch_assess` | 解析意图并启动后台评估。 | 否 |
| `bluearch_list_aws_profiles` | 列出非机密的 AWS 配置文件元数据供用户选择。 | 否 |
| `bluearch_import_findings` | 将支持的外部发现 JSON 导入到临时评估中。 | 否 |
| `bluearch_get_scan_status` | 返回进度而不重复执行工作。 | 否 |
| `bluearch_get_scan_results` | 返回最终结果或 `include_partial`（部分）结果。 | 否 |
| `bluearch_query_results` | 对存储的快照进行过滤、排序、分面和分页，无需重新扫描。 | 否 |
| `bluearch_export_report` | 导出已完成的结果，包括带有图表的本地 PDF。 | 否 |
| `bluearch_cancel_assessment` | 停止待处理的工作并保留已完成的读取结果。 | 否 |
| `bluearch_get_resource_details` | 检查或刷新一个匹配的资源。 | 否 |
| `bluearch_get_coverage` | 报告目录和原生检测器的覆盖率。 | 否 |
| `bluearch_status` | 检查运行时、AWS 身份和规则覆盖率。 | 否 |
| `bluearch_rules_search` | 搜索所有 631 条目录规则。 | 否 |
| `bluearch_explain_finding` | 解释证据和影响。 | 否 |
| `bluearch_plan_remediation` | 重新验证并创建一个短效计划。 | 否 |
| `bluearch_apply_remediation` | 应用一个明确批准的计划。 | 受控 |
| `bluearch_verify_remediation` | 重新读取 AWS 并验证选定的发现结果。 | 否 |
传统的 CLI 和 Textual 仪表盘仍作为开发者诊断工具保留。正常的用户流程是使用 MCP。
## 检测覆盖率
`bluearch_get_coverage` 报告：
| 指标 | v0.7.0 |
| --- | ---: |
| 目录规则 | 631 |
| 原生规范规则 | 100 |
| 原生别名 | 7 |
| 运行时 scope | 16 |
| 目录自动化率 | 15.85% |
运行时 scope 包括 `iam`、`cloudtrail`、`cloudwatch`、`dynamodb`、`s3`、`ec2`、`rds`、`lambda`、`efs`、`ecs`、`alb`、`kms`、`secrets-manager`、`sns`、`sqs` 和 `api-gateway`。别名 `ebs` 和 `networking` 会路由到 EC2 收集器，且不会增加规范规则的计数。
目前所有 100 条规则的 `access_tier` 均为 `free`（免费）。这是稳定的开源基线。超出此基线的未来规范规则将保留给 `premium`（高级）层级，除非项目治理明确将其提升。v0.7.0 不添加托管登录、授权调用或遥测；权利 enforcing 将作为一个独立的未来边界。
每个结果都会区分已评估、已跳过和未评估的规则。由于云平台能力或 AWS 权限受限而被阻止的规则会带有原因被跳过；它们永远不会被报告为通过。发现结果为零仅表示没有已评估的规则匹配。
有关完整的原生规则列表和证据类型，请参阅 [`docs/rule-coverage.md`](docs/rule-coverage.md)。
## 发布状态
当前 `0.7.0` 的工作是一个发布候选版本，而不是已发布的稳定版本。公开预览和稳定发布的把关标准记录在 [`docs/public-release-readiness.md`](docs/public-release-readiness.md) 中。计划的渐进式结果体验记录在 [`docs/result-experience-plan.md`](docs/result-experience-plan.md) 中。
来源适配器契约和安全边界记录在 [`docs/source-compatibility.md`](docs/source-compatibility.md) 和 [`docs/security-threat-model.md`](docs/security-threat-model.md) 中。
## 安全模型
读取权限是根据类型化的操作注册表生成的：
- [`iam/read-policy.json`](iam/read-policy.json)
- [`iam/remediation-policy.json`](iam/remediation-policy.json)
请将这些策略保留在不同的角色上。日常评估只需要读取策略。
大多数发现结果仅用于规划。受控应用仅限于：
- S3 公共访问阻止、默认加密、生命周期、版本控制和服务器访问日志；
- CloudWatch Logs 保留策略；
- CloudTrail 日志文件验证；以及
- ALB 访问日志。
S3 和 ALB 日志记录需要在选定 Region 中存在预先创建的目标、SSE-S3 加密，以及一个 bucket policy，该策略需向请求前缀对应的 AWS 日志交付服务主体授予 `s3:PutObject` 权限。S3 服务器访问日志目标不能启用服务器访问日志记录；ALB 前缀不能包含 `AWSLogs`。Steward 会在规划时和应用前立即验证这些条件。它绝不创建目标 bucket、bucket policy、凭据或支持性基础设施。它也不会自动删除资源、轮换密钥、移除权限、停止工作负载、更改流量或执行迁移。
每次写入都需要：
1. 重新读取以复现该发现；
2. 服务器端持有的计划，包含确切的 operations、preconditions、IAM、rollback 和 verification；
3. 短期过期时间和摘要；
4. 账户、Region 和实时资源状态保持不变；以及
5. 针对该确切计划显式设置 `allow_write=true`。
## 架构
```
MCP client
-> intent and AWS-context refinement
-> ephemeral assessment store
-> concise conversational projection
-> filtered cursor-paginated exploration
-> prioritized remediation queue
-> complete report export
-> collector registry + ExecutableRuleSpec registry
-> live recommendation-source adapters + deterministic deduplication
-> AWS SDK provider (default) or AWS CLI compatibility provider
-> typed read allowlist + assessment-local metric cache
-> detectors + structured evidence
-> plan store + explicit guarded writes
```
服务收集器在有界并发下运行。服务快照在其规则之间被重用，并且 `rule_filter` 会同时缩小规则和 AWS 调用的范围。
24 条信号规则通过评估局部的缓存批量处理 CloudWatch `GetMetricData` 请求。缺失的指标数据被标记为未知，绝不会视为零。
此版本不包含多账户遍历、全 Region 编排、IaC 扫描、攻击图、托管历史记录、遥测或 AWS MCP provider。
有关计划的规则、LocalEmu、EKS、性能和 IaC 修复扩展路径，请参阅 [`docs/expansion-plan.md`](docs/expansion-plan.md)。
## 开发说明
使用 Python 3.10、3.11 或 3.13 安装质量工具：
```
make dev-sync
make test
make quality
make security
make package
```
针对确定性的 LocalEmu 固件运行实际的 stdio MCP 协议：
```
make emulator-doctor
make emulator-mcp-e2e
```
E2E 使用虚拟凭据且不进行任何写入操作，证明了 `assess -> status -> partial results -> unified source deduplication -> concise results -> paginated complete query -> complete PDF -> plan -> verify` 的完整流程。`make emulatorcoverage` 还要求通过 AWS SDK 和 AWS CLI provider 为全部 100 条活动规则提供正向发现。88 个固件直接使用 LocalEmu API；十二个历史性、账户级、指标维度或合成大小的状态使用了仅用于测试的本地回环响应覆盖层，记录在 [`tests/aws-emulator/rule-map.yml`](tests/aws-emulator/rule-map.yml) 中。
除非调用 `make emulator-down`，否则 LocalEmu 将保持运行状态。
要进行手动只读 AWS 验证：
```
AWS_PROFILE=my-sso-profile AWS_REGION=us-east-1 make aws-live-cost-parity
AWS_PROFILE=my-sso-profile AWS_REGION=us-east-1 make aws-live-mcp
```
切勿将 AWS 凭据放入 GitHub Actions 中。CI 使用带有 LocalEmu 的虚拟凭据，且从不选择 AWS 配置文件。LocalStack 仅作为可选的兼容性目标通过 `make localstack-compat-coverage` 提供。
## 目录与 IAM 工件
从同级的 `aws-misconfig-db` 检出中刷新目录：
```
.venv/bin/python -m bluearch_aws_steward rules sync --source ../aws-misconfig-db
make catalog-check CATALOG_SOURCE=../aws-misconfig-db
.venv/bin/python -m bluearch_aws_steward.iam_policies
.venv/bin/python -m bluearch_aws_steward.iam_policies --check
```
`make test` 是独立的，不需要同级目录检出。
`make catalog-check` 是显式的维护者把关步骤，用于将打包的目录与选定的 `aws-misconfig-db` 检出进行比较。
目录文本属于不受信任的数据。只有经过审查的 `ExecutableRuleSpec` 映射才能驱动 AWS 调用或决定通过/失败结果。
## 贡献与安全
在提交 Pull Request 之前，请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。请按照 [`SECURITY.md`](SECURITY.md) 中的说明私下报告漏洞。本项目采用 Apache-2.0 许可协议；请参阅 [`LICENSE`](LICENSE)。
标签：AWS, DPI, MCP, 模块化设计, 自动化修复, 逆向工具