diff --git a/.cz.yaml b/.cz.yaml index 4851f07..ebe52e9 100644 --- a/.cz.yaml +++ b/.cz.yaml @@ -109,3 +109,5 @@ commitizen: version: 0.22.2 version_files: - internal/cli/app.go:Version + - gitlab/templates/sheriff.gitlab-ci.yml:sheriff:v + - README.md:tags/v diff --git a/README.md b/README.md index b6b646c..13b8fe7 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,8 @@ Sheriff is a tool to scan repositories and generate security reports. - [Source code hosting services](#source-code-hosting-services) - [Messaging services](#messaging-services) - [Scanners](#scanners) +- [Usage in CI](#usage-in-ci) + - [In Gitlab](#in-gitlab) - [Contributors ✨](#contributors-) ## Quick Usage @@ -239,6 +241,34 @@ Sets the token to be used when reporting the security report on slack - [x] [OSV-Scanner](https://github.com/google/osv-scanner) - [ ] [Trivy](https://github.com/aquasecurity/trivy) +## Usage in CI + +Sheriff was designed so it could be run as part of a CI pipeline. + +### In Gitlab + +To run sheriff on Gitlab, we suggest the following set-up: +1. Create a repostory which will contain your CI runner, you can call it `sheriff-runner` for example +2. Create a CI file in this repository which extends from our template + ```yaml + include: + - remote: 'https://raw.githubusercontent.com/elementsinteractive/sheriff/refs/tags/v0.22.2/gitlab/templates/sheriff.gitlab-ci.yml' + + sheriff: + extends: .sheriff + ``` +3. Go to **Build** -> **Pipeline schedules** -> **New schedule** + a. Add a name & a preferred cron interval. We prefer a weekly scan such as `0 7 * * 1` (every Monday at 7am) + b. Add a **Variable** Variable named `SHERIFF_CLI_ARGS` which extra CLI arguments you wish to add (see CLI configuration section) + c. Add a **File** Variable named `SHERIFF_CONFIG` containing your sheriff configuration (see file configuration section) +4. Go to **Settings** -> **CI/CD** -> **Variables** + a. If scanning gitlab projects, add your gitlab token in **GITLAB_TOKEN** with *Protected*, *Masked*, *Hidden* + b. If publishing reports to slack, add your slack token in **SLACK_TOKEN** with *Protected*, *Masked* +5. Test your pipeline by going to **Build** -> **Pipeline schedules** & clicking the play button on your pipline +5. Enjoy! Your pipeline should now run & scan your projects on a weekly basis 😀 + +We have a gitlab template set up for convenience, which runs sheriff with a set of configurable options. + ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): diff --git a/gitlab/templates/sheriff.gitlab-ci.yml b/gitlab/templates/sheriff.gitlab-ci.yml new file mode 100644 index 0000000..340e32a --- /dev/null +++ b/gitlab/templates/sheriff.gitlab-ci.yml @@ -0,0 +1,28 @@ +variables: + GITLAB_TOKEN: + description: "GitLab token for API access" + SLACK_TOKEN: + description: "Slack token for notifications" + SHERIFF_CONFIG: + description: "Sheriff TOML configuration file contents. Will be available to sheriff as a file `sheriff.toml`" + SHERIFF_CLI_ARGS: + description: "Add CLI arguments to pass to the sheriff patrol command" + +.sheriff: + stage: deploy + image: + name: elementsinteractive/sheriff:v0.22.2 + entrypoint: [""] + resource_group: production + rules: + - if: $CI_PIPELINE_SOURCE == "schedule" + - if: $CI_PIPELINE_SOURCE == "web" + script: + - sheriff patrol + --gitlab-token $GITLAB_TOKEN + --slack-token $SLACK_TOKEN + --config $SHERIFF_CONFIG + $SHERIFF_CLI_ARGS + +sheriff: + extends: .sheriff