Skip to main content

Enable Checksum Verification

About Checksum Verification, please see also.

Create a GitHub Repository​

Let's create a GitHub Repository for this tutorial. You can remove the repository after this tutorial.

Prepare GitHub Access Token​

Please create a classic personal access token and add it to Repository Secrets.

  • name: GH_TOKEN
  • required permissions: contents: write
caution

GitHub Actions' token GITHUB_TOKEN is unavailable.

info

Unfortunately, fine-grained personal access token is unavailable at the moment because it doesn't support GraphQL API. https://github.com/cli/cli/issues/6680

2023-04-27 fine-grained access token supports GraphQL API now.

info

In this time we use a classic personal access token, but we recommend GitHub App or fine-grained access token in terms of security.

Create aqua.yaml​

aqua init
aqua g -i suzuki-shunsuke/tfcmt

Enable Checksum Verification​

By default, checksum verification is disabled. Let's edit aqua.yaml and enable Checksum Verification.

---
checksum:
  enabled: true
registries:
- type: standard
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry
packages:
- name: suzuki-shunsuke/tfcmt@v4.2.0

Set up GitHub Actions Workflow​

caution

For CircleCI Users, please use circleci-orb-aqua's update-checksum command instead.

To create and update aqua-checksum.json automatically, let's set up GitHub Actions.

mkdir -p .github/workflows
vi .github/workflows/update-aqua-checksum.yaml
name: update-aqua-checksum
on:
  pull_request:
    paths:
      - aqua.yaml
      - aqua-checksums.json
jobs:
  update-aqua-checksums:
    uses: aquaproj/update-checksum-workflow/.github/workflows/update-checksum.yaml@d3ab3ae1f9db2320a23efeaf9baaafeaae45af56 # v1.0.6
    permissions:
      contents: read
    with:
      aqua_version: v2.48.3
      prune: true
    secrets:
      gh_token: ${{secrets.GH_TOKEN}}
      # gh_app_id: ${{secrets.APP_ID}}
      # gh_app_private_key: ${{secrets.APP_PRIVATE_KEY}}

We use update-checksum-action.

Create a pull request​

Commit aqua.yaml and .github/workflows/update-aqua-checksum.yaml.

git checkout -b ci/aqua-checksum
git add aqua.yaml .github/workflows/update-aqua-checksum.yaml
git commit -m "ci: add aqua.yaml and set up workflow"
git push origin ci/aqua-checksum

Create a pull request. Then aqua-checksums.json will be created by GitHub Actions.

image

image

Change a package version​

Let's change version.

sed -i "s/v4.2.0/v4.1.0/" aqua.yaml
-- name: suzuki-shunsuke/tfcmt@v4.2.0
+- name: suzuki-shunsuke/tfcmt@v4.1.0

Push a commit.

git pull origin ci/aqua-checksum
git add aqua.yaml
git commit -m "chore: change tfcmt version"
git push origin "ci/aqua-checksum"

Then aqua-checksums.json is updated automatically.

image

image

See how Checksum Verification prevents tampering​

Let's see how Checksum Verification prevents tampering. It's bothersome to tamper assets actually, so in this time let's simulate the situation by tampering checksum in aqua-checksums.json.

git pull origin ci/aqua-checksum
vi aqua-checksums.json
     {
       "id": "github_release/github.com/suzuki-shunsuke/tfcmt/v4.1.0/tfcmt_linux_amd64.tar.gz",
-      "checksum": "A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D91",
+      "checksum": "A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D92",
       "algorithm": "sha256"
     },

Add a GitHub Actions job that runs a tampered package.

  test:
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    env:
      AQUA_LOG_COLOR: always
      AQUA_REQUIRE_CHECKSUM: "true"
    steps:
      - uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v6-beta
      - uses: aquaproj/aqua-installer@82d0e83878a8657c4a6f2ff1755d3bfbfc67f329 # v4.1.0
        with:
          aqua_version: v2.48.3
        env:
          GITHUB_TOKEN: ${{github.token}}
      - run: tfcmt -v
git add aqua-checksums.json
git commit -m "chore: tamper aqua-checksums.json"
git push origin "ci/aqua-checksum"

Then test job would fail because the checksum is unmatched.

image

time="2023-03-12T06:36:05Z" level=fatal msg="aqua failed" actual_checksum=A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D91 aqua_version=2.28.0 env=linux/amd64 error="checksum is invalid" exe_name=tfcmt expected_checksum=A8E55BEA1A5F94F9515FD9C5C3296D1874461BA1DBD158B3FC0ED6A0DB3B7D92 package=suzuki-shunsuke/tfcmt package_version=v4.1.0 program=aqua

Please consider autofix.ci or Securefix Action instead of update-checksum-action and update-checksum-workflow​

Instead of update-checksum-action and update-checksum-workflow, we recommend autofix.ci or Securefix Action for security.

  • autofix.ci: For OSS
  • Securefix Action: For private repositories

autofix.ci​

About autofix.ci, please see the website. https://autofix.ci/ autofix.ci is free for OSS. autofix.ci has various benefits:

  • You can fix pull requests from fork securely
  • Easy to use. You don't need to take care of how to create and push commits
  • Commits are verified
  • You no longer need to branch processing based on whether the pull request is from a fork or not

We're using autofix.ci in various places.

e.g. https://github.com/aquaproj/aqua-renovate-config/blob/main/.github/workflows/autofix.yaml

This is an example workflow:

name: autofix.ci
on: pull_request
permissions: {}
jobs:
  autofix:
    runs-on: ubuntu-26.04
    permissions: {}
    timeout-minutes: 15
    steps:
      - name: Checkout the repository
        uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v6-beta
        with:
          persist-credentials: false
      - name: Install aqua
        uses: aquaproj/aqua-installer@82d0e83878a8657c4a6f2ff1755d3bfbfc67f329 # v4.1.0
        with:
          aqua_version: v2.43.0
      - name: Fix aqua-checksums.json
        run: aqua upc -prune
      - name: Run autofix.ci
        uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4

Securefix Action​

About Securefix Action, please see the document. You can update aqua-checksums.json using Securefix Action and aqua upc command:

e.g.

name: Update aqua-checksums.json
on: pull_request
permissions: {}
jobs:
  securefix:
    runs-on: ubuntu-26.04
    permissions: {}
    timeout-minutes: 15
    steps:
      - name: Checkout the repository
        uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v6-beta
        with:
          persist-credentials: false
      - name: Install aqua
        uses: aquaproj/aqua-installer@82d0e83878a8657c4a6f2ff1755d3bfbfc67f329 # v4.1.0
        with:
          aqua_version: v2.43.0
      - name: Fix aqua-checksums.json
        run: aqua upc -prune
      - name: Commit and push
        uses: securefix-action/action@1b770a7af0ec5e04517295b4e14c4b451359d550 # v0.6.3
        with:
          app_id: ${{secrets.APP_ID}}
          app_private_key: ${{secrets.APP_PRIVATE_KEY}}
          server_repository: demo-client

commit-action​

You can also use suzuki-shunsuke/commit-action. But we recommend Securefix Action for security.

e.g.

name: Update aqua-checksums.json
on: pull_request
permissions: {}
jobs:
  update-aqua-checksums:
    runs-on: ubuntu-26.04
    permissions: {}
    timeout-minutes: 15
    steps:
      - name: Checkout the repository
        uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v6-beta
        with:
          persist-credentials: false
      - name: Install aqua
        uses: aquaproj/aqua-installer@82d0e83878a8657c4a6f2ff1755d3bfbfc67f329 # v4.1.0
        with:
          aqua_version: v2.43.0
      - name: Fix aqua-checksums.json
        run: aqua upc -prune
      - name: Commit and push
        uses: suzuki-shunsuke/commit-action@5eaa5ecce3ffe93d09a85b946dc5136e3713b1b7 # v1.1.0
        with:
          app_id: ${{secrets.APP_ID}}
          app_private_key: ${{secrets.APP_PRIVATE_KEY}}