Add docs on resolving CKV2_GHA_1: "Ensure top-level permissions are not set to write-all"

[JoshuaKGoldberg]

Coming over from https://github.com/eslint/eslint/issues/19356: debugging a the CHKV2_GHA_1 message:

.github/workflows/stale.yml:15:1
 15:1  high  Ensure top-level permissions are not set to write-all  checkov/CKV2_GHA_1

There isn't much documentation on the check that I could find. From https://www.checkov.io/5.Policy%20Index/github_actions.html:

CKV2_GHA_1 | resource | permissions | Ensure top-level permissions are not set to write-all | github_actions | ReadOnlyTopLevelPermissions.yaml

...but that's it, seemingly, on checkov.io?

Request: for at least this rule -and ideally all of the GHA checks-, could the site include an explainer with multi-sentence descriptions of:

• What the rule checks for
• Why it checks for that
• How to resolve its reports

For reference, the ESLint and typescript-eslint docs tend to do this:

• https://eslint.org/docs/latest/rules/for-direction
• https://typescript-eslint.io/rules/await-thenable

Note that this is related to #4127. I filed a new issue here because that one has a lot of comments and seems to be user questions focused on understanding the issue, not a docs request.

[huornlmj]

+1

[chicks-net]

I had asked

Does anyone know how to fix CKV2_GHA_1 instead of just disabling it?

Then I found https://github.com/eslint/eslint/issues/19356#issuecomment-2605433950 looks like the solution.

[pfuhrmann]

Adding permissions: read-all is not a good solution. This allows every job in the workflow to read everything, which goes against the principle of least privilege. This check is fundamentally flawed in its current form.

[haku]

iiuc, the best fix is to add permissions: {} at the top of the file and then add explicit permissions to each section of jobs: etc.

edit: also the docs for this are here: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions

[chicks-net]

iiuc, the best fix is to add permissions: {} at the top of the file and then add explicit permissions to each section of jobs: etc.

Thank you so much. This absolutely makes more sense than what I was doing. 🥇

It would be great if the docs or error message could be improved to point more folks in this direction. It wasn't like I didn't care about security, but I didn't understand the best way to fix this aspect of security. I'm probably not alone. 😁