Getting Started

Introduction

For your convenience, Soteria comes as a pre-built executable file, which can be found here. In the linked page, we provided two executables per platform (Linux, MacOS, Windows), one for amd64 and arm64 architectures.

Requirements

Soteria does not depend on anything else. Thus, once you downloaded the executable file, you can start using it straight away.

Commands

Soteria has 3 commands: check, stats, and detectors. Each command has also a set of flags that can be used. Following are the --help output of each command.

$ soteria check --help

NAME:
   soteria check - Perform a static analysis check on the given file(s) or directory

USAGE:
   soteria check [command options]

OPTIONS:
   --config value, -c value    Path to the configuration file
   --repo value, -r value      Name of the repository (will be used to name the global results file)
   --string, -s                YAML being passed as string (default: false)
   --verbose, -v               Verbose mode (default: false)
   --max-rows value, -m value  Maximum number of rows to print for the statistics table (default: 10)
   --global, -g                Output only one global JSON file per repository with the aggregated results (default: false)
   --out value, -o value       Output directory for the workflows' statistics (one JSON file per workflow will be generated, plus a global one)
   --help, -h                  show help

Configuration File

A YAML configuration file can be optionally passed to Soteria. This file defines some options that the tool will set based on the developer's preferences. For instance, a developer can indicate which detectors should be used in the static analysis. A comprehensive list of misconfigurations for which a detector can be found in Introduction/Misconfigurations. To tell Soteria which detectors to use, the following syntax can be used:

detectors:
  method: "include"
  names:
    - "poisoned-pipeline-execution/pwn-request"
    - "insufficient-pbac/*"

In the case above, we are telling the tool to use the pwn-request detector together with all detectors present in the insufficient-pbac group (denoted by the /*). If, instead, we want to exclude specific detectors, the following syntax can be used:

detectors:
  method: "exclude"
  names:
    - "poisoned-pipeline-execution/*"
    - "dependency-chain-abuse/no-hash-version-pin"

In the case above, all but the no-hash-version-pin misconfiguration and the misconfigurations present in the poisoned-pipeline-execution group will be used during the analysis of the workflow.