From ee0b0338ce4ee4984c393f97b7257cb3ff8f72f4 Mon Sep 17 00:00:00 2001 From: Mark Johnson <739719+virgofx@users.noreply.github.com> Date: Mon, 14 Oct 2024 01:32:55 +0000 Subject: [PATCH] docs: update README and SECURITY for GITHUB_TOKEN usage - Updated README.md to remove reference to custom PATs. - Clarified SECURITY.md with details on using the default GITHUB_TOKEN for scoped access, security, and simplified token management. --- README.md | 12 ++++++++++-- SECURITY.md | 26 ++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1a1fcb0..e74c5f2 100644 --- a/README.md +++ b/README.md @@ -124,8 +124,8 @@ requests and creating releases. for `pull-requests` must be set to `"write"`. - Additionally, the workflow permission for `contents` must also be set to `"write"` to allow the action to create tags and releases. -- If you are using a Personal Access Token (PAT), ensure that it has the `repo` scope granted. This permission is - required for the action to read and write to the repository, including managing pull requests and creating releases. +- For security considerations and best practices when using the `github_token` or PATs, please refer to the + [Security Documentation](./security.md). - Ensure the **Restrict editing to users in teams with push access only** setting is enabled for public repositories, as the GitHub Actions Bot can write to the wiki by default. @@ -209,3 +209,11 @@ by Piotr Krukowski. your workflow, this action will not be triggered. An alternative approach would be to split this action into two separate actions and workflows, one for pull requests and one for direct pushes to the main branch. However, this would require additional configuration and setup in the calling code. + +## License + +The scripts and documentation in this project are released under the [MIT License](./LICENSE.md). + +## Security + +For detailed information about security practices and guidelines, check out the [Security Documentation](./security.md). diff --git a/SECURITY.md b/SECURITY.md index a38313f..fbd90e2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -36,6 +36,32 @@ security risks, we recommend the following practices when using this Action: - **Audit GitHub Actions dependencies** regularly to ensure that no third-party actions have introduced vulnerabilities or insecure behaviors. +## Why This Action Uses the Default `GITHUB_TOKEN` + +This action utilizes the default `GITHUB_TOKEN` for several important reasons, ensuring that it operates efficiently and +securely: + +1. **Scoped Access to the Current Repository**: The `GITHUB_TOKEN` is automatically generated by GitHub for every + workflow run and is scoped to the repository in which the action is triggered. It provides the necessary permissions + to interact with that specific repository, such as reading pull request data, interacting with GitHub APIs, and + making commits. Since this action operates within the same repository, there’s no need for external authentication or + elevated permissions, ensuring minimal access for optimal security. + +1. **No Cross-Repository Access**: This action does not require access to other repositories. The default `GITHUB_TOKEN` + is scoped only to the repository where the action is executed. This makes it unnecessary to configure additional + tokens or credentials, keeping the action simple and secure. + +1. **Security and Minimal Exposure**: The `GITHUB_TOKEN` is ephemeral—it is automatically revoked at the end of each + workflow run and does not persist beyond the scope of the action. This limits its exposure and prevents any misuse + beyond its intended purpose. + +1. **Simpler Token Management**: Using the `GITHUB_TOKEN` eliminates the need for manually managing personal access + tokens (PATs), which would require extra steps for setup, maintenance, and possible re-authentication. GitHub handles + the lifecycle of this token automatically, reducing the risk of human error and making this action more secure. + +By leveraging the default `GITHUB_TOKEN`, this action minimizes security risks, simplifies configuration, and ensures +that it remains efficient and secure. + ## Resources - [GitHub Actions Security Best Practices](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)