Checklist:

• Commit Message Formatting: Commit titles and messages follow guidelines in the
  conventional commits.
• Changelog updated with breaking and/or notable changes for the next minor release.
• Documentation has been updated, if necessary.
• Unit tests have been added, if necessary.
• Functional tests have been added, if necessary.
• E2E Workflow tests have been added, if necessary.

Overview

This GitHub action is used to:

1. Detect when GitHub secrets would be accidentally exposed through GitHub workflows that auto-trigger on PR builds, and
2. Notify the PR author and reviewers about the security concerns before the PR gets merged into main.

NOTE: When we talk about "auto-triggered workflows", we're essentially talking about the small E2E job, medium E2E job, unit tests, etc. because they automatically run any time a given contributor creates a pull request and/or pushes a new commit to an existing pull request. In the cases of the large E2E and x-large E2E jobs, neither of them auto-trigger on PR builds, which means if a PR author or reviewer wants the large/x-large E2E test to run on a PR, a trusted repo maintainer must review the PR's proposed changes and manually trigger the desired E2E job if they do not see any security concerns.

What is Specifically Analyzed

This action looks to see if any secrets are loaded into Git workflow environment variables, like in this case with top-level environment secrets:

name: "Some E2E Job"

 # <<< Exposed secrets at the top level (global) >>>
env:
  SECRET_TOKEN: ${{ secrets.SECRET_TOKEN }}
  SECRET_KEY: ${{ secrets.SECRET_KEY }}

jobs:
  some-job: {}
  some-other-job: {}

or secrets embedded into individual steps:

name: "Some E2E Job"

jobs:

  some-job:
    steps:
      # <<< Exposed secrets at the step level (local to the job, but still an issue) >>>
      - name: First step
        env:
          SECRET_TOKEN: ${{ secrets.SECRET_TOKEN }}
          SECRET_KEY: ${{ secrets.SECRET_KEY }}
        run: some-cmd

  some-other-job:
    steps:
      # <<< Exposed secrets at the step level (local to the job, but still an issue) >>>
      - name: First step
        env:
          SECRET_TOKEN: ${{ secrets.SECRET_TOKEN }}
          SECRET_KEY: ${{ secrets.SECRET_KEY }}
        uses: some-instructlab-gh-action

Since GitHub secrets are defined using the form ${{ secrets.SECRET_NAME }}, we can iterate through the env blocks in the file and use regular expressions to detect GitHub secrets.

What is Not Analyzed

This check does not look to see if a user outright copy-pastes a token or a password. In other words, it does NOT detect something like:

name: "Some E2E Job"

jobs:
  some-job:
    steps:

      # Password strings are not detected
      - name: Store my password to the GitHub env
        run: echo "MY_PASSWORD=my-super-secret-password" >> $GITHUB_ENV

      # Neither are tokens or API keys, like git tokens
      - name: Store my git token to the GitHub env
        run: echo "git_token=ghp_1234567890" >> $GITHUB_ENV

How it Works

This new in-house GitHub action allows the repository maintainers to either provide a valid path to a Git workflow file (via the --file flag) OR provide a directory to read Git workflow files from (via the --dir flag). Providing both flags simultaneously is not allowed or supported, and is blocked by the CLI. (Just call the CLI tool each time you want to check a new location.)

The tool then validates that: (1.) it can find the desired YAML file(s), and (2.) that the YAML files are indeed Git workflow files, not any random YAML file. If any valid Git workflow files are found, the tool then parses those workflow files to determine if any GitHub secrets are loaded into environment variables, either at the top-level of the workflow file OR through any one of the jobs' steps.

Example output from this PR's build:

Additional Info

I named this check security-lint because the tool that powers it technically falls under the category of "linters". However, I don't think it falls 100% under the existing "lint" category, as this linter is dedicated more towards security and not formatting etc.. I figure we can put future security lint steps in the same section of the lint.yml file later on as well, if we need to add more.