📖 Adding missing documentation for Token-Permissions (#1656)

* Adding missing documentation for Token-Permissions

* Make documentation for `actions` more accurate

Co-authored-by: Naveen <172697+naveensrinivasan@users.noreply.github.com>
Co-authored-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>

checks/permissions.go

@@ -399,7 +399,7 @@ func calculateScore(result permissionCbData) int {
 		}
 
 		// actions.
-		// May allow an attacker to steal GitHub secrets by adding a malicious workflow/action.
+		// May allow an attacker to steal GitHub secrets by approving to run an action that needs approval.
 		// High risk: -10
 		if permissionIsPresent(perms, permissionActions) {
 			score -= checker.MaxResultScore

docs/checks.md

@@ -570,6 +570,19 @@ left undefined because of human error.
 The check cannot detect if the "read-only" GitHub permission setting is
 enabled, as there is no API available.
 
+Additionally, points are reduced if certain write permissions are defined for a job. 
+
+### Write permissions causing a small reduction
+* `statuses` - May allow an attacker to change the result of pre-submit checks and get a PR merged.
+* `checks` - May allow an attacker to remove pre-submit checks and introduce a bug.
+* `security-events` - May allow an attacker to read vulnerability reports before a patch is available. However, points are not reduced if the job utilizes a recognized action for uploading SARIF results.
+* `deployments` - May allow an attacker to charge repo owner by triggering VM runs, and tiny chance an attacker can trigger a remote service with code they own if server accepts code/location variables unsanitized.
+
+### Write permissions causing a large reduction
+* `contents` - Allows an attacker to commit unreviewed code. However, points are not reduced if the job utilizes a recognized packaging action or command.
+* `packages` - Allows an attacker to publish packages. However, points are not reduced if the job utilizes a recognized packaging action or command.
+* `actions` - May allow an attacker to steal GitHub secrets by approving to run an action that needs approval.
+ 
 
 **Remediation steps**
 - Set permissions as `read-all` or `contents: read` as described in GitHub's [documentation](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#permissions).

docs/checks/internal/checks.yaml

@@ -621,6 +621,20 @@ checks:
 
       The check cannot detect if the "read-only" GitHub permission setting is
       enabled, as there is no API available.
+
+      Additionally, points are reduced if certain write permissions are defined for a job. 
+
+      ### Write permissions causing a small reduction
+      * `statuses` - May allow an attacker to change the result of pre-submit checks and get a PR merged.
+      * `checks` - May allow an attacker to remove pre-submit checks and introduce a bug.
+      * `security-events` - May allow an attacker to read vulnerability reports before a patch is available. However, points are not reduced if the job utilizes a recognized action for uploading SARIF results.
+      * `deployments` - May allow an attacker to charge repo owner by triggering VM runs, and tiny chance an attacker can trigger a remote service with code they own if server accepts code/location variables unsanitized.
+
+      ### Write permissions causing a large reduction
+      * `contents` - Allows an attacker to commit unreviewed code. However, points are not reduced if the job utilizes a recognized packaging action or command.
+      * `packages` - Allows an attacker to publish packages. However, points are not reduced if the job utilizes a recognized packaging action or command.
+      * `actions` - May allow an attacker to steal GitHub secrets by approving to run an action that needs approval.
+ 
     remediation:
       - >-
         Set permissions as `read-all` or `contents: read` as described in