Documentation

Installation in Linux

Assumptions

  • The CLI tools are by default installed at /usr/bin
  • The system uses a deb or rpm package manager

1. Access the deliverables

Access information to the FossID deliverables is provided in the delivery mail. Download and extract the fossid-cli-tools-VERSION.zip.

1.1. Install the FossID deliverable

Debian / Ubuntu:

sudo dpkg -i fossid-cli-tools-VERSION_amd64.deb

RedHat:

sudo yum localinstall fossid-cli-tools-VERSION_amd64.rpm

2. FossID CLI pre-requisites

2.1. Install packages required by CLI

Debian / Ubuntu:

Update package repository:

sudo apt-get update

Install packages:

sudo apt-get -y install default-jre

Redhat:

Install packages:

sudo yum -y install java-11-openjdk

2.2 Test that all is installed correctly

Run the following test command to test whether CLI tools have access to the can server.

fossid-cli --host YOUR_SERVER_HOST --token YOUR_TOKEN --test-route

Note: The host address and the token have been provided to you at your FossID delivery site. If you do not use FossID’s scan servers, tokens are administered by your scan server administrator.

3. FossID Configuration

3.1. Basic fossid.conf settings

Fossid configuration file can be used to configure the scan server credentials and additional scan options.

To configure the scan server credentials:

1.- Access /etc/fossid.conf

2.- Configure Scan server access: Update these config options with info at your FossID delivery site, or by your scan server admin if you do not use FossID’s scan servers.

[CLI]

;FOSSID CLI CONFIGURATION

;Server credentials
;-------------------------
;You need a server host name and a scanning token in
;order for the FOSSID CLI to obtain scan results

;cli_server_host = YOUR_SERVER_HOST
;cli_token = YOUR_TOKEN

;Scan configuration
;------------------
;These options allow you to customize scanning parameters

;Minimum amount of code instructions to match
;This is approximately equivalent to lines of code but
;varies depending on programming language and coding conventions
;The default value is 10 and the minimum accepted value is 6
;cli_sensitivity = 15

;Maximum number of matches to be displayed. Defaults to 10
;cli_match_limit = 10

;Number of threads to launch when scanning multiple files.
;Each thread has it's own persistent HTTP connection to the server.
;Default is auto
;cli_threads = 8

;Prefix that identifies matched lines of code when requesting
;matching source code with the --mirror parameter
;cli_snippet_marker = "==>"

;Ignore HTML/XML tags for the following comma separated list of file extensions
;cli_strip_tags = .html

;Do full-file matching only (no snippet matching).
;Set to 1 to enable. Default is 0.
;cli_ffm_only = 0

;Only do snippet matching (no full file matching).
;Set to 1 to enable. Default is 0.
;cli_snippet_only = 0

;Display only matches and do not report "match=none" for files without
;matches. Set 1 to enable. Default is 0.
;cli_hide_nomatch = 0

;Follow symlinks when scanning directories recursively. Set to 1
;to enable it. Default is 0 (do not follow symlinks)
;cli_follow_symlinks = 0

;How many times to retry in case of network issues (default: 2 times)
;cli_retry = 2

;How long to wait each time before retrying, in seconds (default: 10 seconds)
;cli_retry_wait = 10

;Timeout for HTTP connections. (default: 300 seconds)
;cli_timeout = 300

;Skip binary files. Default is 0 (scan all files)
;cli_skip_binaries = 0

;Prettify JSON output. Set 1 to enable. Default is 0 (single-line JSON objects)
;cli_pretty_json = 0

;Maximum file size in bytes. Snippet scanning is only performed on bytes below
;this limit. Default values is 524288 bytes. Deprecated alias: cli_max_file_length
;cli_max_file_size = 524288

;Minimum file size in bytes. Files below this limit are skipped due to being too small.
;The default is 0 (no file is too small). Deprecated alias: cli_min_file_length
;cli_min_file_size = 0

;Enable or disable ssl verification. Default is enabled (1). Set to 0 to disable.
;cli_ssl_verify = 1

;Set to 1 to perform certificate revocation checks in a "best effort" manner. Windows only.
;Please see https://curl.se/libcurl/c/CURLOPT_SSL_OPTIONS.html (CURLSSLOPT_REVOKE_BEST_EFFORT)
;for more information. (Default: 0)
;cli_ssl_revoke_best_effort = 1

;Enable (1) or disable (0) sending the filename.
;The filename is used to provide better source code identification.
;cli_send_filename = 1

;Override the Alfred version
;cli_alfred_version = 3.2.2r

;Select whether to enable support for dependency analysis in signatures.
;This means that for all package files (package.json, pom.xml, etc), the actual contents
;of the files will be added to the signature. This is disabled by default.
;cli_dependency_analysis = 1

;Select whether to enable SHA-1 hashes in signatures.
;Default is disabled.
;cli_enable_sha1 = 1

;Add or remove JSON fields in the match response
;cli_fields = component.author,component.artifact,component.version

;Set the KB version (default 2, specify 1 for old KB version)
;cli_kb = 2

;Set the CLI User Agent used for the HTTP request
;This sets a custom HTTP header x-fossid-cli-user-agent to the specified value
;cli_user_agent = CustomApp/1.0

;Set a scan depth to speed up scans at the cost of result quality.
;The default is 1.0. Maximum is 1.0.
;This feature is experimental and might be removed in the future.
;cli_scan_depth = 1.0

;Set the match format. Default 2.
;Please refrain from using this unless you need to use match format 1 temporarily
;during a transition to match format 2.
;cli_match_format = 2

;Proxy settings
;--------------
;Specify here your proxy credentials
;If you prefer not to type your proxy password here, you could
;encrypt your password with using the --password option (see help)

;Your proxy hostname or IP
;cli_proxy_host=

;Your proxy port (i.e. 8080)
;cli_proxy_port=

;Your proxy username
;cli_proxy_user=

;Your proxy password (plain text), or
;cli_proxy_pass=

;Your encrypted proxy password (created with --password)
;cli_proxy_secure_pass=

;Your SSL proxy client certificate
;cli_proxy_cert=

;Your private key for SSL and TLS proxy client certificate
;cli_proxy_key=

3.- Save your fossid.conf file. Note the change to configuration is immediate, no restart is required.

Proxy configuration and additional options for the CLI tools is available in the same file.

4. Using FossID

For configuration options and usage examples, run

fossid-cli --help