xiaoruiguo / yor

Extensible auto-tagger for your IaC files. The ultimate way to link entities in the cloud back to the codified resource which created it.

Yor is Universal Infrastructure-as-Code Tagging framework

Yor is an open-source tool that helps add informative and consistent tags across infrastructure-as-code frameworks such as Terraform, CloudFormation, and Serverless.

Yor is built to run as a GitHub Action that hydrates IaC code with consistent tagging logics. It can also run as a pre-commit hook and a standalone CLI.

Features

• Apply tags and labels on infrastructure as code directory
• Tracing: yor_trace tag enables simple attribution between an IaC resource block and a running cloud resource.
• Change management: git-based tags automatically add org, repo, commit and modifyer details on every resource block.
• Custom taggers: user-defined tagging logics can be added to run using Yor.
• Skips: inline annotations enable developers to excluse paths that should not be tagged.

Demo

Attributing a directory with tags by user input

Attributing a resource to an owner

Change management tags

Trace IaC code to cloud resource

Trace cloud resource to IaC code

Table of contents

• Getting Started
• Support
• Customizing Yor

Getting Started

Installation

GitHub Action

name: IaC trace

on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  yor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        name: Checkout repo
        with:
          fetch-depth: 0
          ref: ${{ github.head_ref }}
      - name: Run yor action
        uses: bridgecrewio/yor-action@main
      - name: Commit tag changes
        uses: stefanzweifel/git-auto-commit-action@v4

MacOS

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

OR

Docker

docker pull bridgecrew/yor

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

Pre-commit

  - repo: git://github.com/bridgecrewio/yor
    rev: 0.0.44
    hooks:
      - id: yor
        name: yor
        entry: yor tag -d
        args: ["example/examplea"]
        language: golang
        types: [terraform]
        pass_filenames: false

Usage

tag : Apply tagging on a given directory.

 # Apply all the tags in yor on the directory tree terraform.
 ./yor tag --directory terraform/

# Apply all the tags in yor except the tags git_last_modified_by and yor_trace.
 ./yor tag --directory terraform/ --skip-tags git_last_modified_by,yor_trace

# Apply only the tags under the git tag group.
 ./yor tag --tag-groups git --directory terraform/

# Apply key-value tags on a specific directory
 export YOR_SIMPLE_TAGS='{ "Environment" : "Dev" }'
 ./yor tag --tag-groups simple --directory terraform/dev/

-o : Modify output formats.

./yor tag -d . -o cli
# default cli output

./yor tag -d . -o json
# json output

./yor tag -d . --output cli --output-json-file result.json
# print cli output and additional output to file on json file -- enables prgormatic analysis alongside printing human readable result

--skip-tags:Specify only named tags (allow list) or run all tags except those listed (deny list).

./yor tag -d . --skip-tags yor_trace
## Run all but yor_trace

./yor tag -d . --skip-tags yor_trace,git_modifiers
## Run all but yor_trace and git_modifiers

./yor tag -d . --skip-tags git*
## Run all tags except tags with specified patterns

skip-dirs : Skip directoruy paths you can define paths that will not be tagged.

./yor tag -d path/to/files
## Run on the directory path/to/files

./yor tag -d path/to/files --skip-dirs path/to/files/skip,path/to/files/another/skip2
## Run yor on the directory path/to/files, skipping path/to/files/skip/ and path/to/files/another/skip2/

list-tag

./yor list-tag-groups
 # List tag classes that are built into yor.
 
 ./yor list-tags
 # List all the tags built into yor
./yor list-tags --tag-groups git
 
 # List all the tags built into yor under the tag group git

What is Yor trace?

yor_trace is a magical tag creating a unique identifier for an IaC resource code block.

Having a yor_trace in place can help with tracing code block to its cloud provisioned resources without access to sensitive data such as plan or state files.

See demo here

Contributing

Contribution is welcomed!

We are working on extending Yor and adding more parsers (to support additional IaC frameworks) and more taggers (to tag using other contextual data).

To maintain our conventions, please run lint on your branch before opening a PR. To run lint:

golangci-lint run --fix --skip-dirs tests/yor_plugins

Support

If you need direct support you can contact us at https://slack.bridgecrew.io/.