From c60b66bbc8b85286416d6ab9ae9324a095e66c94 Mon Sep 17 00:00:00 2001 From: olivekl <83081275+olivekl@users.noreply.github.com> Date: Fri, 14 Jan 2022 15:46:30 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20Olivekl=20v4=20doc=20updates=20(?= =?UTF-8?q?#1481)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Create scorecards-analysis.yml * Update README.md Move Public Data section Add placeholders for new installation organization, TODOs for public data section * Update README.md Remove outdated public data scoring system paragraph * Update README.md Add explanation of Scorecard Action install option and link out * Update README.md Add sentence introducing CLI installation section; move all heading down a level for that section * Update README.md Fix typo * Update README.md Remove comma * Delete scorecards-analysis.yml file Co-authored-by: Azeem Shaikh --- README.md | 122 +++++++++++++++++++++++++++--------------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 63767abb102..e43255389ea 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,16 @@ - [What Is Scorecards?](#what-is-scorecards) - [Prominent Scorecards Users](#prominent-scorecards-users) +- [Scorecards' Public Data](#public-data) ## Using Scorecards - -- [Prerequisites](#prerequisites) -- [Installation](#installation) -- [Authentication](#authentication) -- [Basic Usage](#basic-usage) -- [Report Problems](#report-problems) -- [Scorecards' Public Data](#public-data) +- [Scorecards GitHub Action](#scorecards-github-action) +- [Scorecards Command Line Interface](#scorecards-command-line-interface) + - [Prerequisites](#prerequisites) + - [Installation](#installation) + - [Authentication](#authentication) + - [Basic Usage](#basic-usage) + - [Report Problems](#report-problems) ## Checks @@ -60,17 +61,55 @@ Scorecards has been run on thousands of projects to monitor and track security m - [deps.dev](https://deps.dev) - [metrics.openssf.org](https://metrics.openssf.org) +### Public Data + +We run a weekly Scorecards scan of the 1 million most critical open source projects judged by their direct dependencies and publish the results in a +[BigQuery public dataset](https://cloud.google.com/bigquery/public-data). + +This data is available in the public BigQuery dataset +`openssf:scorecardcron.scorecard-v2`. The latest results are available in the +BigQuery view `openssf:scorecardcron.scorecard-v2_latest`. + +You can extract the latest results to Google Cloud storage in JSON format using +the [`bq`](https://cloud.google.com/bigquery/docs/bq-command-line-tool) tool: + +``` +# Get the latest PARTITION_ID +bq query --nouse_legacy_sql 'SELECT partition_id FROM +openssf.scorecardcron.INFORMATION_SCHEMA.PARTITIONS WHERE table_name="scorecard-v2" +AND partition_id!="__NULL__" ORDER BY partition_id DESC +LIMIT 1' + +# Extract to GCS +bq extract --destination_format=NEWLINE_DELIMITED_JSON +'openssf:scorecardcron.scorecard-v2$' gs://bucket-name/filename-*.json + +``` + +The list of projects that are checked is available in the +[`cron/data/projects.csv`](https://github.com/ossf/scorecard/blob/main/cron/data/projects.csv) +file in this repository. If you would like us to track more, please feel free to +send a Pull Request with others. Currently, this list is derived from **projects hosted on GitHub +ONLY**. We do plan to expand them in near future to account for projects hosted +on other source control systems. + ## Using Scorecards +### Scorecards GitHub Action + +The easiest way to use Scorecards on GitHub projects you own is with the [Scorecards GitHub Action](https://github.com/ossf/scorecard-action). The Action runs on any repository change and issues alerts that maintainers can view in the repository’s Security tab. For more information, see the Scorecards GitHub Action [installation instructions](https://github.com/ossf/scorecard-action#installation). -### Prerequisites +### Scorecards Command Line Interface +To run a Scorecards scan on projects you do not own, use the command line interface installation option. + +#### Prerequisites Platforms: Currently, Scorecards supports OSX and Linux platforms. If you are using a Windows OS you may experience issues. Contributions towards supporting Windows are welcome. Language: You must have GoLang installed to run Scorecards (https://golang.org/doc/install) -### Installation +#### Installation -#### Standalone +##### Standalone To install Scorecards as a standalone: @@ -78,7 +117,7 @@ To install Scorecards as a standalone: 2. Extract the binary file 3. Add the binary to your `GOPATH/bin` directory (use `go env GOPATH` to identify your directory if necessary) -#### Using Homebrew +##### Using Homebrew You can use [Homebrew](https://brew.sh/) (on macOS or Linux) to install Scorecards. @@ -86,14 +125,14 @@ You can use [Homebrew](https://brew.sh/) (on macOS or Linux) to install Scorecar brew install scorecard ``` -### Using Linux package managers +#### Using Linux package managers | Package Manager | Linux Distribution | Command | |------------------------------------------------------------|--------------------|--------------------------------------------| | Nix | NixOS | `nix-env -iA nixpkgs.scorecard` | | [AUR helper](https://wiki.archlinux.org/title/AUR_helpers) | Arch Linux | Use your AUR helper to install `scorecard` | -### Authentication +#### Authentication GitHub imposes [api rate limits](https://developer.github.com/v3/#rate-limiting) on unauthenticated requests. To avoid these limits, you must authenticate your requests before running Scorecard. There are two ways to authenticate your requests: either create a GitHub personal access token, or create a GitHub App Installation. @@ -127,8 +166,8 @@ GITHUB_APP_ID= These variables can be obtained from the GitHub [developer settings](https://github.com/settings/apps) page. -### Basic Usage -#### Docker +#### Basic Usage +##### Docker `scorecard` is available as a Docker container: @@ -144,7 +183,7 @@ To use a specific scorecards version (e.g., v3.2.1), run: docker run -e GITHUB_AUTH_TOKEN=token gcr.io/openssf/scorecard:v3.2.1 --show-details --repo=https://github.com/ossf/scorecard ``` -#### Using repository URL +##### Using repository URL Scorecards can run using just one argument, the URL of the target repo: @@ -234,7 +273,7 @@ Check scores: | 10 / 10 | Vulnerabilities | no vulnerabilities detected | github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities | |---------|------------------------|--------------------------------|---------------------------------------------------------------------------| ``` -#### Scoring +##### Scoring Each individual check returns a score of 0 to 10, with 10 representing the best possible score. Scorecards also produces an aggregate score, which is a weight-based average of the individual checks weighted by risk. * “Critical” risk checks are weighted at 10 @@ -244,7 +283,7 @@ Each individual check returns a score of 0 to 10, with 10 representing the best See the [list of current Scorecards checks](#scorecard-checks) for each check's risk level. -#### Showing Detailed Results +##### Showing Detailed Results For more details about why a check fails, use the `--show-details` option: ``` @@ -278,71 +317,33 @@ RESULTS |---------|------------------------|--------------------------------|--------------------------------|---------------------------------------------------------------------------| ``` -#### Using a Package manager +##### Using a Package manager For projects in the `--npm`, `--pypi`, or `--rubygems` ecosystems, you have the option to run Scorecards using a package manager. Provide the package name to run the checks on the corresponding GitHub source code. For example, `--npm=angular`. -#### Running specific checks +##### Running specific checks To run only specific check(s), add the `--checks` argument with a list of check names. For example, `--checks=CI-Tests,Code-Review`. -#### Formatting Results +##### Formatting Results There are three formats currently: `default`, `json`, and `csv`. Others may be added in the future. These may be specified with the `--format` flag. For example, `--format=json`. -### Report Problems +#### Report Problems If you have what looks like a bug, please use the [Github issue tracking system.](https://github.com/ossf/scorecard/issues) Before you file an issue, please search existing issues to see if your issue is already covered. -### Public Data - -If you're interested in seeing a list of projects with their Scorecard -check results, we publish these results in a -[BigQuery public dataset](https://cloud.google.com/bigquery/public-data). - -This data is available in the public BigQuery dataset -`openssf:scorecardcron.scorecard-v2`. The latest results are available in the -BigQuery view `openssf:scorecardcron.scorecard-v2_latest`. - -You can extract the latest results to Google Cloud storage in JSON format using -the [`bq`](https://cloud.google.com/bigquery/docs/bq-command-line-tool) tool: - -``` -# Get the latest PARTITION_ID -bq query --nouse_legacy_sql 'SELECT partition_id FROM -openssf.scorecardcron.INFORMATION_SCHEMA.PARTITIONS WHERE table_name="scorecard-v2" -AND partition_id!="__NULL__" ORDER BY partition_id DESC -LIMIT 1' - -# Extract to GCS -bq extract --destination_format=NEWLINE_DELIMITED_JSON -'openssf:scorecardcron.scorecard-v2$' gs://bucket-name/filename-*.json - -``` - -The list of projects that are checked is available in the -[`cron/data/projects.csv`](https://github.com/ossf/scorecard/blob/main/cron/data/projects.csv) -file in this repository. If you would like us to track more, please feel free to -send a Pull Request with others. Currently, this list is derived from **projects hosted on GitHub -ONLY**. We do plan to expand them in near future to account for projects hosted -on other source control systems. - -**NOTE**: The public dataset uses a Pass/Fail scoring system with a confidence score -between **0 and 10**. A confidence of 0 indicates that the check was unable to -achieve any real signal, and that the result should be ignored. A confidence of 10 -indicates the check was completely sure of the result. - ## Checks ### Scorecard Checks @@ -373,7 +374,6 @@ Name | Description | Risk Level To see detailed information about each check, its scoring criteria, and remediation steps, check out the [checks documentation page](docs/checks.md). - ## Contribute ### Code of Conduct Before contributing, please follow our [Code of Conduct](CODE_OF_CONDUCT.md).