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

* Adding missing documentation for Token-Permissions * Make documentation for `actions` more accurate Co-authored-by: Naveen <[email protected]> Co-authored-by: laurentsimon <[email protected]>
ossf · Feb 25, 2022 · 7610519 · 7610519
1 parent 4c82c29
commit 7610519
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 5 deletions.
diff --git a/checks/permissions.go b/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

diff --git a/docs/checks.md b/docs/checks.md
@@ -566,9 +566,22 @@ and the required write permissions are declared at the
 One point is reduced from the score if all jobs have their permissions defined but the top level permissions are not defined. 
 This configuration is secure, but there is a chance that when a new job is added to the workflow, its job permissions could be 
 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.   
+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**

diff --git a/docs/checks/internal/checks.yaml b/docs/checks/internal/checks.yaml
@@ -618,9 +618,23 @@ checks:
       One point is reduced from the score if all jobs have their permissions defined but the top level permissions are not defined. 
       This configuration is secure, but there is a chance that when a new job is added to the workflow, its job permissions could be 
       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.   
+      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