📖 Olivekl v4 doc updates (#1481)

olivekl · azeemshaikh38 · web-flow · commit c60b66bbc8b8 · 2022-01-14T20:46:30.000Z
* 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 &lt;azeemshaikh38@gmail.com&gt;
diff --git 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,40 +61,78 @@ 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$<partition_id>' 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:
 
 1. Visit our latest [release page](https://github.com/ossf/scorecard/releases/latest) and download the correct binary for your operating system
 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.
 
 ```sh
 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=<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$<partition_id>' 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).
