bridgecrew/yor

Yor Docker镜像文档

镜像概述和主要用途

Yor是一个开源工具，旨在为基础设施即代码（IaC）框架添加信息丰富且一致的标签。目前支持Terraform、CloudFormation和Serverless框架，可自动为IaC资源块添加标签。Yor可作为GitHub Action自动应用标签逻辑，也可作为pre-commit钩子或独立CLI工具运行，帮助团队实现云资源与IaC代码的关联追踪及变更管理。

核心功能和特性

• IaC目录标签应用：在IaC文件目录上批量应用标签和标签。
• 追踪功能：通过yor_trace标签实现IaC资源块与运行中的云资源之间的简单关联。
• 变更管理：基于Git的标签自动为每个资源块添加组织、仓库、提交和修改者详情。
• 自定义标签器：支持添加用户定义的标签逻辑。
• 跳过功能：通过内联注释允许开发者排除不应被标记的路径。
• Dry-Run模式：预览将要添加的标签，无需实际应用任何更改。

使用场景和适用范围

• 团队协作：需要在团队中统一IaC资源标签标准的场景。
• 云资源追踪：需将云环境中的资源快速关联到对应IaC代码块的场景。
• 变更审计：需要记录IaC资源修改历史（如提交者、修改时间）的审计需求。
• 多环境管理：通过自定义标签区分开发、测试、生产等不同环境的IaC资源。
• CI/CD集成：在代码提交或部署流程中自动添加标签，确保标签一致性。

详细的使用方法和配置说明

镜像拉取

bash
docker pull docker.xuanyuan.run/bridgecrew/yor

基本运行示例

在本地IaC目录上运行Yor添加标签：

bash
docker run --tty --volume /local/path/to/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag --directory /tf

说明：--volume /local/path/to/tf:/tf 将本地IaC目录挂载到容器内的/tf路径，tag --directory /tf指定对该目录下的IaC文件应用标签。

常用命令参数说明

tag命令（核心标签功能）

bash
# 对terraform目录树应用所有标签（递归）
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag --directory /tf

# 对terraform目录应用标签，不递归子目录
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag --directory /tf --non-recursive

# 仅应用指定标签（git_file和git_org）
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag --directory /tf --tags git_file,git_org

# 排除指定标签（以git开头和yor_trace标签）
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag --directory /tf --skip-tags git*,yor_trace

# 仅应用git标签组下的所有标签
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag --tag-groups git --directory /tf

# 应用自定义键值对标签（需设置环境变量）
docker run --tty -e YOR_SIMPLE_TAGS='{ "Environment" : "Dev" }' -v /local/tf/dev:/tf docker.xuanyuan.run/bridgecrew/yor tag --tag-groups simple --directory /tf

# Dry-Run模式（预览标签变更，不实际修改文件）
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --dry-run

# 使用外部标签组配置文件
docker run --tty -v /local/config:/config -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --config-file /config/custom_tags.yaml

# 排除特定类型的资源（如aws_s3_bucket）
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --skip-resource-types aws_s3_bucket

# 为标签添加前缀
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --tag-prefix "module_"

# 排除指定名称的资源
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --skip-resources aws_s3_bucket.operations

# 仅对指定框架应用标签
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --parsers Terraform,CloudFormation

输出格式控制

bash
# 默认CLI输出
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf -o cli

# JSON格式输出
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf -o json

# 同时输出CLI和JSON文件（便于程序分析+人工阅读）
docker run --tty -v /local/tf:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --output cli --output-json-file /tf/result.json

跳过目录

bash
# 对path/to/files应用标签，跳过指定子目录
docker run --tty -v /local/path/to/files:/tf docker.xuanyuan.run/bridgecrew/yor tag -d /tf --skip-dirs /tf/skip,/tf/another/skip2

列出标签

bash
# 列出内置标签组
docker run --tty docker.xuanyuan.run/bridgecrew/yor list-tag-groups

# 列出所有内置标签
docker run --tty docker.xuanyuan.run/bridgecrew/yor list-tags

# 列出git标签组下的所有标签
docker run --tty docker.xuanyuan.run/bridgecrew/yor list-tags --tag-groups git

支持的注释格式

通过特定注释可排除资源或文件被标签化，目前支持Terraform和CloudFormation文件：

排除特定资源

hcl
# Terraform示例
#yor:Skip 
resource "aws_instance" "example_instance" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

# CloudFormation示例
#yor:skip
ExampleInt:
  Type: AWS::Lambda::Function
  Properties:
    Description: An example template

排除文件中所有资源

hcl
# Terraform示例
#yor:skipAll
resource "aws_vpc" "example_vpc" {
  cidr_block = "10.0.0.0/16" 
}

# CloudFormation示例
#yor:skipAll
Resources:
  NewVolume:
    Type: AWS::EC2::Volume
    Properties:
      Size: 100

Yor Trace说明

yor_trace是一个特殊标签，为IaC资源代码块创建唯一标识符。通过该标签，无需访问敏感的plan或state文件，即可将云资源与对应的IaC代码块关联，实现从云资源到代码的追踪。

其他安装方式（非Docker）

• MacOS/Linux（Brew）：

  bash
  brew tap bridgecrewio/tap
  brew install bridgecrewio/tap/yor
  

• Windows（Chocolatey）：

  bash
  choco install yor
  

• GitHub Action：

  yaml
  name: IaC trace
  on: [push, pull_request]
  jobs:
    yor:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
          with:
            fetch-depth: 0
        - name: Run yor action
          uses: bridgecrewio/yor-action@main
  

支持与贡献

• 支持：通过Slack社区获取帮助
• 贡献：欢迎扩展Yor功能，提交PR前请运行golangci-lint run --fix --skip-dirs tests/yor_plugins确保代码规范