Deepfactor CLI Reference

Deepfactor Support

October 16, 2020 21:37

dfctl is Deepfactor's command line interface. This can be downloaded from Deepfactor's public package repositories. It is installed in the /usr/bin/dfctl location. Along with dfctl, another file, libdf.so is also installed at /opt/deepfactor/lib/libdf.so

DF CLI Docker Init

The DF CLI for launching docker images with DF instrumentation uses Docker Volume. This volume contains the runtime libs required to run the application with DF. This volume is mounted while launching the application. The volume must be initialized before it can be used to launch application images with DF instrumentation.

Users must execute the following command to initialize the Docker volume.

curl https://repo.deepfactor.io/install-dfctl.sh | sh -

Install specific versions of the Deepfactor runtime:

curl https://repo.deepfactor.io/install-dfctl.sh | sh -s -- --version 2.2.0-1200

Install dfctl without initializing docker volumes:

curl https://repo.deepfactor.io/install-dfctl.sh | sh -s -- --no-docker-volume

Install dfctl with a specific runtime image:

curl https://repo.deepfactor.io/install-dfctl.sh | sh -s - --dfrt-image 241761893560.dkr.ecr.us-east-2.amazonaws.com/df/runtime --version 2.2.0-1200

App Launcher

Deepfactor's dfctl run command now supports two formats to run an application directly or a container via --docker-run.

dfctl app launcher:

dfctl run 
[-v] [-f] -a "application name" -c "component name" 
[-p "alert policy"] [--version component-version]
[--env "environment name"] [--entrypoint-libc "musl"|"glibc" ]
[--disable-stack-traces] [--enable-method-tracing]
--cmd command with arguments

dfctl docker app launcher:

dfctl run 
[-v] [-f] -a "application name" [-c "component name"] 
[-p "alert policy"] [--version component-version]
[--env "environment name"] [--entrypoint-libc "musl"|"glibc" ]
[--disable-stack-traces] [--enable-method-tracing]
--docker-run [docker run CLI arguments] --image [command arguments]

Command to register application in portal :

dfctl register 
[-v] [-f] -a "application name" [-c "component name"] 
[-p "alert policy"] [--version component-version]
[--env "environment name"] [-n "image name"] [-i "image id"]
[--disable-stack-traces] [--enable-method-tracing] [-o output]

-a or --application (required) specify the name of your application. If an application with this name does not already exist on your Deepfactor Portal, it will be created.

-c or --component (optional) specify the component name. Default is the image name without tag.
--version (optional) specify the version of the component you are currently running. You can filter insights based on this version number. If not specified, the md5sum or the image Tag will be used. If an image has no tag, then the image Id will be used.
-p or --policy (optional) specify the alert policy for this component. This policy will be used to raise alerts for all active and future instances of this component.
--cmd (required) specify the full command along with arguments you use to launch your component. Please note this should be the last argument of dfctl run command.

--docker-run (required) If you are running a docker container, please specify the full docker run command along with the arguments you use to run your container. Please note this should be the last argument of dfctl run command.

Other options

-v (optional) can be used to run the tool in verbose mode.
-l or --lang (deprecated) Deepfactor can enhance alerts by enabling language-specific probes. If you are running a java component, please add -l "java" option to dfctl run command. For other programming languages, there is no need to add this option.
-E or --env (optional) specify the environment in which you are running your component (Ex. staging, qa etc.). You can filter insights based on the environment you specify.
Hybrid libc environments

--fail-safe or -f (optional) - In case the application cannot be instrumented by dfctl, the application deployment is not affected. An uninstrumented application is deployed, its entry is displayed in the portal. However no additional data related to application can be seen on UI (Alerts, Vulnerabilities, etc)

--entrypoint-libc (optional) "musl"|"glibc" - For containerized workloads, if the libc required by the entrypoint does not match the OS distribution libc then it can be specified with this option. You can read more about this option in the below article

Hybrid libc environments

--disable-stack-traces (optional) - Stack traces are enabled by default, this option is to disable stack traces. You can read more about this option in the below article
Language Specific Agents (LSA)

Note: Applications could see a performance impact when run with Deepfactor since stack traces are enabled by default.

--enable-method-tracing (optional) -This can be used to enhance application alerts by enabling language specific function or method tracing. You can read more about this option in the below article
Language Specific Agents (LSA)

Note: All dfctl arguments must be specified before --cmd on the command line. The argument specified with --cmd must be executable name followed by the list of arguments with which the executable must be launched.

Scanning your artifacts with dfctl

The Deepfactor CLI tool can scan your artifacts (container images / filesystem directories) to generate SBOM and find SCA vulnerabilities using the scan verb. Deepfactor can automatically correlate the results of scans performed against artifacts and running workloads. This correlation is shown on the portal UI at multiple screens in order to give the user an unified view of their application's security posture.

Scanning container images

dfctl scan [-s image] 
[-u timeout] [-h "agent-name"] [-g "agent-type"]                                    
[-p "SCA & SBOM alert policy"] [-f "format"] [-O "output file path"]                          
<Image path with repo and tag to be scanned>

Scanning filesystem directory

dfctl scan -s fs -a "application name" -c "component-name" -V "component-version"
[-u timeout] [-h "agent-name"] [-g "agent-type"]
[-p "alert policy"] [-f "format"] [-O "output file path"] 
<filesystem path to scan (can be relative)>

-a (required) is used to specify the application name. The artifact name will be applicationName:componentName
-c (required) is used to specify the component name. The artifact name will be applicationName:componentName
-V (required) is used to specify the component version.

Please provide the same application name, component name and version while running your non-containerized workload with Deepfactor. Deepfactor will then correlate the results of the static scan with the results found by observing the running application.

You can use the following options to configure the filesystem scan:

where:

-s (optional) is used to specify the scan type, namely image or fs (filesystem). By default, the value is image. Please pass -s fs to dfctl scan command for filesystem scans.

-u (optional) is used to set the scan timeout value. The default value of the timeout is 15min.
-h (optional) is used to specify the agent name, which tracks meta information of the host from where the scan is being triggered. By default, hostname and IP are used to tag the agent.

-g (optional) is used to specify the agent type, which serves as a category for a subset of agents. Ex. CI/CD pipeline

-p (optional) is used to specify the SCA & SBOM alert policy. The rules configured in the policy are used for identifying violation in the static scan SCA (vulnerability)/SBOM (application dependency) information and, in turn, generate alerts. The alert policy can also be set from the DF portal. If no policy is set, the default policy will be used.
-f (optional) is used to specify the report formats. Allowed values are table, json, cyclonedx, spdx, spdx-json. The default value is the table.

-O (optional) Specify a file name to capture the output. If no option is specified, the output is displayed on the terminal.

Design

The host running dfctl and docker cli may run any supported Linux distribution (Ubuntu, Centos, etc.) and the deployed image could be of yet another supported distro and version. For example, we may have docker host running on Ubuntu while the deployed image could be Alpine.

To instrument an Alpine image from an Ubuntu or Centos based host, we will package glibc as well as muslc flavors of libdf.so in the Deepfactor-runtime package. This will be done only for rpm and deb packages. Hence, while installing the Deepfactor-runtime package on Ubuntu or Centos host, we will have libdf.so for rpm, deb or Alpine-based containers.

DFctl Run when invoked with --docker-run option will have to fingerprint the image being run to find the distro. Based on this, dfctl will copy glibc or muslc flavor of libdf.so into a directory that will be mounted into the container during launch. During this process, dfctl will call the register component API to generate a manifest file. Path to this file will be used to set DF_MANIFEST environment variable while running the container image.

Container

In addition to the above technique to use to "dfctl run ... --docker-run", you can add Deepfactor to a container image or by using the Deepfactor mutating webhook. Please see the following articles.

Miscellaneous

Display the current version of dfctl :

dfctl version

Display the list of policies :

dfctl policy list