ghalint

README

ghalint

Install | Policies | How to use | Configuration

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 anc action.yaml for security policy compliance.

Policies

1. Workflow Policies

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

2. Action Policies

1. action_ref_should_be_full_length_commit_sha: action's ref should be full length commit SHA
2. github_app_should_limit_repositories: GitHub Actions issueing GitHub Access tokens from GitHub Apps should limit repositories
3. github_app_should_limit_permissions: GitHub Actions issueing GitHub Access tokens from GitHub Apps should limit permissions
4. action_shell_is_required: shell is required if run is set

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

1. Validate workflows

Run the command ghalint run on the repository root directory.

ghalint run

Then ghalint validates workflow files ^\.github/workflows/.*\.ya?ml$.

2. Validate action.yaml

Run the command ghalint run-action.

ghalint run-action

The alias act is available.

ghalint act

Then ghalint validates action files ^action\.ya?ml$ on the current directory. You can also specify file paths.

ghalint act foo/action.yaml bar/action.yml

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

Disable policies

You can disable the following policies.

• deny_inherit_secrets
• job_secrets
• action_ref_should_be_full_length_commit_sha
• github_app_should_limit_repositories

e.g.

excludes:
  - policy_name: deny_inherit_secrets
    workflow_file_path: .github/workflows/actionlint.yaml
    job_name: actionlint
  - 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

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