albert-einshutoin/cdn-security-framework

# CDN Security Framework [](https://github.com/albert-einshutoin/cdn-security-framework/actions/workflows/policy-lint.yml) [](https://github.com/albert-einshutoin/cdn-security-framework/actions/workflows/release-npm.yml) [](./.github/workflows/policy-lint.yml) [](./docs/supply-chain.md) **CDN Security Framework** 是一个**安全设计与实现框架**，可适用于主流的 CDN 边缘执行环境，如 CloudFront、CloudFront Functions、Lambda@Edge 和 Cloudflare Workers。 目标非常简单。 **推荐的初始路径：** 从 `npx cdn-security init --platform aws --archetype spa-static-site --force` 开始，构建生成的 policy，然后将 AWS CloudFront Function 和 WAF Terraform 输出接入你现有的基础设施中。我们也支持 Cloudflare Workers，但 AWS + Terraform 路径是目前最完整的首次部署路径。 ## 为什么需要这个框架 许多 CDN 安全设置存在以下问题： * **为每个项目重复手写类似的 Edge 规则** * CloudFront 和 Cloudflare 之间的**设计碎片化** * WAF 和 Edge Functions 之间**职责划分不明确** * **初始安全质量不一致**，取决于实施者是谁 本框架通过**“policy 驱动” + “runtime 分离”**来解决这些问题。 ## 设计理念（重要） ### 1. Edge 是“第一道防线——不要让攻击进来” * 在流量到达 Origin 或应用之前**减少攻击面** * **立即拦截明显的异常** * 通过标准化和移除不必要的元素来**防止意外发生** ### 2. 以声明式编写规则（Policy） * 不要直接编辑 CDN 特定的代码 * 首先编写**人类可读的 policy** * 然后将其编译为各个 CDN runtime ### 3. 不与 WAF 重叠 * **Functions / Workers** * 标准化、轻量级拦截、header 注入 * **WAF** * 速率限制、OWASP、Bot、CAPTCHA ## 支持的 CDN / Edge Runtimes | Platform | Support | | -------------------- | -------------------------------- | | AWS CloudFront | Behavior / Policy 设计 | | CloudFront Functions | Viewer Request / Response | | AWS Lambda@Edge | Origin Request / Response | | Cloudflare | CDN / 安全规则 | | Cloudflare Workers | Fetch Handler | ## 仓库结构 ``` README.md src/ bin/cli.ts # TypeScript source for the CLI scripts/ # TypeScript source for compilers, tests, and tools lib/ # TypeScript source for public library APIs bin/ cli.js # Compiled package artifact: CLI entry (npx cdn-security) docs/ architecture.md quickstart.md policy-runtime-sync.md policy/ security.yml / base.yml profiles/ scripts/ compile.js # Compiled from src/scripts/*.ts compile-cloudflare.js compile-infra.js policy-lint.js runtime-tests.js cloudflare-runtime-tests.js compile-unit-tests.js infra-unit-tests.js check-drift.js templates/ # Internal: used by build to generate dist/edge/ aws/ dist/ edge/ # Generated: deploy this (viewer-request.js, viewer-response.js, origin-request.js) infra/ # Generated WAF IaC: Terraform JSON and optional CloudFormation runtimes/ # Legacy / reference; deploy from dist/edge/ examples/ ``` 包代码的权威来源位于 `src/**/*.ts`。根目录下的 JavaScript 和 `.d.ts` 文件是由 `npm run build:ts` 生成的已提交包产物，这样 npm 用户无需 TypeScript 构建步骤即可运行 CLI。`templates/` 下的 runtime 模板是手写的，用于生成可部署的 `dist/edge/` 输出。 有关 Terraform / CloudFormation / CDK / WAF 的使用，请参阅 [IaC 集成](docs/iac.md)。 ### 操作文档 - [CLI 参考](docs/cli.md) — `init` / `build` / `emit-waf` / `doctor` / `readiness` / `capabilities` / `explain` / `diff` / `migrate` - [程序化 API](docs/programmatic-api.md) — `require('cdn-security-framework')` 用于 CI / IaC 集成 - [编译器严格性](docs/compiler-strictness.md) — 阶段契约、严格检查以及剩余的动态区域 - [Archetypes](docs/archetypes.md) — 基于应用形态的 policy 预设（SPA、REST API、admin、microservice） - [Policy 配方](docs/recipes.md) — 适用于 Cognito API、SPA、admin 面板、签名下载和 Cloudflare GraphQL 的可复制代码片段 - [响应 DLP](docs/response-dlp.md) — Cloudflare Workers 针对高置信度数据泄露的响应掩码/拦截 - [密钥轮换操作手册](docs/runbooks/secret-rotation.md) — JWT / JWKS / 签名 URL / admin token / origin secret - [Schema 迁移](docs/schema-migration.md) — `policy/schema.json` 如何演进以及 `migrate` CLI - [供应链](docs/supply-chain.md) — SLSA v1 provenance 和 `npm audit signatures` - [模板注入契约](docs/template-injection-contract.md) — 标记安全、经过解析检查的 runtime 配置注入 - [测试策略](docs/test-strategy.md) — Vitest 迁移策略和发布门禁测试工作流 - [ADR 0001: 插件安全的发射器路径](docs/adr/0001-plugin-safe-emitter-path.md) — 基于 bundler 的原型和迁移标准 ## Policy 和 Runtimes * **Policy**（`policy/security.yml` 或 `policy/base.yml`）是**单一事实来源**。编辑 policy 以更改拦截规则、header 或路由保护。 * **Build** 运行 CLI 编译器：`npx cdn-security build` 读取 policy，对其进行验证，并将 **Edge Runtime** 代码生成到 `dist/edge/*.js` 中。无需手动同步 `CFG` 或 runtime 配置。 * 有关详细信息和 IaC 用法，请参阅 [Policy 和 runtime 同步](docs/policy-runtime-sync.md)。 ## 快速开始（5 分钟） ### 1. 安装 ``` npm install --save-dev cdn-security-framework ``` ### 2. 初始化（构建 policy 脚手架） ``` npx cdn-security init ``` 回答提示问题。你可以使用引导式设置，从 **profile**（`strict` / `balanced` / `permissive`）开始，或者选择一个 **archetype**（`spa-static-site`、`rest-api`、`admin-panel`、`microservice-origin`）。引导式设置会询问应用形态、CDN 目标、认证模式、CORS、WAF 态势和部署意图。 或使用非交互模式：`npx cdn-security init --platform aws --profile balanced --force` 或使用 archetype：`npx cdn-security init --platform aws --archetype rest-api --force` 或使用引导模式：`npx cdn-security init --guided --platform cloudflare --app-shape rest-api --auth jwt --cors-origins https://app.example.com --force` ### 3. 编辑并构建 根据需要编辑 `policy/security.yml`，然后： ``` # 如果你的策略具有 static_token auth gate，请先设置引用的 build-time # secret。内置的 base/admin 示例使用 EDGE_ADMIN_TOKEN。 export EDGE_ADMIN_TOKEN=replace-with-a-deploy-secret # AWS（默认）：生成 viewer-request.js、viewer-response.js、origin-request.js npx cdn-security build # Cloudflare Workers：为 Wrangler 生成 index.ts npx cdn-security build --target cloudflare # AWS + 现有由 Terraform 管理的 Web ACL： # 仅生成 rule groups（跳过 aws_wafv2_web_acl 输出） npx cdn-security build --rule-group-only ``` 这将验证 policy 并将 Edge Runtime 代码生成到 `dist/edge/` 中。 对于非生产环境的测试构建，你可以使用 `npx cdn-security build --allow-placeholder-token`，但绝不要部署包含 占位符 token 的产物。 ### 4. 测试 ``` export EDGE_ADMIN_TOKEN=ci-build-token-not-for-deploy export ORIGIN_SECRET=ci-origin-secret-not-for-deploy npm run test:ci ``` 运行单 Node CI 质量门禁，包括 audit、policy lint、build、 runtime、unit、fuzz、integration、drift、security-baseline、coverage 和 package smoke 检查。它有意不重现 GitHub Actions 的 Node 版本矩阵；CI 仍会在 Node 20.17.0、22 和 24 上运行 package smoke。 如果你有本地的 `policy/security.yml`，`test:ci` 会先对其进行 lint 和 build， 然后重新生成 `policy/base.yml` fixtures 以用于 runtime 和 coverage 测试。 对于有针对性的本地检查： ``` npm run test:runtime npm run test:unit npm run test:drift npm run test:security-baseline ``` 包含内置 admin `static_token` 门禁的生成产物需要 `EDGE_ADMIN_TOKEN`。 更广泛的 drift/release 检查所使用的 origin-auth fixture policy 需要 `ORIGIN_SECRET`。 ### 4.5 诊断（可选，但在首次部署前推荐） ``` npx cdn-security doctor npx cdn-security capabilities --policy policy/security.yml --target aws npx cdn-security explain ``` 一次性通过/失败报告：Node 版本、policy 可解析性 / schema 版本、认证门禁引用的每个环境变量（`EDGE_ADMIN_TOKEN`、`JWT_SECRET`、`ORIGIN_SECRET` 等）、`dist/edge/` 可写性以及 `npm ls` 的整洁度。写入 `doctor-report.json` 以供 CI 捕获。详情请参阅 [CLI 参考](docs/cli.md)。 使用你将用于 `build` 的相同环境变量运行它， 因为 CloudFront Functions 会将静态 token 门禁固化到生成的产物中。 `explain` 会打印只读的 policy 安全态势摘要，供审查和入职参考。 `capabilities` 会打印目标支持矩阵，并且通过 `--policy`，报告 `aws` 或 `cloudflare` 中部分支持、不支持或仅警告的已配置控制项。使用 `--json` 进行自动化。 ### 5. 部署 将 `dist/edge/` 中生成的文件与 Terraform、CDK 或你的 CDN 控制台配合使用。在环境或 secrets 中为 admin 路由设置 `EDGE_ADMIN_TOKEN`。 ## 本框架提供的功能 * 拦截不需要的 HTTP 方法 * 提前拦截 Path Traversal * UA / query 异常检测 * 认证门禁：静态 token、Basic auth、JWT (RS256/HS256)、签名 URL * 强制安全 header（HSTS、CSP、Referrer-Policy、Permissions-Policy） * CORS 和 Cookie 属性管理 * 缓存中毒缓解 * 用于非阻塞观察的监控模式 * 不与 WAF 冲突的设计 ## 设计上不做的事情 * 高级 Bot 行为分析（WAF / Bot 管理的职责） * 内部 DB 滥用 * 业务逻辑篡改 ## 目标用例 * 新 Web / API 服务的初始安全防护 * 使用多个 CDN 的全球服务 * OSS / SaaS “安全模板”产品 * 标准化内部安全基线 ## 对于维护者（发布到 npm） * **package-lock.json**：提交它以便 CI 可以运行 `npm ci`。 * **dist/**：通过 `.gitignore` 忽略。用户运行 `npm run build` 以生成 `dist/edge/` 和 `dist/infra/`。对于 CI drift 检查，在 CI 中运行 `npm run build` 并与 policy 进行比较（不要提交 `dist/`）。 * **CI 工作流**： * `.github/workflows/policy-lint.yml`：push/PR 质量门禁（lint/build/runtime/unit/drift/security-baseline + package smoke 测试） * `.github/workflows/release-npm.yml`：tag 驱动的发布工作流 * **通过 tag 发布**： 1. 提升 `package.json` 版本（例如：`1.0.1`） 2. 提交并推送到 `main` 3. 创建并推送 tag `v1.0.1` 4. GitHub Actions 运行发布检查，如果所有检查通过则发布到 npm * **用于发布的 npm 认证**： * 首选：带有 `npm publish --provenance` 的 npm Trusted Publishing (OIDC) * 备选：设置仓库密钥 `NPM_TOKEN`，工作流使用 token 发布 ## License MIT License

标签：CDN, ECS, LNA, MITM代理, Terraform, WAF, 安全策略管理, 暗色界面, 程序员工具, 自定义脚本, 边缘计算