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"] [--disable-stack-traces] [--disable-usage-tracking] --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"] [--disable-stack-traces] [--disable-usage-tracking] --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] [--disable-usage-tracking] [-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.
–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)
–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.
–disable-usage-tracking (optional) – Deepfactor automatically intercepts class loaded events for java applications. You can disable this intercept by passing this option.
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 a container image
dfctl scan [-v] [-s image] [-u timeout] [-h "agent-name"] [-G "scan-trigger-source"] [-R "release-tag"] [-p "SCA & SBOM alert policy"] [-f "format"] [-O "output file path"] <Image path with repo and tag to be scanned>
Scanning a filesystem directory
dfctl scan -s fs -a "application name" -c "component-name" -V "component-version" [-v] [-u timeout] [-h "agent-name"] [-G "scan-trigger-source"] [-R "release-tag"] [-p "alert policy"] [-f "format"] [-O "output file path"] [-X exit-code] [-L failure-exit-code] [-G "scan-trigger-source"] ["--include-dev-dependencies"] <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 optional 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 source from which the scan is triggered. 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. You can specify a comma separated list of format types if you would like to export more than one output report. Allowed values are table, json, cyclonedx, spdx, spdx-json. The default value is the table.
-O (optional) Specify a file name if you would like the results to be stored on disk. Multiple files maybe created if multiple formats are requested. If no option is specified, the output is displayed on the terminal.
–v (optional) can be used to run the scan in verbose mode.
-X or –exit-code (optional) is used to specify the exit code the dfctl scan command will return when there is at least one policy rule violation. It is set to 0 by default. If you would like to gate builds based on policy rule violation, please set it to a non-zero value (from 1 to 255)
-L or –failure-exit-code (optional) is used to specify the exit code the dfctl scan command will return when the scan fails. It is set to 1 by default. You can set it to 0 if you want to ignore scan fail errors.
-R (optional) is used to specify the name of the release to which this build belongs. Deepfactor will show the trend of vulnerabilities within a release and across releases. The release name is generally derived from the name of the branch of git tag depending upon your branching strategy.
–include-dev-dependencies (optional) is used to include dev dependencies for node.js (package-lock.json and yarn.lock) and PHP (composer-lock.json) in the scan output. Please note, by default, Deepfactor filters out dev dependencies as they are generally not bundled into the artifact that runs in production and cause false positives/SBOM bloat.
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 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.
System Service #
dfctl service register [-v] [-f] -a "application name" -c "component name" [-p "alert policy"] [--version component-version] [--env "environment name"] [-r] service
The command service register is primarily used for adding DF instrumentation to system service. This command modifies the service control file, sets the environment required to run the service with DF instrumentation, and restarts / starts the service is -r flag is specified.
–application or -a (required) is used to specify the application name
–component or -c (optional) is used to specify the component name.
–version (optional) can be used to register the app with a specific version string.
-v (optional) can be used to run the tool in verbose mode.
-l (optional) is used to specify the programming language of the component. It is used for multiple purposes including injecting Deepfactor’s language-specific agent into the DF instrumented component. For example, setting -l “java” will enable the collection of java specific metrics including java stack trace frames.
-p (optional) is used to specify the alert policy to be set for the DF instrumented component. The alert policy can also be set from the DF portal.
–env or -E (optional) is used to specify the deployment environment name.
-r can be used to start/restart the service with DF instrumentation.
–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 the application can be seen on UI (Alerts, Vulnerabilities, etc)
dfctl service deregister [-v] [-r] service
The command service deregister is to remove DF instrumentation for service and restore the service control file to its original state.
-v (optional) can be used to run the tool in verbose mode.
-r (optional) can be used to start/restart the service with DF instrumentation.
dfctl service list
The command service list is to list all the services that are DF instrumentation enables.
Miscellaneous #
Display the current version of dfctl :
dfctl version
Display the list of policies :
dfctl policy list