Scan Directives

SourceClear Software Composition Analysis

Sourceclear’s Agent supports scans that include per-scan directives (known as scan directives). These can be specified on a per-project basis by placing a srcclr.yml file at the root of the scan.

Below is a list of the supported scan directives for use in a srcclr.yml.

Agent Directives

scan_collectors:

By default, SourceClear agents find all supported build tools and package managers in the directory specified by the scan command (or the current directory for CI scans). Using scan_collectors, it’s possible to specify which build tools/package managers to use. The possible values for scan_collectors are:

  • gem
  • maven
  • gradle
  • pip
  • ant
  • npm
  • bower
  • jar
  • ivy
  • yarn
  • sbt
  • "go get"
  • trash
  • govendor
  • godep
  • glide
  • cocoapods
  • composer
  • MSBuildDotNet

Example:

scan_collectors: gem, maven

skip_collectors:

By default, SourceClear agents find all supported build tools and package managers in the directory specified by the scan command (or the current directory for CI scans). Using skip_collectors, it’s possible to control which build tools/package managers to skip when running a scan. The possible values for skip_collectors are:

  • gem
  • maven
  • gradle
  • pip
  • ant
  • npm
  • bower
  • jar
  • ivy
  • yarn
  • sbt
  • "go get"
  • trash
  • govendor
  • godep
  • glide
  • cocoapods
  • composer
  • MSBuildDotNet

Example:

skip_collectors: npm, bower

vuln_methods_ignored_directories:

A comma-separated list of directories which should be ignored in vulnerable methods analysis. Allows the defaults to be overriden.

Example:

vuln_methods_ignored_directories: doc

vuln_methods_extra_ignored_directories:

A comma-separated list of directories which adds to the default per-language set ignored by vulnerable methods analysis.

vuln_methods_extra_ignored_directories: doc, test

The defaults are:

  • Ruby: test
  • Java: test
  • Python: test, tests, doc, docs, bin, .virtualenv, env, venv

Multi-Language Directives Scope

Ruby, Java, NPM, Yarn, Bower, PHP

When specified, the ‘scope’ directive will limit the dependency resolution (and therefore, the discovered dependencies) to those within the specified scope. It will also include any scope that the specified scope inherits from (if supported by the build system). This will apply the same scope to any package manager used in the project.

For PHP the only accepted scope is --no-dev which will only install production packages.

Example:

# Java example
scope: testCompile

# Prevent scanning 'devDependencies' for an NPM project
scope: production
Note: This example indicates that we only wish to include dependencies that are in the ‘testCompile’ scope, or a scope that ‘testCompile’ inherits from.

Java compile_first

Boolean value which forces SourceClear agent to perform a compilation prior to scanning. Defaults to true.

Example:

compile_first: false

install_first:

Boolean value which forces SourceClear agent to perform a compilation and installation prior to scanning. Defaults to true.

Example:

install_first: false

custom_maven_command:

String attribute with which the SourceClear agent will utilize the supplied mvn options instead of compile and install which are the defaults. This command must take the form of a single String object.

Example:

custom_maven_command: clean compile

custom_maven_exec:

String attribute which specifies the full path to a custom maven executable to use. Defaults to using the maven executable on the PATH of whatever environment the scan is being performed in.

Example:

custom_maven_exec: /usr/local/bin/mvn

custom_gradle_exec:

String attribute which specifies the full path to a custom gradle executable to use. Defaults to using the gradle executable on the PATH of whatever environment the scan is being performed in or a gradlew file in the directory being scanned if it exists.

Example:

custom_gradle_exec: /usr/local/bin/gradle

custom_ant_exec:

String attribute which specifies the full path to a custom ant executable to use. Defaults to using the ant executable on the PATH of whatever environment the scan is being performed in.

Example:

custom_ant_exec: /usr/local/bin/ant

ant_build_steps:

String attribute with custom Ant build steps to run before scanning.

Example:

ant_build_steps: clean compile

ivy_settings_filename

By default, SourceClear uses ivysettings.xml file found in the root folder. You may use this directive to specify another Ivy Settings file to use.

Example:

ivy_settings_filename: ivysettings-release.xml

ant_lib_dir:

Comma-separated relative (to scan project root) directory paths.

Example:

ant_lib_dir: lib/, main/jarfiles/

gradle_location:

This directives supports setups where the gradlew file may not exist at the root of a Gradle project. This should be a relative path, and include the gradlew filename at the end.

Example:

gradle_location: api/gradlew

gradle_tasks:

By default the ‘classes’ task is used when performing Gradle scans. This allows for complete dependency resolution and generation of class files while not going far enough in the build to execute unit and integrations tests. If you have a custom task that should be run instead it can be placed here. This is a space separated list of tasks to execute.

Example:

gradle_tasks: clean compile

gradle_filter_task:

This allows the user to dynamically pin scans to only certain sub-modules, based on whether that sub-module contains the specified task. In the example below, the scan would be limited to sub-modules containing the classes task.

Example:

gradle_filter_task: classes

Ruby

force_bundle_install:

Boolean attribute that forces the SourceClear agent to perform a ‘bundle install’ even when a Gemfile.lock already exists. Defaults to false.

Example:

force_bundle_install: true

Python

system_site_packages:

This option maps to a boolean which indicates whether the Python virtualenv image with which we scan for pip dependency information should include the system site packages. The default value for this is false.

Example:

system_site_packages: true

use_system_pip:

This option maps to a boolean which indicates whether the SourceClear Agent should use the pip package that is found on the machine instead of the bundled version of pip. The default value for this is false.

Example:

use_system_pip: true

pip_requirements_file

The attribute value associated with this key is a file that indicates an alternative location to find the PIP requirements file for a particular project. If this is not specified, we assume that we should look for requirements.txt, dev-requirements.txt, or requirements-dev.txt in the root of the project.

Example:

pip_requirements_file: libs/requirements.txt

Bower

allow_root:

By default Bower doesn’t permit the root user to perform installation tasks. While this is for security reasons, many Docker setups use the root user. Using this directive and setting it to true will instruct Bower to use the --allow-root flag.

Example:

allow_root: true

Golang

force_go_install:

Boolean value which forces SourceClear agent to download the Go dependencies used by the project before scanning for them.

Example:

force_go_install: false

PHP

skip_composer_install:

Boolean value which can be used to stop SourceClear re-installing composer packages. If this is used, the composer.lock file MUST be present in the repository already.

Example:

skip_composer_install: false