🌱 Merge main into golang-staging

.github/workflows/codeql-analysis.yml

@@ -39,7 +39,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@1ed1437484560351c5be56cf73a48a279d116b78 # v1.1.4
+      uses: github/codeql-action/init@2f58583a1b24a7d3c7034f6bf9fa506d23b1183b # v1.1.4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -50,7 +50,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@1ed1437484560351c5be56cf73a48a279d116b78 # v1.1.4
+      uses: github/codeql-action/autobuild@2f58583a1b24a7d3c7034f6bf9fa506d23b1183b # v1.1.4
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -64,4 +64,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@1ed1437484560351c5be56cf73a48a279d116b78 # v1.1.4
+      uses: github/codeql-action/analyze@2f58583a1b24a7d3c7034f6bf9fa506d23b1183b # v1.1.4

.github/workflows/golangci.yml

@@ -32,9 +32,9 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-      - uses: actions/setup-go@f6164bd8c8acb4a71fb2791a8b6c4024ff038dab #v2.1.5
+      - uses: actions/setup-go@fcdc43634adb5f7ae75a9d7a9b9361790f7293e2 #v2.1.5
         with:
           go-version: '1.17.x'
-      - uses: golangci/golangci-lint-action@b517f99ae23d86ecc4c0dec08dcf48d2336abc29
+      - uses: golangci/golangci-lint-action@537aa1903e5d359d0b27dbc19ddd22c5087f3fbc
         with:
           only-new-issues: true

.github/workflows/tests.yaml

@@ -34,14 +34,14 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-      - uses: actions/setup-go@f6164bd8c8acb4a71fb2791a8b6c4024ff038dab #v2.1.5
+      - uses: actions/setup-go@fcdc43634adb5f7ae75a9d7a9b9361790f7293e2 #v2.1.5
         with:
           go-version: '1.17.x'
       - name: Run Go tests
         # cannot run tests with race because we are mutating state (setting ENV variables)
         run: go test -covermode=atomic  -coverprofile=unit-coverage.out ./...
       - name: Upload codecoverage
-        uses: codecov/codecov-action@e3c560433a6cc60aec8812599b7844a7b4fa0d71 # 2.1.0
+        uses: codecov/codecov-action@81cd2dc8148241f03f5839d295e000b8f761e378 # 2.1.0
         with:
          files: ./unit-coverage.out
          verbose: true
@@ -70,7 +70,7 @@ jobs:
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
           restore-keys: |
             ${{ runner.os }}-go-
-      - uses: actions/setup-go@f6164bd8c8acb4a71fb2791a8b6c4024ff038dab #v2.1.5
+      - uses: actions/setup-go@fcdc43634adb5f7ae75a9d7a9b9361790f7293e2 #v2.1.5
         with:
           go-version: '1.17.x'
       - name: Run Go verify

.gitignore

@@ -1,2 +1,3 @@
 # Testing
 unit-coverage.out
+scorecard-action

.golangci.yml

@@ -3,13 +3,23 @@ run:
   concurrency: 6
   deadline: 5m
 issues:
-  new-from-rev: ""
   include:
     # revive `package-comments` and `exported` rules.
     - EXC0012
     - EXC0013
     - EXC0014
     - EXC0015
+  # Maximum issues count per one linter.
+  # Set to 0 to disable.
+  # Default: 50
+  max-issues-per-linter: 0
+  # Maximum count of issues with the same text.
+  # Set to 0 to disable.
+  # Default: 3
+  max-same-issues: 0
+  new-from-rev: ""
+  # Fix found issues (if it's supported by the linter).
+  fix: true
 linters:
   disable-all: true
   enable:

Dockerfile

@@ -21,11 +21,11 @@
 #           -e INPUT_REPO_TOKEN=$GITHUB_AUTH_TOKEN \
 #           -e GITHUB_REPOSITORY="ossf/scorecard" \
 #           laurentsimon/scorecard-action:latest
-FROM gcr.io/openssf/scorecard:v4.1.0@sha256:a1e9bb4a0976e800e977c986522b0e1c4e0466601642a84470ec1458b9fa6006 as base
+FROM gcr.io/openssf/scorecard:v4.2.0@sha256:86666488851413a52fa4dee05df503aa0ed8e93fbf71b1f4c96b2539bd9e4306 as base
 
 # Build our image and update the root certs.
 # TODO: use distroless.
-FROM debian:11.3-slim@sha256:f75d8a3ac10acdaa9be6052ea5f28bcfa56015ff02298831994bd3e6d66f7e57
+FROM debian:11.3-slim@sha256:fbaacd55d14bd0ae0c0441c2347217da77ad83c517054623357d1f9d07f79f5e
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
     jq ca-certificates curl
@@ -40,4 +40,4 @@ COPY policies/template.yml  /policy.yml
 # Note: the file is executable in the repo
 # and permission carry over to the image.
 COPY entrypoint.sh /entrypoint.sh
-ENTRYPOINT ["/entrypoint.sh"]
+ENTRYPOINT ["/entrypoint.sh"]

README.md

@@ -7,7 +7,7 @@ The Scorecards GitHub Action is free for all public repositories. Private reposi
 
 ________
 [Installation](#installation) 
-- [Authentication](#authentication)
+- [Authentication](#authentication-with-pat)
 - [Workflow Setup](#workflow-setup)
 
 [View Results](#view-results)
@@ -21,24 +21,38 @@ ________
 - [Workflow Example](#workflow-example)
 ________
 
+The following GitHub triggers are supported: `push`, `schedule` (default branch only).
+
+The `pull_request` and `workflow_dispatch` triggers are experimental.
+
+Running the Scorecard action on a fork repository is not supported.
+
+Private repositories need a Personal Access Token (PAT).
+
+Public repositories need a PAT to enable the [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) check. Without a PAT, Scorecards will run all checks except the Branch-Protection check.
+
+GitHub Enterprise repositories are not supported.
+
 ## Installation
-To install the Scorecards GitHub Action, you need to:
+The Scorecards Action is installed by setting up a workflow on the GitHub UI.
 
-1) Create a Personal Access Token (PAT) for authentication and save the token value as a repository secret; 
-
-    (Note: If you have already installed Scorecards on your repository from the command line, you can reuse your existing PAT for the repository secret. If you no longer have access to the PAT, though, simply create a new one.)
-
-3) Set up the workflow via the GitHub UI
+**Private repositories**: Scorecards requires authentication using a Personal Access Token (PAT). So if you install Scorecards on a private repository, you will need to follow the optional Authentication step. If you don't, Scorecards will fail to run.
+
+**Public repositories**: One Scorecards check ([Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection)) requires authentication using a Personal Access Token (PAT). If you want all Scorecards checks to run on a public repository, you will need to follow the optional Authentication step. If you don't, all checks will run except Branch-Protection.
 
-### Authentication
+**Optional Authentication**: Create a Personal Access Token (PAT) for authentication and save the token value as a repository secret. (Note: If you have already installed Scorecards on your repository from the command line, you can reuse your existing PAT for the repository secret. If you no longer have access to the PAT, though, simply create a new one.)
+
+**Required**: Set up the workflow via the GitHub UI - see [Workflow Setup](#workflow-setup)
+
+### Authentication with PAT
 1. [Create a Personal Access Token](https://github.com/settings/tokens/new?scopes=public_repo,read:org,read:repo_hook,read:discussion) with the following read permissions:
     - Note: `Read-only token for OSSF Scorecard Action - myorg/myrepo` (Note: replace `myorg/myrepo` with the names of your organization and repository so you can keep track of your tokens.)
     - Expiration: `No expiration`
     - Scopes: 
-        * `repo > public_repo`
-        * `admin:org > read:org`
-        * `admin:repo_hook > read:repo_hook`
-        * `write:discussion > read:discussion`
+        * `repo > public_repo`                  Required to read [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) settings. **Note**: for private repositories, you need scope `repo`.
+        * `admin:org > read:org`                Optional: not used in current implementation.
+        * `admin:repo_hook > read:repo_hook`    Optional: needed for the experimental [Webhook](https://github.com/ossf/scorecard/blob/main/docs/checks.md#webhooks) check.
+        * `write:discussion > read:discussion`  Optional: not used in current implementation.
 
 ![image](/images/tokenscopes.png)
 
@@ -77,23 +91,23 @@ Then click "Add More Scanning Tools."
 
 ## View Results
 
-To view a list of results from each Scorecards Action run, go to the Security tab and click "Code Scanning Alerts." Click on the individual alerts for more information, including remediation instructions. You will need to click "Show more" to expand the full remediation instructions.
+The workflow is preconfigured to run on every repository contribution. After making a code change, you can view a list of results by going to the Security tab and clicking "Code Scanning Alerts" (it can take a couple minutes for the run to complete and the results to show up). Click on the individual alerts for more information, including remediation instructions. You will need to click "Show more" to expand the full remediation instructions.
 
 ![image](/images/remediation.png)
 
 ### Verify Runs 
 The workflow is preconfigured to run on every repository contribution. 
 
-To verify that the Action is running successfully, click the repository's Actions tab to see the status of all recent workflow runs. 
+To verify that the Action is running successfully, click the repository's Actions tab to see the status of all recent workflow runs. This tab will also show the logs, which can help you troubleshoot if the run failed.
 
 ![image](/images/actionconfirm.png)
 
 ### Troubleshooting 
-If the run has failed, the most likely reason is an authentication failure. Confirm that the Personal Access Token is saved as an encrypted secret within the same repository (see [Authentication](#authentication)). 
+If the run has failed, the most likely reason is an authentication failure. If you are running Scorecards on a private repository, confirm that the Personal Access Token is saved as an encrypted secret within the same repository (see [Authentication](#authentication)). In addition, provide the `repo` scope to your PAT. (The `repo > public_repo` scope only provides access to public repositories).
 
-If you install Scorecard on a repository owned by an organization that uses [SAML SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) or if you see `403 Resource protected by organization SAML enforcement` in the logs, be sure to [enable SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) for your PAT token (see [Authentication](#authentication)).
+If you install Scorecards on a repository owned by an organization that uses [SAML SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) or if you see `403 Resource protected by organization SAML enforcement` in the logs, be sure to [enable SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) for your PAT token (see [Authentication](#authentication)).
 
-If the PAT is saved as an encrypted secret and the run is still failing, confirm that you have not made any changes to the workflow yaml file that affected the syntax. Review the [workflow example](#workflow-example) and reset to the default values if necessary.  
+If you use a PAT saved as an encrypted secret and the run is still failing, confirm that you have not made any changes to the workflow yaml file that affected the syntax. Review the [workflow example](#workflow-example) and reset to the default values if necessary.
 
 ## Manual Action Setup
 
@@ -108,7 +122,7 @@ First, [create a new file](https://docs.github.com/en/repositories/working-with-
 | ----- | -------- | ----------- |
 | `result_file` | yes | The file that contains the results. |
 | `result_format` | yes | The format in which to store the results [json \| sarif]. For GitHub's scanning dashboard, select `sarif`. |
-| `repo_token` | yes | PAT token with read-only access. Follow [these steps](#pat-token-creation) to create it. |
+| `repo_token` | yes | PAT token with read-only access. Follow [these steps](#authentication-with-pat) to create it. |
 | `publish_results` | recommended | This will allow you to display a badge on your repository to show off your hard work (release scheduled for Q2'22). See details [here](#publishing-results).|
 
 ### Publishing Results
@@ -147,6 +161,8 @@ jobs:
     permissions:
       # Needed to upload the results to code-scanning dashboard.
       security-events: write
+      # Used to receive a badge. (Upcoming feature)
+      id-token: write
       actions: read
       contents: read
 
@@ -161,9 +177,12 @@ jobs:
         with:
           results_file: results.sarif
           results_format: sarif
-          # Read-only PAT token. To create it,
-          # follow the steps in https://github.com/ossf/scorecard-action#pat-token-creation.
-          repo_token: ${{ secrets.SCORECARD_READ_TOKEN }}
+          # (Optional) Read-only PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecards on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
+          # repo_token: ${{ secrets.SCORECARD_READ_TOKEN }}
+
           # Publish the results for public repositories to enable scorecard badges. For more details, see
           # https://github.com/ossf/scorecard-action#publishing-results. 
           # For private repositories, `publish_results` will automatically be set to `false`, regardless 

RELEASE.md

@@ -0,0 +1,115 @@
+# Releasing the scorecard GitHub Action
+
+This is a draft document to describe the release process for the scorecard
+GitHub Action.
+
+(If there are improvements you'd like to see, please comment on the
+[tracking issue](https://github.com/ossf/scorecard-action/issues/33) or issue a
+pull request to discuss.)
+
+- [Tracking](#tracking)
+- [Preparing the release](#preparing-the-release)
+  - [Update the scorecard version](#update-the-scorecard-version)
+- [Drafting release notes](#drafting-release-notes)
+- [Release](#release)
+  - [Create a tag](#create-a-tag)
+  - [Create a GitHub release](#create-a-github-release)
+- [Update the starter workflow](#update-the-starter-workflow)
+- [Announce](#announce)
+
+## Tracking
+
+As the first task, a Release Manager should open a tracking issue for the
+release.
+
+We don't currently have a template for releasing, but the following
+[issue](https://github.com/ossf/scorecard-action/issues/97) is a good example
+to draw inspiration from.
+
+We're not striving for perfection with the template, but the tracking issue
+will serve as a reference point to aggregate feedback, so try your best to be
+as descriptive as possible.
+
+## Preparing the release
+
+This section covers changes that need to be issued as a pull request and should
+be merged before releasing the scorecard GitHub Action.
+
+### Update the scorecard version
+
+_NOTE: As the scorecard GitHub Action is based on scorecard, you may want to publish a new release of scorecard to ensure the next release of the GitHub Action has the most up-to-date functionality. This is not strictly required. The only requirement is that we use a stable scorecard version which is at or above the current version used for this action._
+
+For the rest of document, let `CH1` be the hash of the scorecard image you
+intend to use for this release.
+
+See [here](https://github.com/orgs/ossf/packages?repo_name=scorecard) for
+scorecard images.
+
+(We'll use `0bc9576b3efbda7b38febbf0a1e1b9546894f9650aaead9ccb5edc7dade86552`
+as `CH1` in any examples below.)
+
+Now that you have `CH1`, update the digest in the [Dockerfile](Dockerfile) to use `CH1`.
+
+Example:
+
+```Dockerfile
+FROM gcr.io/openssf/scorecard:v100.0.0@sha256:0bc9576b3efbda7b38febbf0a1e1b9546894f9650aaead9ccb5edc7dade86552 as base
+```
+
+Create a pull request with this change.
+
+Once the PR is merged, note the GitHub commit hash.
+We'll refer to this as `GH2` below.
+
+## Drafting release notes
+
+<!-- TODO(release): Provide details -->
+
+## Release
+
+### Create a tag
+
+Locally, create a signed tag based on `GH2`:
+
+```console
+git remote update
+git checkout `GH2`
+git tag -s -m "v100.0.0" v100.0.0
+git push <upstream> --tags
+```
+
+### Create a GitHub release
+
+Create a
+[GitHub release](https://github.com/ossf/scorecard-action/releases/new) using
+the tag you've just created.
+
+Release title: `<tag>`
+
+The release notes will be the notes you drafted in the previous step.
+
+Ensure the following fields are up to date:
+
+- Security contact email
+- Primary Category
+- Another Category — optional
+
+Click `Publish release`.
+
+## Update the starter workflow
+
+1. Open a pull request in the
+[starter workflows repo](https://github.com/actions/starter-workflows/tree/main/code-scanning/scorecards.yml)
+to update the action's digest to `GH2`.
+
+1. Update our documentation's example workflow to use `GH2`.
+
+1. Verify on
+   [GitHub Marketplace](https://github.com/marketplace/actions/ossf-scorecard-action)
+   that the workflow example contains `GH2`.
+
+   _NOTE: GitHub Marketplace uses the default branch as reference documentation_
+
+## Announce
+
+<!-- TODO(release): Provide details -->

codeql.js

@@ -1 +1,19 @@
+/**
+ * Copyright 2022 OpenSSF Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 console.log("codeql")

entrypoint.sh

@@ -47,11 +47,18 @@ export ENABLED_CHECKS=
 #
 # Boolean inputs are strings https://github.com/actions/runner/issues/1483.
 # ===============================================================================
-curl -s -H "Authorization: Bearer $GITHUB_AUTH_TOKEN" https://api.github.com/repos/$GITHUB_REPOSITORY > repo_info.json
+status_code=$(curl -s -H "Authorization: Bearer $GITHUB_AUTH_TOKEN" https://api.github.com/repos/"$GITHUB_REPOSITORY" -o repo_info.json -w '%{http_code}')
+if [[ $status_code -lt 200 ]] || [[ $status_code -ge 300 ]]; then
+    error_msg=$(jq -r .message repo_info.json 2>/dev/null || echo 'unknown error')
+    echo "Failed to get repository information from GitHub, response $status_code: $error_msg"
+    echo "$(<repo_info.json)"
+    rm repo_info.json
+    exit 1;
+fi
+
 export SCORECARD_PRIVATE_REPOSITORY="$(cat repo_info.json | jq -r '.private')"
 export SCORECARD_DEFAULT_BRANCH="refs/heads/$(cat repo_info.json | jq -r '.default_branch')"
 export SCORECARD_IS_FORK="$(cat repo_info.json | jq -r '.fork')"
-rm repo_info.json
 
 # If the repository is private, never publish the results.
 if [[ "$SCORECARD_PRIVATE_REPOSITORY" == "true" ]]; then
@@ -73,6 +80,8 @@ echo "Publication enabled: $SCORECARD_PUBLISH_RESULTS"
 echo "Format: $SCORECARD_RESULTS_FORMAT"
 echo "Policy file: $SCORECARD_POLICY_FILE"
 echo "Default branch: $SCORECARD_DEFAULT_BRANCH"
+echo "$(<repo_info.json)"
+rm repo_info.json
 
 if [[ -z "$GITHUB_AUTH_TOKEN" ]]; then
     echo "The 'repo_token' variable is empty."