📖 update docs for webhooks documentation (#3299)

* update docs for webhooks documentation Signed-off-by: leec94 <[email protected]> * change webhook severity in readme Signed-off-by: leec94 <[email protected]> --------- Signed-off-by: leec94 <[email protected]>
ossf · Jul 24, 2023 · 41a18ff · 41a18ff
1 parent 93ec2d1
commit 41a18ff
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -467,7 +467,7 @@ Name        | Description                               | Risk Level | Token Req
 [Signed-Releases](docs/checks.md#signed-releases)               | Does the project cryptographically [sign releases](https://wiki.debian.org/Creating%20signed%20GitHub%20releases)?                                                                                                                                                                                                           | High | PAT, GITHUB_TOKEN   | Validating |
 [Token-Permissions](docs/checks.md#token-permissions)           | Does the project declare GitHub workflow tokens as [read only](https://docs.github.com/en/actions/reference/authentication-in-a-workflow)?                                                                                                                                                                                   | High | PAT, GITHUB_TOKEN   | Unsupported |
 [Vulnerabilities](docs/checks.md#vulnerabilities)               | Does the project have unfixed vulnerabilities? Uses the [OSV service](https://osv.dev).                                                                                                                                                                                                                                      | High | PAT, GITHUB_TOKEN   | Validating |
-[Webhooks](docs/checks.md#webhooks)                             | Does the webhook defined in the repository have a token configured to authenticate the origins of requests?                                                                                                                                                                                                                                      | High | maintainer PAT (`admin: repo_hook` or `admin> read:repo_hook` [doc](https://docs.github.com/en/rest/webhooks/repo-config#get-a-webhook-configuration-for-a-repository)  |  | EXPERIMENTAL
+[Webhooks](docs/checks.md#webhooks)                             | Does the webhook defined in the repository have a token configured to authenticate the origins of requests?                                                                                                                                                                                                                                      | Critical | maintainer PAT (`admin: repo_hook` or `admin> read:repo_hook` [doc](https://docs.github.com/en/rest/webhooks/repo-config#get-a-webhook-configuration-for-a-repository)  |  | EXPERIMENTAL
 
 ### Detailed Checks Documentation
 

diff --git a/docs/checks.md b/docs/checks.md
@@ -65,7 +65,7 @@ certain workflows for branches, such as requiring review or passing certain
 status checks before acceptance into a main branch, or preventing rewriting of
 public history.
 
-Note: The following settings queried by the Branch-Protection check require an admin token: `DismissStaleReviews`, `EnforceAdmin`, `StrictStatusCheck` and `RequireCodeownerReview`. If
+Note: The following settings queried by the Branch-Protection check require an admin token: `DismissStaleReviews`, `EnforceAdmins`, `RequireLastPushApproval`, `RequiresStatusChecks` and `UpToDateBeforeMerge`. If
 the provided token does not have admin access, the check will query the branch
 settings accessible to non-admins and provide results based only on these settings.
 Even so, we recommend using a non-admin token, which provides a thorough enough
@@ -102,27 +102,27 @@ commit.
 
 This test has tiered scoring. Each tier must be fully satisfied to achieve points at the next tier. For example, if you fulfill the Tier 3 checks but do not fulfill all the Tier 2 checks, you will not receive any points for Tier 3.
 
-Note: If Scorecard is run without an administrative access token, the requirements that specify “For administrators” are ignored.
+Note: If Scorecard is run without an administrative access token, the requirements that specify “For administrators” can be safely ignored, and scores will be determined as if all such requirements have been met.
 
 Tier 1 Requirements (3/10 points):
   - Prevent force push
   - Prevent branch deletion
   - For administrators: Include administrator for review
 
 Tier 2 Requirements (6/10 points):
-  - Required reviewers >=1
-  - For administrators: Last push review
-  - For administrators: Strict status checks (require branches to be up-to-date before merging)
+  - Require at least 1 reviewer for approval before merging
+  - For administrators: Require branch to be up to date before merging
+  - For administrators: Require approval of the most recent reviewable push
 
 Tier 3 Requirements (8/10 points):
-  - Status checks defined
+  - Require branch to pass at least 1 status check before merging
 
 Tier 4 Requirements (9/10 points):
-  - Required reviewers >= 2
+  - Require at least 2 reviewers for approval before merging
+  - Require review from code owners
 
 Tier 5 Requirements (10/10 points):
-  - For administrators: Dismiss stale reviews
-  - For administrators: Require CODEOWNER review
+  - For administrators: Dismiss stale reviews and approvals when new commits are pushed
 
 GitLab Integration Status:
   - GitLab associates releases with commits and not with the branch. Releases are ignored in this portion of the scoring.
@@ -677,6 +677,6 @@ This check determines whether the webhook defined in the repository has a token
 
 **Remediation steps**
 - Check whether your service supports token authentication.
-- If there is support for token authentication, set the secret in the webhook configuration. See [Setting up a webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#setting-up-a-webhook)
-- If there is no support for token authentication, consider implementing it by following [these directions](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks).
+- If there is support for token authentication, set the secret in the webhook configuration. See [Setting up a webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#setting-up-a-webhook).
+- If there is no support for token authentication, request the webhook service implement token authentication functionality by following [these directions](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks).
 
diff --git a/docs/checks/internal/checks.yaml b/docs/checks/internal/checks.yaml
@@ -814,10 +814,10 @@ checks:
         such as `LICENSES/Apache-2.0.txt`.
 
   Webhooks:
-    risk: High
+    risk: Critical
     tags: security, infrastructure
     repos: GitHub
-    short: This check validate if the webhook defined in the repository have a token configured.
+    short: This check validates if the webhook defined in the repository has a token configured.
     description: |
       Risk: `Critical` (service possibly accessible to third parties)
 
@@ -826,6 +826,6 @@ checks:
       - >-
         Check whether your service supports token authentication.
       - >-
-        If there is support for token authentication, set the secret in the webhook configuration. See [Setting up a webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#setting-up-a-webhook)
+        If there is support for token authentication, set the secret in the webhook configuration. See [Setting up a webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks#setting-up-a-webhook).
       - >-
-        If there is no support for token authentication, consider implementing it by following [these directions](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks).
+        If there is no support for token authentication, request the webhook service implement token authentication functionality by following [these directions](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks).