Skip to main content

Configuration keys

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 using a specific commit of its source repo. 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, ES. If not present, defaults to EN (English).

language: ES

output​

By default, the vulnerabilities that Machine 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 or SARIF
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 Machine 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 Machine 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 Security Analysis and Static Testing (SAST) for 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 (>1h) 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
tip

Read the Format 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) 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 Keys
    - access_key_id: "000f"
      secret_access_key: "000f"
    # Using Session Token
    - access_key_id: "000e"
      secret_access_key: "000e"
      session_token: "000e"
    # Using Custom Trust Policy
    - role: "000d"
      external_id: "000d"
  # 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 docs

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
Last updated on