ghalint

README

ghalint

GitHub Actions linter for security best practices.

$ ghalint run
ERRO[0000] read a workflow file                          error="parse a workflow file as YAML: yaml: line 10: could not find expected ':'" program=ghalint version= workflow_file_path=.github/workflows/release.yaml
ERRO[0000] github.token should not be set to workflow's env  env_name=GITHUB_TOKEN policy_name=workflow_secrets program=ghalint version= workflow_file_path=.github/workflows/test.yaml
ERRO[0000] secret should not be set to workflow's env    env_name=DATADOG_API_KEY policy_name=workflow_secrets program=ghalint version= workflow_file_path=.github/workflows/test.yaml

ghalint is a command line tool to check GitHub Actions Workflows for security policy compliance.

Policies

• job_permissions: All jobs should have permissions
• deny_read_all_permission: read-all permission should not be used
• deny_write_all_permission: write-all permission should not be used
• deny_inherit_secrets: secrets: inherit should not be used
• workflow_secrets: Workflow should not set secrets to environment variables
• job_secrets: Job should not set secrets to environment variables
• deny_job_container_latest_image: Job's container image tag should not be latest
• action_ref_should_be_full_length_commit_sha: action's ref should be full length commit SHA
• github_app_should_limit_repositories: GitHub Actions issueing GitHub Access tokens from GitHub Apps should limit repositories
• github_app_should_limit_permissions: GitHub Actions issueing GitHub Access tokens from GitHub Apps should limit permissions

How to install

1. Homebrew:

brew install suzuki-shunsuke/ghalint/ghalint

1. Scoop

scoop bucket add suzuki-shunsuke https://github.com/suzuki-shunsuke/scoop-bucket
scoop install ghalint

1. aqua

aqua g -i suzuki-shunsuke/ghalint

1. Download a pre-built binary from GitHub Releases and locate an executable binary ghalint in PATH

How to use

$ ghalint help
NAME:
   ghalint - GitHub Actions linter

USAGE:
   ghalint [global options] command [command options] [arguments...]

VERSION:
    ()

COMMANDS:
   run      lint GitHub Actions Workflows
   version  Show version
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --log-color value         log color. auto(default)|always|never [$GHALINT_LOG_COLOR]
   --log-level value         log level [$GHALINT_LOG_LEVEL]
   --config value, -c value  configuration file path [$GHALINT_CONFIG]
   --help, -h                show help
   --version, -v             print the version

$ ghalint help run
NAME:
   ghalint run - lint GitHub Actions Workflows

USAGE:
   ghalint run [command options] [arguments...]

OPTIONS:
   --help, -h  show help

Configuration file

Configuration file path: ^\.?ghalint\.ya?ml$

You can specify the configuration file with the command line option -config (-c) or the environment variable GHALINT_CONFIG.

ghalint -c foo.yaml run

You can exclude the policy job_secrets and action_ref_should_be_full_length_commit_sha.

e.g.

excludes:
  - policy_name: job_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
  - policy_name: action_ref_should_be_full_length_commit_sha
    action_name: slsa-framework/slsa-github-generator
  - policy_name: github_app_should_limit_repositories
    workflow_file_path: .github/workflows/test.yaml
    job_name: test
    step_id: create_token

excludes[].policy_name

Required. You can exclude only the following policies.

• job_secrets
• action_ref_should_be_full_length_commit_sha
• github_app_should_limit_repositories

Environment variables

• GHALINT_CONFIG: Configuration file path
• GHALINT_LOG_LEVEL: Log level One of panic, fatal, error, warn, warning, info (default), debug, trace
• GHALINT_LOG_COLOR: Configure log color. One of auto (default), always, and never.

💡 If you want to enable log color in GitHub Actions, please try GHALINT_LOG_COLOR=always

env:
  GHALINT_LOG_COLOR: always

AS IS

TO BE

How does it works?

ghalint reads GitHub Actions Workflows ^\.github/workflows/.*\.ya?ml$ and validates them. If there are violatation ghalint outputs error logs and fails. If there is no violation ghalint succeeds.

LICENSE

MIT