Running a component scan using the Signature Scanner command line

--bdio2

Use BDIO 2's JSON-LD format for storing and transmitting scan evidence to the Black Duck server.

--binaryAllowedList <file extensions>

--sourceAllowedList <file extensions>

Use to create approved signature lists.

• --binaryAllowedList x, y, x where x, y, z are the approved file extensions for SHA-1 (binary) files.

• --sourceAllowedList a, b, c where a, b, c, are the approved file extensions for clean SHA-1 (source code) files.

Specifies the name of an existing project version to use as a clone.

To clone a project version, use the:

• --project parameter to specify the project you wish to clone from.

• --release parameter to specify the new project version.

• --cloneFrom parameter to specify the project version to use as a clone.

For example, to clone version 1.0 of project SampleProject to a new version called 2.0, you would include these parameters:

--project SampleProject --release 2.0 --cloneFrom 1.0

--exclude-from <Filename>

Excludes a directory or several directories from scanning.

The scanner automatically excludes these directories and the contents of these directories:

• CVS
• .svn
• .git
• .hg
• .bzr
• __MACOSX

The scanner automatically excludes files named:

• .cvsignore
• .git
• .gitignore
• .gitattributes
• .gitmodules
• .hgignore
• .hgsub
• .hgsubstate
• .hgtags
• .bzrignore
• vssver.scc
• .DS_Store

To exclude other directories, use --exclude to exclude a single directory; --exclude-from to specify a file that lists directories that should be excluded.

Exclusion guidelines:

• Leading and trailing forward slashes are required.

  For example, if you enter exclude /directory, a warning message will appear and the directory will not be excluded. If you enter /directory in the file, the directory will not be excluded.

• Directory names cannot contain double asterisks (**).

• Specify one directory per line in the file. Include the complete direct path. The path must be a relative path rather than an absolute path.

• You cannot exclude archives or contents within archives.

There are two additional methods you can use to exclude directories from scanning:

• Create an ignore file located in the $HOME/config/blackduck directory.

  Use this file to list excluded directories, relative to root. This option provides you with the ability to use one location to list all directories that need to be excluded.

  Lines in the ignore file must have the path from source root to the ignored directory, may have multiple subdirectories, and must have leading and trailing forward slashes (/).

  Create one of the following environment variables, as shown here, configured for Linux or Mac OS X:

  • export JAVA_TOOL_OPTIONS=" -Duser.home=<path>"

    The .ignore file must be located here: <user.home>/.config/blackduck/ignore

  • export XDG_CONFIG_HOME=<path>

    The .ignore file must be located here: $XDG_CONFIG_HOME/blackduck/ignore

  • export JAVA_TOOL_OPTIONS="-Dblackduck.scan.excludesFile=<path>/<file>"

    The .ignore file can be in any location and have any name.

  For Windows systems, use the Control Panel to access the Advanced System Settings dialog box to create the environment variables.

• Create individual .bdignore files which can be located in any directory.

  Use this file to list the excluded subdirectories in the directory where the .bdignore file is located. You must create a .bdignore file in each directory that has subdirectories you want to exclude.

You must also follow the exclusion guidelines as described above when using either of these methods.

Number of minutes the scan client waits for the File System scan (signature scan) to be in either the completed or error status before starting the snippet or string search scan. Must be a positive integer number.

Individual file matching is the identification of a component based purely upon the checksum information of a single file. By default, individual file matching is disabled. To enable individual file matching, select one of the following options:

• source. Performs individual file matching only on files with this extension: .js, c, h, c+, cc, cpp, cxx, hh, hpp, hxx, h+, cs, idl, rc

• binary. Performs individual file matching on files with these extensions: .apklib, .bin, .dll, .exe, .o, and .so.

• all. Performs individual file matching on all files with extensions matching "*".

• both. Performs individual file matching on file extensions only using both approved signature lists.

Any other value will be ignored and individual file matching will remain disabled.

Click here for more information on using this parameter with approved signature lists.

Location of the log directory which contains all scanner log files. You must specify the --logDir parameter for log files to be saved.

--max-request-body-size <size>

--max-update-size <size>

Controls how scan data is streamed (buffered) from the Signature Scanner to Black Duck.

In rare cases, you may need to modify these values to better suit your network, for example, decreasing the values if there are issues with your network or increasing the default values if your network is highly stable.

• --max-request-body-size. Size of the main request that uploads the scan data for scanned paths.

  Specify a value, in bytes. The default is 20000000 bytes. The recommended minimum value is 2000000 bytes; the recommended maximum value is 2000000000 bytes.

• --max-update-size Buffers an update request to inform Black Duck when Signature Scanner has completed uploading the data of individual URIs (scanned paths).

  Specify a value, in bytes. The default value of 10000 bytes. The recommended minimum value is 1000 bytes; the recommended maximum value is 1000000 bytes.

--min-scan-interval=<time in hours>

Minimum scan interval setting (in hours), which may be used to limit daily rate of the signature scan for given code location. If set to greater than 0, signature scans will not be processed if they occur before the set scan interval.

--name <scan name>

Unique name identifying this scan. This name is displayed on the Scans page. Click here for more information.

Non-interactive mode.

Instead of the --no-prompt parameter, you can set the BD_HUB_NO_PROMPT environment variable to enable non-interactive mode.

Forces the scanner to prompt you for the password for the user account with the code scanner role:

• Specifying the --password parameter without the password value results in the scanner prompting you for the password.

• Specifying the password value displays a warning message notifying you that specifying the password on the command line will not be supported in future versions of Black Duck; the scan then runs.

Set the BD_HUB_PASSWORD environment variable with the Black Duck server password instead of passing an argument to the --password parameter:

• If you set this environment variable and specify the --password parameter, the scanner prompts you for the password; it does not check the password value against the value specified in the environment variable.

• If you set this environment variable and do not specify the --password parameter, the scanner does not prompt you for the password.

If this environment variable is not set, the scanner prompts you for the password whether you include or omit the --password parameter.

Instead of specifying a username and password, use the BD_HUB_TOKEN environment variable to specify a Black Duck API token.

Port on which the Black Duck server instance is listening.

Name of the project to which you want to map the scan results.

If you specify a project, you must specify a version.

• If the project and project version exist, the scanner maps or remaps the scan results.

• If the project exists, but the version does not, the scanner creates the version and maps the scan results.

--project-group <project group name>

Assigns the project to the designated project group. If the project does not already exist, it is created in the corresponding project group.

This parameter has no effect if the project already exists or if the specified project group does not exist.

Name of the project version to which you want to map the scan results.

If you specify a version, you must specify a project.

• If the project and project version exist, the scanner maps or remaps the scan results.

• If the project exists, but the version does not, the scanner creates the version and maps the scan results.

--discard-unmatched-files

Protocol to use to connect to the server hosting the Black Duck installation. Possible values are http or https; https is the default value. You must include -scheme https to specify the https protocol.

--snippet-matching

--snippet-matching-only

--snippet-matching-all-source

--full-snippet-scan

Select one of the following for snippet matching:

• --snippet-matching. Selecting this parameter enables a two-phase approach to scanning. First, a component scan is completed whereby only files that have changed since the previous scan are scanned. Once that component scan is completed, a snippet scan runs on those newly scanned files only: if a previously scanned file has not changed, it will not be rescanned for snippets.

  Black Duck Software recommends using this parameter for snippet scanning.

• --snippet-matching-only. Selecting this parameter runs a snippet scan only on files that have changed; a component scan is not performed.

  You must have successfully completed a full file scan prior to selecting this parameter.

• --snippet-matching-all-source. Selecting this parameter runs a snippet scan for all files with supported extensions (whether they belong to unmatched directories/archives or not).

• --full-snippet-scan. Selecting this parameter forces the snippet scan to search the KnowledgeBase regardless of locally cached matches from previous snippet scans.

  This parameter must be used with the --snippet-matching, --snippet-matching-only, or the --snippet-matching-all-source parameter:

  • With the --snippet-matching parameter: First, a signature scan is completed. Once that scan is completed, a snippet scan is performed on unmatched files or files belonging to unmatched directories/archives

  • With the --snippet-matching-only parameter: A snippet scan is performed on unmatched files or files belonging to unmatched directories/archives; a signature scan is not executed, but it must already exist.

  • With the --snippet-matching-all-source. First, a signature scan is completed. Once that scan is completed, a snippet scan is performed for all files with supported extensions (whether they belong to unmatched directories/archives or not).

To upload source files, you must use the --upload-source parameter, as described below.

Forces the scanner to prompt you for the password for the client certificate.

You can specify the --tlscertpass parameter and/or set the BD_HUB_CLIENTCERT_PASS environment variable which specifies the private key password for the client certificate, for example, when --tlscert points to an encrypted PKCS #12 key store.

The result of specifying the --tlscertpass parameter depends on whether the key is encrypted.

• If the key is encrypted, the scan will fail if you do not set the BD_HUB_CLIENTCERT_PASS environment variable or specify the --tlscertpass parameter.

  • If you set the environment variable and specify the --tlscertpass parameter, the scanner prompts you for the password; it does not check the password value against the value specified in the environment variable.

• If the key is not encrypted, regardless of whether the BD_HUB_CLIENTCERT_PASS environment variable is set:

  • Specifying the --tlscertpass parameter forces the scanner to prompt you for the password for the client certificate. The scan will fail unless the password is empty.

  • If you do not specify the --tlscertpass parameter, the scan will succeed.

Black Duck client certificate private key file. Automatically sets --scheme to https.

Black Duck client certificate chain file or key store file. Automatically sets --scheme to https. Click here for more information on using certificate-based authentication.

Uploads the source file, an optional feature for snippet matching, embedded license search, and copyright text search.

This parameter is optional with the --snippet-matching or --snippet-matching-only parameters or with the --license-search and/or --copyright-search parameters.

Black Duck user account with the code scanner role.

Instead of specifying a username and password, use the BD_HUB_TOKEN environment variable to specify a Black Duck API token.

Other environment variable:

• BD_HUB_TOKEN

Used to specify the Black Duck API token which is the preferred authentication method over username and password.

Use the Profile page in the Black Duck UI or the api-token-rest-server API to manage API tokens.