Updates the permissions block to be minimal

[aeisenberg]

And adds a permissions block to the README.

Fixes #464.

Merge / deployment checklist

• Confirm this change is backwards compatible with existing workflows.
• Confirm the readme has been updated if necessary.
• Confirm the changelog has been updated if necessary.

[adityasharad]

From our last internal discussion about this, I believe that actions: read is (only) needed if you are analyzing a private repository, and security-events: write is (only) needed if you are not analyzing a pull request. And I think we need at least contents: read (or pull-requests: read for PRs). The overlapping scopes for PRs make this a bit confusing.

So perhaps let's go with the recommendation of actions: read, contents: read, security-events: write? If it turns out that's not entirely minimal, we can refine it again later.

[aeisenberg]

Sure, and I can add some comments on when different scopes may not be needed.

[aeisenberg]

Here are the API calls we are making (just doing a code search for .request:

• GET /repos/:owner/:repo/actions/runs/:run_id (actions: read)
• GET /repos/:owner/:repo/actions/workflows (actions: read)
• PUT /repos/:owner/:repo/code-scanning/analysis/status (security-events: write)
• GET /enterprise/code-scanning/codeql-bundle/find/{tag} (security-events: read)
• GET /enterprise/code-scanning/codeql-bundle/download/{asset_id} (security-events: read)
• GET /repos/:owner/:repo/code-scanning/codeql/databases (security-events: read)
• PUT /repos/:owner/:repo/code-scanning/codeql/databases/:language (security-events: write)
• PUT /repos/:owner/:repo/code-scanning/analysis (security-events: write)

Unless I've missed something, we only need security-events: write and actions: read. And the latter is only for private repos.

[adityasharad]

Plus you need enough permission to check out the repo itself in the workflow (but not in the Action), which I believe is either contents: read or pull_requests: read.

[aeisenberg]

Ah..yes. Again, only for private repos, it seems. So, contents: read guards the GET /repos/:owner/:repo/contents/:path endpoint. I don't see anything about pull requests, though. This would only be for things like editing the PR itself, or adding comments, etc.

[adityasharad]

LGTM once you resolve the changelog conflict. Thanks!

[naveensrinivasan]

Here are the API calls we are making (just doing a code search for .request:

• GET /repos/:owner/:repo/actions/runs/:run_id (actions: read)
• GET /repos/:owner/:repo/actions/workflows (actions: read)
• PUT /repos/:owner/:repo/code-scanning/analysis/status (security-events: write)
• GET /enterprise/code-scanning/codeql-bundle/find/{tag} (security-events: read)
• GET /enterprise/code-scanning/codeql-bundle/download/{asset_id} (security-events: read)
• GET /repos/:owner/:repo/code-scanning/codeql/databases (security-events: read)
• PUT /repos/:owner/:repo/code-scanning/codeql/databases/:language (security-events: write)
• PUT /repos/:owner/:repo/code-scanning/analysis (security-events: write)

Unless I've missed something, we only need security-events: write and actions: read. And the latter is only for private repos.

@aeisenberg I am trying to figure out the required permissions for any GitHub Action. What is the process to get all the necessary permission? Thanks

[aeisenberg]

There's no principled way of doing this that I can think of. An action can make any arbitrary request to the github api. And it can make requests in many ways (since they are just fundamentally REST requests): curl, gh, octokit, etc.

You could try setting very restrictive permissions, and slowly loosen them until you get your workflow passing. Alternatively, you can try to eyeball the code, which could be tricky if the action is doing non-standard things.

[naveensrinivasan]

There's no principled way of doing this that I can think of. An action can make any arbitrary request to the github api. And it can make requests in many ways (since they are just fundamentally REST requests): curl, gh, octokit, etc.

You could try setting very restrictive permissions, and slowly loosen them until you get your workflow passing. Alternatively, you can try to eyeball the code, which could be tricky if the action is doing non-standard things.

Thank you!