Configure and use Sorts on your own

This document guides you through configuring and using Sorts, Fluid Attacks' tool to assess the vulnerability probability of files in code repositories.

CLI structure

The Sorts command-line interface (CLI) follows this structure:

sorts [OPTIONS] REPOSITORY_PATH

The available options allow you to analyze repositories or commits and customize the output format.

Repo mode

Repo mode analyzes a single repository and generates a file describing the vulnerability probability of each file. To use Repo mode, use the --mode flag with the repo argument.

Example:

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

In Repo mode, you can specify the output file format using the --out option. The available formats are JSON (default) and CSV.

CI mode

CI mode integrates Sorts into your CI/CD pipeline. It is specifically designed for the phase where users need approval to merge their commits, where Sorts checks the mean risk of a commit and adjusts the required approvers based on a configuration file. To use CI mode, use the --mode flag with the ci argument.

Example:

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

CI mode requires a YAML configuration file to define how Sorts handles commits. By default, Sorts looks for sorts_config.yaml in your repository's root directory. You can specify a different file path using the --config flag.

For more detailed information on using CI mode, refer to Use the tool in your CI/CD pipeline.

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

Repository path

Both Repo and CI modes require the absolute path to your repository. This can be a local path or the platform-specific path used in your CI/CD pipeline.

Use the tool as a standalone app

Make sure you have the following tools installed in your system:
- Nix
- Makes
Use Sorts as follows:
```
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
```
Optionally, specify which type of output you want by using the --out flag.

Upon completing the analysis, Sorts generates an output file (JSON or CSV) containing the names of all files in the repository and their corresponding vulnerability probabilities.

Use the tool in your CI/CD pipeline

You can find a Makes container can be found in the container registry, which you can use 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. Read on to learn how to use it with different CI/CD providers.

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

        

Sorts 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 specified value. Learn more about this in Specifications on using the CI/CD mode.

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

Specifications on using the CI/CD mode

Sorts' CI/CD mode analyzes a commit that is pushed to a repository and checks what the probabilities are for the files that are in the commit to be vulnerable. Based on the mean vulnerability probability of all the files in the commit, Sorts can update the rules for allowing the commit to be merged within the main branch in order to give more risky files the attention the user deems necessary.

To use this mode correctly, you need a configuration file to specify Sorts' behavior. By default, Sorts looks 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

Here is the function of each parameter:

enable: Enables or disables Sorts in your pipeline
max_risk: The upper threshold for the commit's mean risk before additional approvers are required
platform: Your development platform (currently only gitlab is supported)
required_approvals: The number of approvals needed when a commit's risk exceeds max_risk
approvers: A list of users who can approve high-risk commits (leave empty to allow any developer to approve)
token: An environment variable containing an API token for Sorts to modify approval rules.

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. 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 placing it in your repository, you can use Fluid Attacks' Makes container and Sorts CI mode in your pipeline. See the following example for GitLab:

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

When a merge request is created, Sorts automatically adjusts the required approvals based on the commit's risk and your configuration.

Use the tool as a Docker container

To use 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 repository's name.

This command downloads the necessary image, mounts your repository, runs Sorts, and generates an output file (JSON or CSV).

Configure and use Sorts on your own | Fluid Attacks Help