Configure and use Sorts on your own

CLI structure

Sorts command-line interface is based on the following structure

sorts [OPTIONS] REPOSITORY_PATH

The options available in the interface allow you to use Sorts for analyzing repositories or commits and customize the type of output you want.

Repo mode

Using the --mode flag and typing repo you can access the Repo mode where you can analyze a single repository and receive a file in your selected format describing the vulnerability probability of all your files.

Example:

m gitlab:fluidattacks/universe@trunk /sorts --mode repo path/to/repository

Out

This option is only for the Repo mode and it is used for specifying which type of file you want as output given by Sorts. You can choose between JSON and CSV and the default type is JSON.

CI mode

Also using the --mode flag and then typing ci you can access the CI mode which is for using in a CI/CD pipeline, specifically in the phase where users need approval to merge their commits with the main branch of the repository, where Sorts will check the mean risk of the commit and assign more approvers based on a configuration file.

Example:

m gitlab:fluidattacks/universe@trunk /sorts --mode ci platform/path/to/repository

You can check here for more information about using this mode.

At the moment, the CI mode can only be used on the GitLab platform.

Config

This option is only for the CI mode and it is used for specifying where is the yaml configuration file needed for this mode. If you don't specify where the file is then Sorts will look for it in the root of your repository with the name sorts_config.yaml.

Repository path

The only argument that Sorts receives in both Repo and CI modes is the absolute path to your repository. This can be the path in your local machine or the path that each platform defines for the repository when running the CI/CD pipeline.

Use the tool as a standalone app

Make sure you have the following tools installed in your system:
- Nix
- Makes
Now you can use Sorts by calling:
```
m gitlab:fluidattacks/universe@trunk /sorts
```
You can then use the --help flag to learn more about what Sorts can do for you.

The main Sorts function is analyzing a repository and output a file with the names and corresponding probabilities of such files being vulnerable, this can be done with the following command:
```
 m gitlab:fluidattacks/universe@trunk /sorts /path/to/repository
```
You can specify which type of output you want by using the --out flag. See more info about the CLI below.
When Sorts completes its analysis, it will provide you with a file using the type of output you selected. The results will contain the names of all the files of the repository with a corresponding probability of that file having a vulnerability.

Use the tool in your CI/CD pipeline

A Makes container can be found in the container registry. You can use it to run Sorts on any service that supports containers, including most CI/CD providers and then use its results to trigger any action you deem appropriate.

GitHub

   # .github/workflows/dev.yml
   name: Makes CI
   on: [push, pull_request]
   jobs:
      sorts:
         runs-on: ubuntu-latest
         steps:
            - uses: actions/checkout@f095bcc56b7c2baf48f3ac70d6d6782f4f553222
            - uses: docker://ghcr.io/fluidattacks/makes:latest
            name: sorts
            with:
               args: m gitlab:fluidattacks/universe@trunk /sorts /platform/path/to/repository

                        
                    
                            
                        
                            
                        

GitLab

# .gitlab-ci.yml
/sorts:
  image: ghcr.io/fluidattacks/makes:latest
  script:
    - m gitlab:fluidattacks/universe@trunk /sorts /platform/path/to/repository

Travis

# .travis.yml
os: linux
language: nix
nix: 2.3.12
install: nix-env -if https://github.com/fluidattacks/makes/archive/23.06.tar.gz
jobs:
  include:
    - script: m gitlab:fluidattacks/universe@trunk /sorts /platform/path/to/repository

Sorts also includes a built-in function, currently only on GitLab, that you can use in your Merge Request pipeline to assign more approvers when the mean risk associated with the commit exceeds a value that you can specify. Check more information about this function here.

Specifications on using the CI/CD mode

The CI/CD mode can help developers use Sorts to analyze a commit that is pushed to a repository and check what is the probability that the files that are in the commit are vulnerable. Based on the mean probability of all the files in the commit, Sorts can update the rules for allowing the commit to be merged with the main branch in order to give more risky files the attention the user deems necessary.

In order to use Sorts CI/CD mode correctly you will need a configuration file where you can specify how Sorts will handle the commits it analyzes. By default, Sorts will look for a file called sorts_config.yaml located in the root of your repository, however you can also specify the file path by using the --config flag. The file needs to be written in yaml format. The following is an example of a valid configuration file:

ci:
  enable: true
  max_risk: 70
  platform: gitlab
  required_approvals: 2
  approvers: ["user-1", "user-2"]
  token: ENV_VAR_CONTAINING_API_TOKEN

Let's take a look at the function of each parameter:

enable: Used for quickly enabling or disabling Sorts in your pipeline.
max_risk: How high can the commit mean risk be before you need to assign more approvers.
platform: The platform you are using for your development pipeline.
required_approvals: The number of approvals that you consider necessary when a commit goes over the max_risk.
approvers: The specific users which can approve the commit in case it goes over the max_risk. This parameter can be left empty to indicate that any developer in the repository can approve.
token: This is an environment variable which contains a token with API access for Sorts to be able to change the rules for approving the commit.

Make sure you don't write the token directly in the configuration file, this would be an exposure of sensitive information in your source code and Sorts only works by using the name of the environment variable that contains the token, not the token itself.

After creating the configuration file correctly and putting it in your repository, you can use our Makes container and Sorts ci mode in your pipeline. For example, in GitLab:

# .gitlab-ci.yml
/sorts:
  image: ghcr.io/fluidattacks/makes:latest
  script:
    - m gitlab:fluidattacks/universe@trunk /sorts /platform/path/to/repository

And when someone attempts to merge their commit to the repository, Sorts will act to assign more approvers based on the commit's mean risk and the configuration file that you defined.

Use the tool as a Docker container

For using Sorts as a container you only need to have docker installed and then use this command:

docker run -v <path/to/repository>:repo/<repository> ghcr.io/fluidattacks/makes:latest m gitlab:fluidattacks/universe@trunk /sorts /repo/<repository>

Replace <path/to/repository> with the absolute path to your repository and <repository> with the name of the repository.

The command will immediately download the appropriate image for running Sorts, mount your repository's directory in the container, run Sorts to analyze the repository and produce an output file as we already described in the standalone version.

Configure and use Sorts on your own | Fluid Attacks Help