Sorts user guide

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, employ the --mode flag with the repo argument.

Example:

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

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, employ 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 .

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

1. Make sure you have the following tools installed in your system:

   • Nix 
   • Makes 

2. 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 outputting 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

3. 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 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

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 for 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

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).