Prowler SDK 开发指南Check 架构、元数据规范与 AI Agent 驱动的工作流【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowlerProwler SDK 是驱动 AWS、Azure、GCP、Kubernetes、GitHub、M365 等多云安全评估的 Python 核心引擎。本篇以 SDK 组件的 Agent 指南prowler/AGENTS.md为主体完整解析其 Provider 分层架构、Check 实现范式与元数据规范并结合仓库真实源码如 S3 检查实现、Check/CheckMetadata模型与配套 Skills 体系说明一套面向 AI Agent 的规范化开发工作流。读完你可以独立完成新增一个安全 Check、理解其校验规则、跑通本地测试并知道何时必须调用哪个 Skill。项目概览SDK 在 Prowler 中的位置根据指南文档Prowler SDK 是核心 Python 引擎core Python engine当前支持 1100 安全检查与 85 合规框架。结合仓库实际内容可以核实其规模prowler/providers下共有 25 个 Provider 目录aws、azure、gcp、kubernetes、github、m365、alibabacloud、oraclecloud、okta、vercel等远超文档所列的六家主流云全仓库共 1608 个*.metadata.json检查元数据文件、113 个合规框架 JSONprowler/compliance/实际数量已超过文档写作时的口径说明 SDK 的 Check 数量仍在快速增长。根级指南AGENTS.md则将 SDK 定位为 monorepo 五大组件之一组件位置技术栈SDKprowler/Python 3.10, uvAPIapi/Django 5.1, DRF, CeleryUIui/Next.js 16, React 19, Tailwind 4MCP Servermcp_server/FastMCP, Python 3.12Dashboarddashboard/Dash, PlotlySDK 指南开头引用了五个核心 Skills 作为详细模式参考链接已转换为仓库根路径Skill用途prowler-sdk-check从零创建安全检查分步指南prowler-provider添加新的云 Providerprowler-test-sdkSDK 的 pytest 测试模式prowler-compliance合规框架结构pytest通用 pytest 模式Auto-Invoke动作与 Skill 的强制绑定指南的核心机制是Auto-invoke Skills当 AI Agent或开发者执行特定动作时必须先调用对应的 Skill 再动手。这相当于给 Agent 建立了一张动作 → 知识路由表SDK 范围内收录了 18 条规则按 Skill 归组后为prowler-changelog为 PR/功能添加 changelog、更新任一组件的CHANGELOG.md、审查 changelog 格式如 prowler/changelog.d/ 中的碎片文件prowler-compliance新增/更新合规框架、添加合规输出格式化器per-provider class table dispatcher、审计 Check 到 Requirement 的映射、修复合规 JSON 缺陷重复 ID、空 Section、失效引用、同步上游合规目录prowler-provider新增 Provider、为现有 Provider 添加 Serviceprowler-sdk-check创建新 Check、更新现有 Check 与元数据prowler-test-sdk编写 SDK 测试、在测试中用 moto 模拟 AWSprowler-compliance-review审查合规框架 PRpytest编写 Python 测试。这套机制的实际价值在于把团队惯例编码成了可执行的触发条件——Agent 不需要凭记忆判断流程匹配到动作描述即自动加载对应 Skill 的完整模式例如 skills/prowler-sdk-check/SKILL.md 中包含了完整的 Check 目录结构、元数据 Schema、命名规范与常用模式代码。关键规则一Provider 分层架构指南给出的 Provider 目录契约如下这是整个 SDK 最重要的结构约束prowler/providers/{provider}/ ├── {provider}_provider.py # Main provider class ├── models.py # Provider-specific models ├── lib/ # service/, arguments/, mutelist/ └── services/{service}/ ├── {service}_service.py # Resource fetcher ├── {service}_client.py # Singleton instance └── {check_name}/ # Individual checks ├── {check_name}.py └── {check_name}.metadata.json以 AWS S3 服务为例仓库中的实际结构与契约完全吻合s3_service.py 是资源抓取器而 s3_client.py 仅三行——from prowler.providers.aws.services.s3.s3_service import S3 from prowler.providers.common.provider import Provider s3_client S3(Provider.get_global_provider())它把全局 Provider 注入S3服务实例形成模块级单例供该服务下所有 Check 共享。每个 Check 则是独立的目录例如 s3_bucket_secure_transport_policy.py 与其同名.metadata.json成对存放——这正是指南Check 三元组__init__.py、{check_name}.py、{check_name}.metadata.json约定的体现。关键规则二Check 实现范式指南规定所有 Check 必须继承Check基类并实现execute()模板如下from prowler.lib.check.models import Check, CheckReport{Provider} from prowler.providers.{provider}.services.{service}.{service}_client import {service}_client class {check_name}(Check): def execute(self) - list[CheckReport{Provider}]: findings [] for resource in {service}_client.{resources}: report CheckReport{Provider}(metadataself.metadata(), resourceresource) report.status PASS if resource.is_compliant else FAIL report.status_extended Detailed explanation findings.append(report) return findings从源码看这套范式的底层支撑是 prowler/lib/check/models.py 中的三个模型Check基类第 674 行起继承自抽象类Check与CheckMetadata。其__init__会做两件关键事——自动加载同路径的.metadata.json并用 Pydantic 校验随后强制校验CheckID、类名、文件名三者必须完全一致不一致即抛出ValidationError。这意味着指南模板中的类名不是随意命名的class s3_bucket_secure_transport_policy(Check)必须与文件s3_bucket_secure_transport_policy.py、元数据中的CheckID同名。CheckMetadata模型第 183 行起定义了元数据 JSON 的完整 Schema 与十余个校验器详见下节。Check_Report_*家族Check_Report基类第 716 行持有status、status_extended、resource等发现字段并按资源形态自动归一化dict / pydantic 模型 / dataclass /to_dict()。各云 Provider 派生出专属报告类例如Check_Report_AWS附加resource_id/resource_arn/regionCheck_Report_GCP附加project_id/locationCheck_Report_Kubernetes附加namespace。指南模板里的CheckReport{Provider}占位符即指这一族类名。对照一个真实实现可以更直观地看到范式落地s3_bucket_secure_transport_policy.pyfrom prowler.lib.check.models import Check, Check_Report_AWS from prowler.providers.aws.services.s3.s3_client import s3_client class s3_bucket_secure_transport_policy(Check): def execute(self): findings [] for bucket in s3_client.buckets.values(): report Check_Report_AWS(metadataself.metadata(), resourcebucket) # 遍历 bucket policy 语句检查是否存在 # Deny Condition: aws:SecureTransport false 的规则 if not bucket.policy: report.status FAIL ... findings.append(report) return findings该 Check 遍历s3_client.buckets单例提供的已抓取资源逐桶判断策略中是否存在Deny非 HTTPS 请求的语句命中即PASS否则FAIL——与指南模板单例取资源 → 逐资源判定 → 生成 report → 汇总返回的流程一一对应。CheckMetadata元数据 JSON 的 Schema 与硬性校验Check 的身份证是同目录的{check_name}.metadata.json。仓库中的真实样例s3_bucket_secure_transport_policy.metadata.json展示了完整字段结构{ Provider: aws, CheckID: s3_bucket_secure_transport_policy, CheckTitle: S3 bucket policy denies requests over insecure transport, CheckType: [ Software and Configuration Checks/AWS Security Best Practices/Network Reachability, Software and Configuration Checks/Industry and Regulatory Standards/CIS AWS Foundations Benchmark ], ServiceName: s3, SubServiceName: , ResourceIdTemplate: , Severity: medium, ResourceType: AwsS3Bucket, ResourceGroup: storage, Description: **Amazon S3 buckets** are evaluated for ..., Risk: HTTP access exposes object data ..., RelatedUrl: , AdditionalURLs: [https://...], Remediation: { Code: { CLI: ..., NativeIaC: ..., Terraform: ..., Other: ... }, Recommendation: { Text: ..., Url: https://hub.prowler.com/check/s3_bucket_secure_transport_policy } }, Categories: [encryption], DependsOn: [], RelatedTo: [], Notes: }这些字段并非建议填写而是由 models.py 中CheckMetadata的 Pydantic validator 强校验。从源码看主要约束包括字段/校验器规则CheckID非空、不得含连字符-且必须等于类名与文件名Check.__init__强制CheckTitle≤150 字符且不得以 Ensure 开头ServiceName必须为小写且必须等于 CheckID 以_分割后的第一段Severity枚举critical / high / medium / low / informational自动转小写Categories仅允许预定义白名单encryption、internet-exposed、logging、secrets、privilege-escalation等见VALID_CATEGORIES第 42 行起仅小写字母、数字、连字符ResourceGroup白名单校验compute、storage、network、IAM等VALID_RESOURCE_GROUPS第 20 行起可为空字符串CheckType非 AWS Provider 必须为空列表AWS 下每一项必须是prowler/providers/aws/config/check_types.json层级中的合法路径支持namespace、namespace/category、namespace/category/classifier部分路径不得有空字符串RelatedUrl已废弃必须为空Remediation.Code.CLI不得是 URLhttps?://开头即报错Remediation.Recommendation.Url若非空必须以https://hub.prowler.com/开头Description/Risk各 ≤400 字符AdditionalURLs不得含空项与重复项CheckMetadata还提供静态检索能力get_bulk(provider)批量加载某 Provider 全部检查元数据CheckID作键插件 Check 与内置 Check 冲突时内置优先并告警list(...)支持按 provider / severity / category / service / compliance framework 求交集筛选——这正是 CLI--list-checks与--severity、--category等过滤参数的底层实现。代码风格与工具链指南的 Code Style 三条铁律所有公共函数必须有类型注解type hints类与方法必须带 Google 风格 docstringPEP 8 由 black / flake8 强制执行导入顺序standard → third-party → local。技术栈一行概括Python 3.10 | uv | pytest | motoAWS mock| Pre-commitblack、flake8、pylint、bandit 等。仓库实际情况pyproject.toml 声明requires-python 3.10,3.14.pre-commit-config.yaml 中的 hooks 还包括isort、autoflake、check-json、pretty-format-json、shellcheck、actionlint等与 SDK 指南描述的钩子集合一致black、flake8、isort 均在列而各组件如api/、mcp_server/则额外叠加 ruff 等钩子。项目结构与 CLI 入口指南给出的顶层结构图prowler/ ├── __main__.py # CLI entry point ├── config/ # Global configuration ├── lib/ │ ├── check/ # Check execution engine │ ├── cli/ # Command-line interface │ ├── outputs/ # Output format handlers (JSON, CSV, HTML, ASFF, OCSF) │ └── mutelist/ # Mute list functionality ├── providers/ # Cloud providers (aws, azure, gcp, kubernetes, github, m365...) │ └── common/ # Shared provider utilities ├── compliance/ # Compliance framework definitions (CIS, NIST, PCI-DSS, SOC2...) └── exceptions/ # Global exceptions各目录均与仓库实际一一对应prowler/main.py 是 CLI 入口仓库根的 prowler-cli.py 仅导入其中的prowler()并sys.exit转发prowler/lib/check/ 中check.py、checks_loader.py构成执行引擎compliance.py负责合规评估prowler/lib/outputs/ 下确实分列asff、csv、html、ocsf等输出格式处理器prowler/config/ 除全局配置外还存放各 Provider 的 mutelist 示例与 scan_config_schema.py 等。标准命令集指南收录的四组常用命令均为已核实的可执行形式# 环境初始化 uv sync uv run pre-commit install # 运行 Prowler uv run python prowler-cli.py {provider} uv run python prowler-cli.py {provider} --check {check_name} uv run python prowler-cli.py {provider} --list-checks # 测试 uv run pytest -n auto -vvv tests/ uv run pytest tests/providers/{provider}/services/{service}/ -v # 代码质量 uv run pre-commit run --all-files补充两点上下文-n auto依赖pytest-xdist做并行测试SDK 测试目录 tests/providers/ 按providers/{provider}/services/{service}/与源码完全同构布局例如 tests/providers/aws/services/s3/ 下每个 Check 都有对应测试目录方便源码目录 → 测试目录按名定位。配套 Skill prowler-sdk-check 中还给出了更细粒度的本地验证命令uv run python prowler-cli.py {provider} --log-level ERROR --verbose --check {check_name}本地跑单个 Check、--profile myprofile指定凭证、--check {check1} {check2} {check3}一次跑多个。新增 Check 的标准流程Quick Reference 展开指南的六步速查表确认 Check 不存在--list-checks | grep {check_name}创建目录prowler/providers/{provider}/services/{service}/{check_name}/创建三个文件__init__.py、{check_name}.py、{check_name}.metadata.json实现 Check 逻辑遵循上文Check子类范式本地测试--check {check_name}编写测试PASS / FAIL / 空资源三类场景。skills/prowler-sdk-check/SKILL.md 对这一流程给出了可复制的展开细节值得补充的要点命名规范——CheckID 遵循{service}_{resource}_{security_control}例如ec2_instance_public_ip_disabled、s3_bucket_encryption_enabled、iam_user_mfa_enabled。注意与上一节校验规则联动ServiceName 必须等于 CheckID 第一段所以命名直接决定了元数据合法性。严重级别判级指南Severity适用场景critical直接数据暴露、RCE、权限提升high重大安全风险、合规违规medium纵深防御、最佳实践low信息类、次要加固报告状态三态PASS资源合规、FAIL不合规、MANUAL需人工核验或无法获取评估所需数据。该 Skill 特别强调一条反直觉但重要的规则——权限/可用性错误不是 finding不得因 API 调用失败缺权限、API 未启用、特性未授权而打FAIL那属于扫描配置问题而非安全问题正确做法是服务层将数据未获取与结果为空区分开如用None而非[]Check 层只输出一条租户/账号级的MANUALfinding并在status_extended中写明缺失的权限/API。而404/未配置通常意味着未启用该控制反而属于正当的FAIL。常用代码模式——Skill 中还沉淀了两类典型实现多条件聚合把各项不合规点收集到issues列表统一拼进status_extended与区域资源遍历for bucket in s3_client.buckets.values()。与前述 S3 真实检查互为印证。QA 检查清单指南为每个 SDK 变更设定了五项交付门槛uv run pytest通过uv run pre-commit run --all-files通过Check 元数据 JSON 有效能通过CheckMetadata的 Pydantic 校验测试覆盖PASS、FAIL 与空资源三种场景Docstring 符合 Google 风格。其中元数据 JSON 有效一项值得强调其自动化程度由于Check.__init__在实例化时即加载并校验元数据、且CheckID与类名/文件名的三方一致性检查同步执行一次pytest运行即可同时拦截元数据格式错误与命名不一致问题——QA 清单的前四项在很大程度上被测试与钩子链路自动兜底。小结prowler/AGENTS.md 以不足 150 行的篇幅把 Prowler SDK 的架构契约Provider/Service/Check 三层目录、实现范式Check子类 单例 client 报告三态、元数据强校验规则与质量门槛浓缩成了一份机器可读的开发规范再通过 Auto-invoke 表把 18 类常见开发动作绑定到 7 个 Skill形成 Agent 与人类开发者通用的操作协议。对贡献者而言理解这份指南即掌握了 SDK 侧 90% 的开发规约而对更深入的元数据字段文档与 AWS/Azure/GCP 模板可继续查阅 skills/prowler-sdk-check/references/metadata-docs.md 与 skills/prowler-sdk-check/assets/ 中的完整模板。【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考