shieldly-io/cdk-guard

# @shieldly/cdk-guard **由 AI 驱动的 CDK 应用 AWS 安全分析工具。** 在每次执行 `cdk synth` 时捕获有风险的 IAM 策略和 CloudFormation 配置错误——在您部署之前。 [](https://www.npmjs.com/package/@shieldly/cdk-guard) [](LICENSE) ``` npm install --save-dev @shieldly/cdk-guard ``` 请在 **[shieldly.io/app/api](https://www.shieldly.io/app/api)** 获取 API 密钥 （API 密钥需要 Builder 或更高级别的套餐；免费 demo 无需密钥即可运行）。 ## 使用方式 ### 1. CLI —— 无需修改代码（适用于任何语言的 CDK 应用） 运行 `cdk synth`，然后分析所有合成的 stack： ``` npx @shieldly/cdk-guard ``` ``` # 在 -- 之后传递额外的 cdk synth flags npx @shieldly/cdk-guard -- --context env=prod # 仅在发现 Critical 时失败 npx @shieldly/cdk-guard --fail-on Critical # 分析现有的 cdk.out/ 而无需重新合成 npx @shieldly/cdk-guard --no-synth --out-dir cdk.out # 用于脚本编写的 JSON 输出 npx @shieldly/cdk-guard --format json | jq '.[].findings[]' ``` 通过环境变量设置您的 API 密钥： ``` export SHIELDLY_API_KEY=sk_live_... npx @shieldly/cdk-guard ``` ### 2. CDK Construct —— 基于 hook（适用于 JavaScript/TypeScript CDK 应用） 将 `ShieldlyGuard` 添加到您的 CDK 应用中。它会通过 `process.on('beforeExit')` 在 `cdk synth` 之后自动运行——无需显式调用。 ``` import * as cdk from 'aws-cdk-lib'; import { ShieldlyGuard } from '@shieldly/cdk-guard'; const app = new cdk.App(); // Add the guard — reads SHIELDLY_API_KEY from environment by default. new ShieldlyGuard({ failOn: 'High', // Critical | High | Medium | Low | none }); new MyStack(app, 'MyStack'); // Guard analyzes cdk.out/ automatically when the process exits. ``` **选项：** | 选项 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `apiKey` | `string` | `SHIELDLY_API_KEY` 环境变量 | Shieldly API 密钥 | | `failOn` | `string` | `'High'` | 如果发现的安全问题达到或超过此严重级别，则以退出代码 1 退出 | | `outDir` | `string` | `'cdk.out'` | 要分析的 CDK 输出目录 | | `apiUrl` | `string` | `https://api.shieldly.io` | 用于自托管 / 开发环境的覆盖地址 | | `silent` | `boolean` | `false` | 禁止所有控制台输出 | ### 3. 显式 post-synth（使用顶层 await 的 ESM） ``` import * as cdk from 'aws-cdk-lib'; import { shieldlyGuard } from '@shieldly/cdk-guard'; const app = new cdk.App(); const stack = new MyStack(app, 'MyStack'); const assembly = app.synth(); const { failed } = await shieldlyGuard(assembly.directory, { failOn: 'High', }); if (failed) process.exit(1); ``` ### 4. cdk.json hook 在每次 `cdk synth` 之后自动运行分析——适用于任何 CDK 语言： ``` { "app": "node bin/my-app.js", "hooks": { "afterSynth": ["npx", "@shieldly/cdk-guard", "--no-synth"] } } ``` ## CI / CD ### GitHub Actions ``` - name: CDK security check run: npx @shieldly/cdk-guard env: SHIELDLY_API_KEY: ${{ secrets.SHIELDLY_API_KEY }} ``` ### package.json scripts ``` { "scripts": { "synth:check": "cdk synth && npx @shieldly/cdk-guard --no-synth", "deploy:safe": "npx @shieldly/cdk-guard && cdk deploy" } } ``` ## 工作原理 1. 读取 CDK manifest（`cdk.out/manifest.json`），以仅查找当前合成的 stack 模板（而不是之前运行留下的过期输出）。 2. 将每个 `*.template.json` 发送到 Shieldly AI 分析引擎（`POST /v1/analyze/cf`）。 3. AI 分析 IAM 角色、策略、资源策略和 CloudFormation 安全配置，用通俗易懂的英文解释每个发现的问题，并提供收紧（更安全）的策略。 4. 将结果打印到终端。如果任何发现的问题达到或超过 `failOn` 严重级别阈值，则以代码 `1` 退出。 ## 分析内容 - IAM 角色和管理型策略 - Lambda 函数、EC2 实例、ECS 任务上的内联策略 - 资源策略（S3 存储桶策略、SQS 队列策略、KMS 密钥策略） - CloudFormation 安全配置错误（公开的 S3 存储桶、未加密的资源、过度宽松的安全组） ## 相关项目 - **[shieldly.io](https://www.shieldly.io)** —— 基于 Web 的 IAM Advisor（免费 demo，无需注册） - **[@shieldly/cli](https://www.npmjs.com/package/@shieldly/cli)** —— 从任何终端进行分析 - **[shieldly-io/action](https://github.com/shieldly-io/action)** —— 用于 PR 门控的 GitHub Action - **VS Code 扩展** —— 在应用市场搜索 "Shieldly" - **[REST API](https://www.shieldly.io/docs/api)** —— 集成到任何 pipeline 中 *Amazon Web Services (AWS) 是 Amazon.com, Inc. 的商标。Shieldly 与 Amazon Web Services 没有任何附属、认可或赞助关系。*

标签：AI, AWS CDK, IAM, MITM代理, 云安全监控, 暗色界面, 自动化代码审查, 自定义脚本, 静态分析