🚨 Important Update: Restrictive Default GITHUB_TOKEN Permissions Coming Soon

[felddy]

Hello cisagov team,

We’re announcing an upcoming change to the default GITHUB_TOKEN permissions for all repositories within our GitHub organization. Starting in the next few days, the default permissions will shift from permissive to restrictive, a change aimed at improving security by limiting repository access.

What This Means for You

With restrictive permissions, workflows will have fewer permissions by default, meaning that any workflow relying on elevated access will require explicit permission settings to continue functioning as expected.

Current State (Permissive)

Currently, the GITHUB_TOKEN in our workflows has read and write access across all scopes. This includes:

• Read and Write Access to contents, packages, and all other scopes.

Future State (Restrictive)

After the change, the GITHUB_TOKEN will default to only having:

• Read Access for the contents and packages scopes.

Potential Impact

Workflows that currently rely on broader permissions without defining specific permissions in their configuration may experience errors. This includes workflows performing actions like pushing to branches, accessing protected resources, or managing issues and pull requests.

What You Need to Do

1. Assess your workflows: Identify any workflows that may rely on permissions beyond the restrictive defaults.

2. Use GitHub's new permissions helper tool:
   GitHub recently introduced a tool to help developers determine the exact permissions settings required for their workflows.

   Read more about the tool in GitHub’s blog post:
   New tool to secure your GitHub Actions

3. Update your workflows:
   If you find any workflows requiring more than the default restrictive permissions, explicitly add a permissions block to your workflow YAML. This change will ensure that your workflows continue to function as expected after the update.

   permissions:
     contents: write
     issues: read

4. Test and verify:
   Once you’ve updated permissions, test your workflows to confirm they operate correctly under the new restrictive settings.

Tip

If your repository is a descendant of one of our skeleton repositories, you can expect to receive an automated pull request with the necessary changes to your workflows.

Example Workflow Update

name: Example Workflow
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2

      - name: Run tests
        run: ./run-tests.sh

      - name: Build and push changes
        run: ./deploy.sh

Updated Workflow with Permissions

name: Example Workflow
on:
  push:
    branches:
      - main

permissions:
  contents: write   # Allows pushing changes to branches
  issues: read      # Allows reading issue data

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2

      - name: Run tests
        run: ./run-tests.sh

      - name: Build and push changes
        run: ./deploy.sh

Mentions: @cisagov/gov @cisagov/cdi-adg @cisagov/cisa-ea @cisagov/csso @cisagov/cyber-dhs-gov @cisagov/decider @cisagov/esi-interns @cisagov/handbook-team @cisagov/icsnpp-admins @cisagov/industrial-control-systems-section @cisagov/ivaal @cisagov/jcdc @cisagov/lme @cisagov/nrmc @cisagov/nrmc-hssedi @cisagov/nrmc-is4s @cisagov/nsd @cisagov/pnnl @cisagov/scuba @cisagov/steps @cisagov/team-cdet @cisagov/team-cpg @cisagov/team-inl @cisagov/team-sei @cisagov/team-th @cisagov/team-vm @cisagov/vince

[h-m-f-t]

I've created cisagov/manage.get.gov#2999 as a parent issue for several of my team's repos. Sharing in case it's useful for anyone else.

[barksar]

Thanks Cameron!

[CyberGardener]

Thank you for sharing! 😊

[mcdonnnj]

I created cisagov/skeleton-generic#190 to add the GitHubSecurityLab/actions-permissions/monitor Action to our workflows to get permission recommendations. It will flow down to any repositories that utilize our skeleton system once it is is merged and can be used to dial in the specific permissions each workflow it is added to will need to function.