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.

💡 We've ported ghalint to lintnet module

• https://lintnet.github.io/
• https://github.com/lintnet-modules/ghalint

lintnet is a general purpose linter powered by Jsonnet. We've ported ghalint to the lintnet module, so you can migrate ghalint to lintnet!

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
11. job_timeout_minutes_is_required: All jobs should set timeout-minutes
12. checkout_persist_credentials_should_be_false: actions/checkout's input persist-credentials should be false

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
5. checkout_persist_credentials_should_be_false: actions/checkout's input persist-credentials should be false

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

JSON Schema

• ghalint.json
• https://raw.githubusercontent.com/suzuki-shunsuke/ghalint/refs/heads/main/json-schema/ghalint.json

If you look for a CLI tool to validate configuration with JSON Schema, ajv-cli is useful.

ajv --spec=draft2020 -s json-schema/ghalint.json -d ghalint.yaml

Input Complementation by YAML Language Server

# yaml-language-server: $schema=https://raw.githubusercontent.com/suzuki-shunsuke/ghalint/refs/heads/main/json-schema/ghalint.json

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