2021-01-04 20:09:21 +03:00
|
|
|
# Contributing to Security Scorecards
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
Thank you for contributing your time and expertise to the Security Scorecards
|
|
|
|
project. This document describes the contribution guidelines for the project.
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
**Note:** Before you start contributing, you must read and abide by our
|
|
|
|
**[Code of Conduct](./CODE_OF_CONDUCT.md)**.
|
2021-03-15 19:16:33 +03:00
|
|
|
|
|
|
|
<!-- vim-markdown-toc GFM -->
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
* [Contributing code](#contributing-code)
|
|
|
|
* [Getting started](#getting-started)
|
|
|
|
* [Environment Setup](#environment-setup)
|
|
|
|
* [Contributing steps](#contributing-steps)
|
|
|
|
* [How to build scorecard locally](#how-to-build-scorecard-locally)
|
|
|
|
* [PR Process](#pr-process)
|
|
|
|
* [What to do before submitting a pull request](#what-to-do-before-submitting-a-pull-request)
|
|
|
|
* [Permission for GitHub personal access tokens](#permission-for-github-personal-access-tokens)
|
|
|
|
* [Where the CI Tests are configured](#where-the-ci-tests-are-configured)
|
|
|
|
* [dailyscore-cronjob](#dailyscore-cronjob)
|
|
|
|
* [Deploying the cron job](#deploying-the-cron-job)
|
|
|
|
* [How do I add additional GitHub repositories to be scanned by scorecard
|
|
|
|
dailyscore?](#how-do-i-add-additional-github-repositories-to-be-scanned-by-scorecard-dailyscore)
|
|
|
|
* [Adding New Checks](#adding-new-checks)
|
2021-03-15 19:16:33 +03:00
|
|
|
|
|
|
|
<!-- vim-markdown-toc -->
|
|
|
|
|
2020-10-09 17:47:59 +03:00
|
|
|
## Contributing code
|
|
|
|
|
|
|
|
### Getting started
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. Create [a GitHub account](https://github.com/join)
|
|
|
|
1. Create a
|
|
|
|
[personal access token](https://docs.github.com/en/free-pro-team@latest/developers/apps/about-apps#personal-access-tokens)
|
|
|
|
1. Set up your [development environment](#environment-setup)
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2020-10-26 23:22:13 +03:00
|
|
|
### Environment Setup
|
2020-10-09 17:47:59 +03:00
|
|
|
|
|
|
|
You must install these tools:
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. [`git`](https://help.github.com/articles/set-up-git/): For source control
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. [`go`](https://golang.org/doc/install): You need go version
|
|
|
|
[v1.16](https://golang.org/dl/) or higher.
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. [`docker`](https://docs.docker.com/engine/install/): `v18.9` or higher.
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-01-04 20:09:21 +03:00
|
|
|
## Contributing steps
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. Submit an issue describing your proposed change to the repo in question.
|
|
|
|
1. The repo owners will respond to your issue promptly.
|
|
|
|
1. Fork the desired repo, develop and test your code changes.
|
|
|
|
1. Submit a pull request.
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-01-04 20:09:21 +03:00
|
|
|
## How to build scorecard locally
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
Note that, by building the scorecard from the source code we are allowed to test
|
|
|
|
the changes made locally.
|
2020-10-09 17:47:59 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. Run the following command to clone your fork of the project locally
|
2020-10-09 17:47:59 +03:00
|
|
|
|
|
|
|
```shell
|
2021-01-04 20:09:21 +03:00
|
|
|
git clone git@github.com:<user>/scorecard.git $GOPATH/src/github.com/<user>/scorecard.git
|
2020-10-09 17:47:59 +03:00
|
|
|
```
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. Ensure you activate module support before continue (`$ export
|
|
|
|
GO111MODULE=on`)
|
|
|
|
1. Run the command `make build` to build the source code
|
2021-01-04 20:09:21 +03:00
|
|
|
|
2021-03-21 18:02:19 +03:00
|
|
|
## PR Process
|
|
|
|
|
|
|
|
Every PR should be annotated with an icon indicating whether it's a:
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
- Breaking change: :warning: (`:warning:`)
|
|
|
|
- Non-breaking feature: :sparkles: (`:sparkles:`)
|
|
|
|
- Patch fix: :bug: (`:bug:`)
|
|
|
|
- Docs: :book: (`:book:`)
|
|
|
|
- Infra/Tests/Other: :seedling: (`:seedling:`)
|
|
|
|
- No release note: :ghost: (`:ghost:`)
|
2021-03-21 18:02:19 +03:00
|
|
|
|
|
|
|
Use :ghost: (no release note) only for the PRs that change or revert unreleased
|
|
|
|
changes, which don't deserve a release note. Please don't abuse it.
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
You can also use the equivalent emoji directly, since GitHub doesn't render the
|
|
|
|
`:xyz:` aliases in PR titles.
|
2021-03-21 18:02:19 +03:00
|
|
|
|
|
|
|
Individual commits should not be tagged separately, but will generally be
|
2021-05-07 15:08:33 +03:00
|
|
|
assumed to match the PR. For instance, if you have a bugfix in with a breaking
|
|
|
|
change, it's generally encouraged to submit the bugfix separately, but if you
|
|
|
|
must put them in one PR, you should mark the whole PR as breaking.
|
2021-03-21 18:02:19 +03:00
|
|
|
|
2021-01-04 20:09:21 +03:00
|
|
|
## What to do before submitting a pull request
|
|
|
|
|
|
|
|
Following the targets that can be used to test your changes locally.
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
| Command | Description | Is called in the CI? |
|
|
|
|
| -------- | -------------------------------------------------- | -------------------- |
|
|
|
|
| make all | Runs go test,golangci lint checks, fmt, go mod tidy| yes |
|
|
|
|
| make e2e | Runs e2e tests | yes |
|
2021-01-04 20:09:21 +03:00
|
|
|
|
2021-01-08 22:09:06 +03:00
|
|
|
## Permission for GitHub personal access tokens
|
|
|
|
|
|
|
|
The personal access token need the following scopes:
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
- `repo:status` - Access commit status
|
|
|
|
- `repo_deployment` - Access deployment status
|
|
|
|
- `public_repo` - Access public repositories
|
2021-01-08 22:09:06 +03:00
|
|
|
|
2021-01-04 20:09:21 +03:00
|
|
|
## Where the CI Tests are configured
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
1. See the [action files](.github/workflows) to check its tests, and the
|
|
|
|
scripts used on it.
|
2021-01-04 20:09:21 +03:00
|
|
|
|
2021-03-15 19:16:33 +03:00
|
|
|
## dailyscore-cronjob
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
scorecard scans https://github.com/ossf/scorecard/blob/main/cron/projects.txt
|
|
|
|
repositories in GCP k8s and publishes the results in GCS bucket
|
|
|
|
`ossf-scorecards`.
|
2021-03-15 19:16:33 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
The `cron` definition ./scorecard/cron/cron.sh and the `k8s` for the `cron` is
|
|
|
|
in ./scorecard/cron/k8s/cron.yaml
|
2021-03-15 19:16:33 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
The logs for the cron are available at
|
|
|
|
https://console.cloud.google.com/kubernetes/cronjob/us-central1-c/openssf/default/daily-score/logs?project=openssf
|
2021-03-15 19:16:33 +03:00
|
|
|
|
|
|
|
### Deploying the cron job
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
The cronjob can be deployed into k8s by running `kubectl apply -f
|
|
|
|
./scorecard/cron/k8s/cron.yaml`. This will deploy a k8s cron job.
|
2021-03-15 19:16:33 +03:00
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
Any updates to the ./scorecard/cron/cron.sh will be deployed by the docker
|
|
|
|
container ./scorecard/Dockerfile.gsutil
|
2021-03-15 19:16:33 +03:00
|
|
|
|
|
|
|
## How do I add additional GitHub repositories to be scanned by scorecard dailyscore?
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
Scorecard maintains the list of repositories in a file
|
|
|
|
https://github.com/ossf/scorecard/blob/main/cron/projects.txt
|
2021-03-15 19:16:33 +03:00
|
|
|
|
|
|
|
Submit a PR for this file and scorecard would start scanning in subsequent runs.
|
|
|
|
|
2020-10-09 17:47:59 +03:00
|
|
|
## Adding New Checks
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
Each check is currently just a function of type `CheckFn`. The signature is:
|
2020-10-09 17:47:59 +03:00
|
|
|
|
|
|
|
```golang
|
2021-04-19 22:18:34 +03:00
|
|
|
type CheckFn func(*c.Checker) CheckResult
|
2020-10-09 17:47:59 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
Checks are registered in an init function:
|
|
|
|
|
|
|
|
```golang
|
2021-05-07 15:08:33 +03:00
|
|
|
AllChecks = append(AllChecks, NamedCheck{
|
|
|
|
Name: "Code-Review",
|
|
|
|
Fn: DoesCodeReview,
|
|
|
|
})
|
2020-10-09 17:47:59 +03:00
|
|
|
```
|
|
|
|
|
2021-05-07 15:08:33 +03:00
|
|
|
Currently only one set of checks can be run. In the future, we'll allow
|
|
|
|
declaring multiple suites and configuring which checks get run.
|