How to run the scanner with a custom configuration | Fluid Attacks

Configure the tests by the standalone scanner

Fluid Attacks' scanner is a security vulnerability detection tool. This means it scans your source-code, infrastructure and applications and reports to you the security problems they have.

The scanner can be used by users in two modes:

  1. As a paid software as a service, included in Fluid Attacks' Essential plan or superior
  1. As a free and open-source CLI tool

In the first case, Fluid Attacks configures everything for you. The service will constantly monitor the security state of your system, open new security findings as they are introduced, and close security findings once they are no longer present in the system. Moreover, at all moments you would be provided with reports and analytics on Fluid Attacks' platform.

When run as a free and open-source CLI tool, referred to as Machine Standalone, you are in charge of configuring the tool. It will scan vulnerabilities in the target of your choice and report results back to you in pretty-printed or CSV format. Fluid Attacks provides Docker containers with the Machine Standalone CLI. They can be found on the Docker Hub repository.

This page guides you through the configuration of the tool.

CLI structure

Fluid Attacks' command-line interface is based on the following structure

skims [GLOBAL_OPTIONS] COMMAND [OPTIONS] [ARGUMENTS]

CLI global options

--help

Feel free to pass the --help flag to learn more about the things it can do for you.

This will provide you with information on how to use the tool, as well as a short description of each existing flag.

Example:

skims --help

--strict

With this option you can run Machine Standalone in strict mode, which means that it will fail the execution (with an exit code 1) if it finds at least one vulnerability in your targets.

Ideal for using Machine Standalone as a CI/CD job.

Example:

skims --strict scan path/to/config.yaml

CLI command

Perform vulnerability detection

skims scan .

scan options

--csv

The output of the scan will be in comma-separated values (CSV) format, creating a skims_output.csv file in the path that was executed.

Example:

skims scan --csv path/to/directory

--sarif

The output of the scan will be in Static Analysis Results Interchange Format (SARIF), creating a skims_output.sarif file in the path that was executed.

Example:

skims scan --sarif path/to/config.yaml

--execution-module

This option is effective when a configuration file exists. If multiple modules are configured in this file, you can select which module to execute (apk, dast, cspm, sast, sca).

You can choose one or more modules, separating them with commas and without spaces.

Example:

skims scan path/to/config.yaml --execution-module cspm,dast

scan arguments

Configuration file

This argument is the path to a .yaml configuration file in which you can customize the execution of the scanner

Example:

skims scan path/to/config.yaml

The configuration format is explained in the Configuration guidelines.

Directory

This argument is the path to a directory on which the scanner will be executed.

Example:

skims scan path/to/directory

URL

This argument is a URL. There are two types of URLs that the Fluid Attacks scanner analyzes

  1. Git repository URL: If it is a URL of a Git repository, the Fluid Attacks tool will download the repository and analyze it.

    Example:

    skims scan https://github.com/tree-sitter/tree-sitter.git

  2. Page or web application URL: If it is the URL of a page or web application, a dynamic application security testing (DAST) scan will be carried out

    Example:

    skims scan https://git-scm.com

Create a configuration file

The most flexible way to run the scanner is to use a configuration file.

The scanner supports a configuration file in YAML syntax. The most simple and recommended configuration file is shown below:

namespace: myapp
output:
  file_path: ./Fluid-Attacks-Results.csv
  format: CSV
working_dir: .
language: EN
apk:
  include:
    - glob(**/*.apk)
sast:
  include:
    - .
  exclude:
    - glob(**/node_modules/**)
    - glob(**/test/**)
sca:
  include:
    - .
  exclude:
    - glob(**/test/**)

Check the keys and path sections for a detailed explanation of all the keys and paths format that you can use to take full advantage of the scanner capabilities.

Configuration file keys

The following is a detailed explanation of what each key in the configuration file represents.

All the keys are optional to be personalized for each analysis needs. There should be no issues with the tool if any of them are not included in the configuration file.

namespace

An arbitrary name for the analysis. Normally the name of the repository to be analyzed.

namespace: my_app

working_dir

Used as the path to the repository you want to analyze. With this key, the paths you configure in the DAST, SCA and APK keys will be relative paths to this directory.

working_dir: /absolute/path/to/directory

commit

Used to run Machine Standalone using a specific commit of its source repository. For this you have to pass the commit SHA of the version you want to use. You can see the list of commits here.

commit: e59607b9de3ef4c13d292705fg3da1ff0c67eb38

language

Language used to generate reports, valid values are: EN (English) and ES (Spanish). If not present, defaults to EN.

language: ES

output

By default, the vulnerabilities that Machine Standalone finds in your code will appear in the terminal. However, you can modify this configuring this key with the two attributes:

  • file_path: Defines where you want to store the output
  • format: Defines the format of the output; valid values are CSV (comma-separated values) or SARIF (Static Analysis Results Interchange Format).
output:
  - file_path: relative/path/to/file
  - format: CSV

checks

This configuration key specifies which findings are run. Each finding represents a type of vulnerability. The complete list of findings supported by Fluid Attacks' scanner can be found here and a detailed description of each finding can be found here.

If the key is not present, all the findings supported by the scanner are run. As a user, we recommend you not to use this key, to ensure your repo is checked against ALL currently supported findings.

checks:
  - F011
  - F393

strict

With this option you can run the scanner in strict mode, which means that it will fail the execution (with an exit code 1) if it finds at least one vulnerability in your targets.

Ideal for using the scanner as a CI/CD job.

strict: true

file size limit

We restrict the size of files processed to prevent extended analysis times. If crucial files are omitted as a result, you can remove this restriction by setting it to false.

file_size_limit: false

sast

With this key you activate the static application security testing (SAST) technique for analyzing your source code. This key has three configuration options:

  • include key (mandatory): Specify the paths to the files or directories that you want to analyze.
  • exclude key (optional): As the name implies, specify any files or directories you want to exclude from the analysis.
  • recursion-limit key (optional): Use this key if your SAST execution is taking a long time (more than 1 hour) or if any memory/recursion errors show up. It must be set to an integer (The recommended value is 1000)
sast:
  include:
    - /relative/path/to/file
    - relative/path/to/directory/
  # Optional keys
  exclude:
    - glob(**/node_modules/)
  recursion-limit: 1000

Read the path section for information about the path format recognized by Machine.

sca

With this key you activate the software composition analysis (SCA) for your source code. This key has two configuration options, similar to sast.

  • include key (mandatory): Specify the paths to the files or directories that you want to analyze.
  • exclude key (optional): As the name implies, specify any files or directories you want to exclude from the analysis.
sca:
  include:
    - /relative/path/to/file
    - relative/path/to/directory/
  # Optional keys
  exclude:
    - glob(**/test/)

apk

To activate the reverse engineering checks for Android APKs, you need to use this key.

This key has two configuration options, similar to sast.

  • include key (mandatory): Specify the paths to the files or directories that you want to analyze.
  • exclude key (optional): As the name implies, specify any files or directories you want to exclude from the analysis.
apk:
  include:
    - /relative/path/to/file
    - relative/path/to/directory/
  # Optional keys
  exclude:
    - glob(src/**/test*.apk)

dast

With this key you activate the dynamic application security testing (DAST) for your endpoints.

This key has three configuration options:

  • urls key (mandatory): List all URLs that you want the scanner to analyze.
  • http_checks key (optional): This can disable HTTP checks for your URLs.
  • ssl_checks key (optional): This can disable SSL checks for your URLs.

These last two keys expect a value either false or true and by default they are set to true.

dast:
  urls:
    - https://my-app.com
    - http://localhost.com
  # Optional keys
  http_checks: true
  ssl_checks: false

cspm

With this key you activate the cloud security posture management (CSPM) scans for your cloud environments. To ensure that it works correctly, you should provide the credentials used to access each one of them as follows.

Every sub-key (AWS, Azure and GCP credentials) is optional, however, when you include one, you must include at least one set of credentials.

namespace: namespace
cspm:
  # For AWS
  aws_credentials:
    - access_key_id: "000f"
      secret_access_key: "000f"
    - access_key_id: "000e"
      secret_access_key: "000e"
  # For Azure
  azure_credentials:
    - client_id: "000f"
      client_secret: "000f"
      tenant_id: "0000f"
      subscription_id: "000f"
  # For GCP
  gcp_credentials:
    - private_key: "000f"
    - private_key: "000e"

debug

This key can be used to run the scanner under a debug mode. Currently, this mode is only available for SAST checks, and it enables the scanner to generate two SVG files in the ./skims directory of the home directory.

This is useful for developers, when adding SAST checks. As a user, it is not recommended that you run the scanner using this option.

For more details, please check the development documentation.

Specify the path

You can specify your paths in two different ways:
  1. Using a path relative to the working directory (only works if the key working_dir is defined)
namespace: namespace
working_dir: /test/directory
sast:
  include:
    - src/main/java/org/test/Test.java
  1. Use Unix-style globs, relative to working_dir
namespace: namespace
working_dir: /test/directory
sast:
  include:
    - glob(*)
  exclude:
    - glob(**.java)
    - glob(src/**/test*.py)

Configuration file example

A highly personalized configuration file is shown below.

namespace: my_app
working_dir: /path/to/your/repository
commit: sha_of_the_commit of the scanner's source repo
language: EN
output:
  file_path: /path/to/results.csv
  format: CSV
checks:
  - F052
strict: false
file_size_limit: false
sast:
  include:
    - ./relative/path/to/file/or/dir
    - src/main/java/org/test/Test.java
    - glob(*)
    - glob(**.java)
    - glob(src/**/test*.py)
sca:
  include:
    - .
apk:
  include:
    - ./relative/path/to/build/awesome-app-v1.0.apk
    - build/awesome-app-v1.0.apk
cspm:
  aws_credentials:
    - access_key_id: "000f"
      secret_access_key: "000f"
dast:
  urls:
    - https://localhost.com
    - https://localhost.com:443
  ssl_checks: true
  http_checks: true
debug: true
Have a question about the scanner or encountered a problem? Read the scanner FAQ.
Free trial
Search for vulnerabilities in your apps for free with Fluid Attacks' automated security testing! Start your 21-day free trial and discover the benefits of the Continuous Hacking Essential plan. If you prefer the Advanced plan, which includes the expertise of Fluid Attacks' hacking team, fill out this contact form.