andreygubarev/arnmatch

# arnmatch — 自动生成的 Python AWS ARN 解析器 [](https://github.com/andreygubarev/arnmatch/actions/workflows/ci.yml) [](https://pypi.org/project/arnmatch/) [](https://pypi.org/project/arnmatch/) [](LICENSE) [](https://pypi.org/project/arnmatch/) `arnmatch` 是一个零依赖的 Python 库和 CLI，用于将 AWS ARN （Amazon Resource Names）解析为结构化的资源数据。它能识别 AWS 服务、区域、账户、资源类型、资源 ID、CloudFormation 资源类型、 Resource Groups Tagging API 类型以及 boto3 SDK 服务名称。 大多数 ARN 解析器将 ARN 分割为六个顶级字段。`arnmatch` 更进一步： 其针对特定服务的匹配引擎是从 [《AWS 服务授权参考》](https://docs.aws.amazon.com/service-authorization/latest/reference/) 及相关 AWS 服务元数据生成的，因此它能够识别数千种真实的 AWS 资源格式，而不是依赖于一个小型的人工维护列表。 ## 为什么选择 arnmatch？ | 功能 | arnmatch | | --- | --- | | 解析 AWS ARN 分区、服务、区域和账户 | 是 | | 识别特定服务的资源类型 | 是 | | 提取资源 ID 和资源名称 | 是 | | 将 ARN 映射到 CloudFormation 资源类型 | 是 | | 将 ARN 映射到 Resource Groups Tagging API 类型 | 是 | | 将 ARN 映射到 boto3 SDK 客户端名称 | 是 | | AWS 服务覆盖范围 | 350+ 个服务 | | ARN 资源模式覆盖范围 | 2,100+ 种模式 | | 解析时的运行时依赖 | 0 | ## 常见用例 - 构建 AWS 清单、CSPM、云安全和资产管理工具。 - 规范化不同 AWS API 返回的 ARN。 - 将发现的资源映射到 CloudFormation 资源类型。 - 确定哪个 boto3 客户端可以操作特定资源。 - 从 ARN 中提取 AWS 账户 ID、区域、资源 ID 和资源名称。 - 验证一个 ARN 是否属于已知的 AWS 服务/资源模式。 ## 安装说明 ``` pip install arnmatch ``` ## 快速开始 ### 命令行界面 ``` $ arnmatch "arn:aws:lambda:us-east-1:123456789012:function:my-function" aws_service: lambda aws_sdk_service: lambda aws_sdk_services: lambda aws_region: us-east-1 aws_account: 123456789012 resource_type: function resource_id: my-function resource_name: my-function cloudformation_resource: AWS::Lambda::Function tagging_resource: AWS::Lambda::Function ``` ### Python 库 ``` from arnmatch import arnmatch result = arnmatch("arn:aws:lambda:us-east-1:123456789012:function:my-function") result.aws_service # "lambda" result.aws_region # "us-east-1" result.aws_account # "123456789012" result.resource_type # "function" result.resource_id # "my-function" result.resource_name # "my-function" result.cloudformation_resource # "AWS::Lambda::Function" result.tagging_resource # "AWS::Lambda::Function" result.aws_sdk_service # "lambda" ``` ## 示例 ### 解析 AWS ARN ``` from arnmatch import arnmatch arn = "arn:aws:s3:::my-bucket" resource = arnmatch(arn) print(resource.aws_service) # s3 print(resource.resource_type) # bucket print(resource.resource_name) # my-bucket ``` ### 将 AWS ARN 映射到 CloudFormation 资源类型 ``` from arnmatch import arnmatch resource = arnmatch("arn:aws:lambda:us-east-1:123456789012:function:my-function") print(resource.cloudformation_resource) # AWS::Lambda::Function 函数 ``` ### 将 AWS ARN 映射到 Resource Groups Tagging API 类型 ``` from arnmatch import arnmatch resource = arnmatch("arn:aws:rds:us-east-1:123456789012:db:my-database") print(resource.tagging_resource) # AWS::RDS::DBInstance 数据库实例 ``` ### 从 AWS ARN 获取 boto3 客户端 ``` import boto3 from arnmatch import arnmatch resource = arnmatch("arn:aws:lambda:us-east-1:123456789012:function:my-function") session = boto3.Session(region_name=resource.aws_region) client = resource.client(session=session) # 需要 AWS 凭证及调用 Lambda GetFunction 的权限。 client.get_function(FunctionName=resource.resource_name) ``` 解析器本身没有运行时依赖。可选的 `client()` 辅助方法需要你的应用程序环境中安装了 `boto3`。当你需要控制区域、配置文件、凭据或其他会话设置时，传递一个 boto3 会话。 ### 提取账户、区域、资源 ID 和资源名称 ``` from arnmatch import arnmatch resource = arnmatch("arn:aws:iam::123456789012:role/Admin") print(resource.aws_account) # 123456789012 print(resource.aws_region) # "" for global IAM resources print(resource.resource_type) # iam-role print(resource.resource_id) # Admin print(resource.resource_name) # Admin ``` ## 工作原理 `arnmatch` 生成其解析器数据，而不是手动编写 ARN 定义。生成管道从以下来源收集和协调 AWS 资源元数据： 1. AWS 服务授权参考 ARN 模式 2. CloudFormation 资源规范 3. Resource Groups Tagging API 资源映射 4. botocore/boto3 服务元数据 5. 针对 AWS 文档边缘情况的项目覆盖规则 生成的输出被编译到 `src/arnmatch/arn_patterns.py` 中，使得运行时包能够进行快速的本地正则表达式匹配，无需网络调用且没有运行时依赖。 ``` AWS docs + service metadata ↓ codegen pipeline ↓ generated ARN regex patterns and mappings ↓ zero-dependency Python parser ``` ## 功能特性 - ARN 解析零运行时依赖 - 350+ 个 AWS 服务和 2,100+ 种生成的 ARN 资源模式 - 特定服务的资源类型检测 - 资源 ID 和资源名称提取 - CloudFormation 资源类型映射 - Resource Groups Tagging API 类型映射 - boto3 SDK 服务名称映射 - CLI 和 Python 库接口 - 解析过程中无网络调用 ## API 参考 ### `arnmatch(arn: str) -> ARN` 解析一个 ARN 字符串并返回结构化数据。 如果 ARN 格式无效、AWS 服务未知或没有特定服务模式匹配，则抛出 `ARNError`。 ### `ARN` 包含已解析 ARN 组件的数据类： | 字段 | 类型 | 描述 | | --- | --- | --- | | `aws_partition` | `str` | AWS 分区，如 `aws`、`aws-cn` 或 `aws-us-gov` | | `aws_service` | `str` | ARN 中的 AWS 服务名称 | | `aws_region` | `str` | AWS 区域；对于全局资源可能为空 | | `aws_account` | `str` | AWS 账户 ID；对于某些全局/公共资源可能为空 | | `resource_type` | `str` | 来自生成的 AWS 模式的规范资源类型 | | `resource_types` | `list[str]` | 此资源类型的所有已知别名 | | `attributes` | `dict[str, str]` | 从特定服务 ARN 模式捕获的属性 | | `aws_sdk_service` | `str \| None` | 资源服务的主要 boto3 客户端名称 | | `cloudformation_resource` | `str \| None` | CloudFormation 资源类型，如 `AWS::Lambda::Function` | | `tagging_resource` | `str \| None` | Resource Groups Tagging API 类型 | 属性： | 属性 | 描述 | | --- | --- | | `resource_id` | 资源标识符；优先选择以 `Id` 结尾的捕获属性，然后是 `Name`，最后是最后一个资源属性 | | `resource_name` | 资源名称；优先选择以 `Name` 结尾的捕获属性，如果不存在则回退到 `resource_id` | | `aws_sdk_services` | 映射到 AWS 服务的所有 boto3 客户端名称，例如对于 `elasticloadbalancing`，其值为 `['elb', 'elbv2']` | 方法： | 方法 | 描述 | | --- | --- | | `client(session=None)` | 返回资源服务的 boto3 客户端。传递一个可选的 `boto3.Session`，或使用默认会话。如果没有 SDK 映射存在，则抛出 `ValueError`。 | ### `ARNError` 当 ARN 解析失败时引发的异常。继承自 `ValueError`。 ## 开发指南 前置条件：[uv](https://github.com/astral-sh/uv) ``` make lint # Run ruff linter make test # Run pytest tests make check # Run lint and test make generate # Regenerate patterns from AWS docs make build # Build wheel and tarball make publish # Build and upload to PyPI ``` 重新生成 ARN 模式数据： ``` cd codegen make clean make ``` 然后将生成的模式复制到包中并构建： ``` make build ``` ## 贡献指南 欢迎提交错误报告、补充缺失的 ARN 模式、更正映射以及改进文档。 有关本地设置和贡献指南，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 安全说明 有关漏洞报告或安全敏感问题，请参见 [SECURITY.md](SECURITY.md)。 ## 许可证 `arnmatch` 根据 [Apache License 2.0](LICENSE) 许可。 ## 版本控制 `arnmatch` 使用 [CalVer](https://calver.org/) 格式 `YYYY.MM.MICRO`，例如 `2026.3.3`。

标签：API映射, ARN解析, AWS, boto3, CLI, CloudFormation, CSPM, DPI, Python, TinkerPop, WiFi技术, 云服务, 占用监测, 工具开发, 文档结构分析, 无后门, 漏洞利用检测, 结构化数据, 自动代码生成, 资产管理, 资源管理, 资源识别, 逆向工具, 零依赖