diff --git a/.all-contributorsrc b/.all-contributorsrc new file mode 100644 index 0000000..63c1e2a --- /dev/null +++ b/.all-contributorsrc @@ -0,0 +1,49 @@ +{ + "projectName": "sheriff", + "projectOwner": "elementsinteractive", + "repoType": "github", + "repoHost": "https://github.com", + "files": [ + "README.md" + ], + "imageSize": 50, + "commit": true, + "commitConvention": "angular", + "contributors": [ + { + "login": "sacha-c", + "name": "Sacha Brouté", + "avatar_url": "https://avatars.githubusercontent.com/u/3247529?v=4", + "profile": "https://github.com/sacha-c", + "contributions": [ + "code", + "design", + "ideas", + "maintenance" + ] + }, + { + "login": "scastlara", + "name": "Sergio Castillo", + "avatar_url": "https://avatars.githubusercontent.com/u/7606872?v=4", + "profile": "https://github.com/scastlara", + "contributions": [ + "code", + "ideas", + "maintenance" + ] + }, + { + "login": "jbozanowski", + "name": "Jakub Bożanowski", + "avatar_url": "https://avatars.githubusercontent.com/u/114900?v=4", + "profile": "https://github.com/jbozanowski", + "contributions": [ + "ideas", + "design" + ] + } + ], + "contributorsPerLine": 7, + "linkToUsage": false +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..9263e94 --- /dev/null +++ b/README.md @@ -0,0 +1,160 @@ +

+ sheriff-logo +

+ + +# Sheriff + +Sheriff is a tool to scan repositories and generate security reports. + +- [Quick Usage](#quick-usage) +- [How it works](#how-it-works) + - [Issue in the affected repository](#issue-in-the-affected-repository) + - [Report message](#report-message) + - [Specific repository message](#specific-repository-message) +- [Installation](#installation) + - [Docker](#docker) + - [Manual installation](#manual-installation) +- [Configuration](#configuration) + - [CLI flags](#cli-flags) + - [Environment variables](#environment-variables) + - [Configuration file](#configuration-file) +- [Supported platforms](#supported-platforms) + - [Source code hosting services](#source-code-hosting-services) + - [Messaging services](#messaging-services) + - [Scanners](#scanners) +- [Contributors ✨](#contributors-) + +## Quick Usage + +```sh +sheriff patrol --gitlab-groups your-namespace-or-group --report-gitlab-issue +``` + +## How it works + +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](#supported-platforms). + +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: gitlab, ?. + +### Issue in the affected repository + +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. + +issue-report + + +### Report message + +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. + +msg-report + + +### Specific repository message + +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. + +repo-report + + +## Installation + +### Docker + +The easiest way to run Sheriff is through docker: + +```sh +docker pull elementsinteractive/sheriff +docker run elementsinteractive/sheriff --help +``` + +### Manual installation + +> [!NOTE] +> If you install Sheriff manually, you will need to ensure that all the scanners used by it are available in your system + +You can install Sheriff yourself by installing its dependencies, and then either downloading the binary from the [GitHub Releases page](https://github.com/elementsinteractive/sheriff/releases) or building Sheriff from source. + +```sh +brew install osv-scanner +git clone git@github.com:elementsinteractive/sheriff.git +cd sheriff +go install . +``` + +## Configuration + +Sheriff can be configured in a few different ways: + +### CLI flags + +The most complete way is through CLI flags. See `sheriff patrol --help` for the full list of available options. + +### Environment variables + +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. + +### Configuration file + +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: + +```toml +gitlab-groups = ["namespace/group", "namespace/group/cool-repo"] +gitlab-projects = ["namespace/group/cool-repo"] +report-slack-channel = "sheriff-report-test" +report-gitlab-issue = true +``` + +And if you wish to specify a different file, you can do so with `sheriff patrol --config your-config-file.toml`. + +> [!NOTE] +> When using several type of configuration at once there is an order of preference: **cli flags** > **env vars** > **config file** + +## Supported platforms + +### Source code hosting services + +- [x] [GitLab](https://gitlab.com/dashboard/merge_requests?assignee_username=sergio.lara1) +- [ ] [GitHub](https://github.com) ([#9](https://github.com/elementsinteractive/sheriff/issues/9)) + +### Messaging services + +- [x] [Slack](http://slack.com) +- [ ] Email ([#12](https://github.com/elementsinteractive/sheriff/issues/12)) + +### Scanners + +- [x] [OSV-Scanner](https://github.com/google/osv-scanner) +- [ ] [Trivy](https://github.com/aquasecurity/trivy) + +## Contributors ✨ + +Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): + + + + + + + + + + + + +
Sacha Brouté
Sacha Brouté
💻 🎨 🤔 🚧		Sergio Castillo
Sergio Castillo
💻 🤔 🚧		Jakub Bożanowski
Jakub Bożanowski
🤔 🎨
+ + + + + + +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! \ No newline at end of file diff --git a/assets/issue-report.png b/assets/issue-report.png new file mode 100644 index 0000000..85110d7 Binary files /dev/null and b/assets/issue-report.png differ diff --git a/assets/report-msg.png b/assets/report-msg.png new file mode 100644 index 0000000..6c5fafa Binary files /dev/null and b/assets/report-msg.png differ diff --git a/assets/report-repo.png b/assets/report-repo.png new file mode 100644 index 0000000..7001166 Binary files /dev/null and b/assets/report-repo.png differ diff --git a/assets/sheriff.png b/assets/sheriff.png new file mode 100644 index 0000000..a0d586c Binary files /dev/null and b/assets/sheriff.png differ