Sheriff is a tool to scan repositories and generate security reports.

• Quick Usage
• How it works
  • Issue in the affected repository
  • Report message
  • Specific repository message
• Installation
  • Docker
  • Manual installation
• Configuration
  • CLI flags
  • Environment variables
  • Configuration file
  • Configuration options
    • Miscellaneous
      • config
      • verbose
    • Scanning
      • targets
    • Reporting
      • report to issue
      • report to email (TODO #12)
      • report to slack channels
      • enable project report to
      • silent
    • Tokens
      • gitlab token
      • slack token
• Supported platforms
  • Source code hosting services
  • Messaging services
  • Scanners
• Usage in CI
  • In Gitlab
• Contributors ✨

sheriff patrol --target gitlab://your-namespace-or-group --report-to-issue

Sheriff analyzes repositories in source code repository hosting services (such as GitLab) looking for vulnerabilities in the dependencies of the scanned repositories. Sheriff uses one or several third-party scanners to detect these vulnerabilities, and aggregates them into its reports. See a list of supported platforms and scanners in the section below.

Sheriff is best used for analyzing vulnerabilities in bulk, regularly scanning groups of repositories to provide an overview of which vulnerabilities affect them. For that, Sheriff provides different types of reports, and it can publish them to different platforms such as GitLab (see supported platforms section).

Sheriff will keep an open issue in each one of the analyzed repositories, providing a detailed report of which vulnerabilities have been found by its scanners.

Sheriff will post a message to a messaging service with an overview of the analyzed repositories and the vulerabilities detected. This message is intended to provide a generic overview to those in charge of security to oversee the state of a given group of repositories.

Project teams can also be informed regularly by Sheriff (if they want to) by configuring a channel to which Sheriff should report its findings of a given repository. The message generated by Sheriff will be slightly different, and will contain only information relevant for the repository maintainers.

The easiest way to run Sheriff is through docker:

docker pull elementsinteractive/sheriff
docker run elementsinteractive/sheriff --help

You can install Sheriff yourself by installing its dependencies, and then either downloading the binary from the GitHub Releases page or building Sheriff from source.

brew install osv-scanner
git clone git@github.com:elementsinteractive/sheriff.git
cd sheriff
go install .

Sheriff can be configured in a few different ways:

The most complete way is through CLI flags. See sheriff patrol --help for the full list of available options.

For specific sensitive configuration keys such as API tokens, Sheriff can read them from environmental variables. Only the Tokens section of configuration parameters are supported for this (see sheriff patrol --help for the full list).

This is the case for GITLAB_TOKEN & SLACK_TOKEN for example.

Sheriff also supports configuration through a TOML config file. Only the Reporting and Scanning sections of configuration parameters are supported for this (see sheriff patrol --help for the full list).

In this case you may choose to create a config file such as the following:

targets = ["namespace/group", "namespace/group/cool-repo"]
[report.to]
slack-channel = "sheriff-report-test"
issue = true

And if you wish to specify a different file, you can do so with sheriff patrol --config your-config-file.toml.

Sets the path of your sheriff configuration file

Sets the log level to verbose

Sets the list of groups and projects to be scanned. The expected format of a target is platform://path/to/your/group-or-project

For example: --target gitlab://namespace/group --target github://organization/project

Enables reporting to an issue on the project's platform

Sets the list of email to which a full scan report should be sent

Enable project-level configuration report-to to allow projects to control where their individual reports are sent

Disable printing the report in the bash output

Sets the token to be used when fetching projects from gitlab

Sets the token to be used when reporting the security report on slack

• GitLab
• GitHub (#9)

• Slack
• Email (#12)

• OSV-Scanner
• Trivy

Sheriff was designed so it could be run as part of a CI pipeline.

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

   include:
     - remote: 'https://raw.githubusercontent.com/elementsinteractive/sheriff/refs/tags/v0.23.1/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
6. 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.

Thanks goes to these wonderful people (emoji key):

Sacha Brouté 💻 🎨 🤔 🚧

Sergio Castillo 💻 🤔 🚧

Jakub Bożanowski 🤔 🎨

This project follows the all-contributors specification. Contributions of any kind welcome!