• Product

      Product

      Application Security Platform

      Use Cases

      Shift Left & DevSecOps Supply Chain Security Software Bill of Materials (SBOM) Container Runtime Security & Compliance Cloud Native Application Security
      What is Deepfactor and How Does It Work?
      4-Minute Video
      What is Deepfactor and How Does It Work? >
  • Pricing
    • Pricing Plans
  • Resources

      Resources

      All Resources Next-Gen AppSec Series Case Studies Demos Videos Glossary Webinars Whitepapers Workshops Latest Blogs Documentation
      Next-Gen AppSec Series—Deepfactor SCA: 80% Less Noise, 50% Lower Cost
      Next-Gen AppSec Series
      Next-Gen AppSec Series—Deepfactor SCA: 80% Less Noise, 50% Lower Cost >
  • Company
    • About
    • Leadership
    • Partners
    • News and Events
    • Careers
    • Contact Us
  • LOGIN
Cisco Logo Deepfactor is now part of Cisco | Learn more
Learn more
Deepfactor Logo
  • Product

      Product

      Use Cases

      Application Security Platform

      Use Cases

      Shift Left & DevSecOps Supply Chain Security Software Bill of Materials (SBOM) Container Runtime Security & Compliance Cloud Native Application Security
      What is Deepfactor and How Does It Work?
      4-Minute Video
      What is Deepfactor and How Does It Work? >
  • Pricing
    • Pricing Plans
  • Resources

      Resources

      All Resources Next-Gen AppSec Series Case Studies Demos Videos Glossary
      Webinars Whitepapers Workshops Latest Blogs Documentation
      Next-Gen AppSec Series—Deepfactor SCA: 80% Less Noise, 50% Lower Cost
      Next-Gen AppSec Series
      Next-Gen AppSec Series—Deepfactor SCA: 80% Less Noise, 50% Lower Cost >
  • Company
    • About
    • Leadership
    • Partners
    • News and Events
    • Careers
    • Contact Us
LOGIN
Deepfactor's Application Security Platform will no longer be offered for sale or renewal effective September 20, 2024.

Getting Started

  • QuickStart Guide
  • Install Deepfactor CLI
  • Deepfactor Support Matrix

Tutorials

  • SBOM & SCA
    • Artifact Releases
    • Deepfactor Scanner
    • Integrate Deepfactor scanner in your CI/CD pipelines
    • Scanning container images from private registries using Deepfactor CLI
    • Scan container images in K8s cluster
      • Scanning images from private registries in K8s cluster using Deepfactor
      • Scanning container images from private registries with basic authentication support in K8s
      • Scanning container images from private AWS Elastic Container Registry (ECR) in EKS on AWS Fargate
      • Scanning container images from private AWS Elastic Container Registry (ECR) in EKS on AWS EC2
  • Runtime Security
    • Introduction to Deepfactor Runtime Security
    • Deepfactor CLI Reference
    • Kubernetes workload
      • Run your Kubernetes workload with Deepfactor
      • Install Deepfactor Mutating Webhook
      • Configure Deepfactor Kubernetes admission webhook
      • Install Deepfactor K8s webhook on EKS Fargate
      • Selecting the pods you want to run with Deepfactor
      • Configuring application name, component name and component version in K8s webhook
      • Install Deepfactor mutating admission webhook using Argo CD
      • Install Deepfactor portal & webhook using Argo CD and vault
      • Use image pull secret for Runtime images
    • Containers/Other orchestration platforms
      • Run your Container Images with Deepfactor
      • Run containers in ECS with Deepfactor
    • Non-containerized workloads
      • Running non-containerized applications with Deepfactor

Deepfactor Platform

  • Introduction to Deepfactor
  • Alert Policies
  • Alert States and Triaging Flows
  • Deepfactor’s Correlation Capabilities
  • Organization and Teams
  • Role Based Access Control
  • Insights Knowledge Base
    • Privilege Separation and Privilege Dropping
    • Buffer Overflow Alerts
  • Knowledge Base
    • Deepfactor scan errors
    • K8s Webhook & Runtime Troubleshooting Guide
    • Tools for viewing CycloneDX and SPDX SBOMs
    • Graceful handling of pod restarts
    • Deepfactor telemetry events
    • Deepfactor Instrumentation Warning Messages
    • Best Practices for running your applications with Deepfactor in production environments
    • Golang Specific Notes
    • How to access Deepfactor Portal in different AWS subnet types
    • How the Deepfactor Management Portal Communicates With The Outside World
    • Language Specific Agents (LSA)
    • Mixed libc environments
    • Sensitive Information and Secrets in Process Environment Remediation
    • Running HAProxy with Deepfactor
    • Augmenting Alert Evidence with Runtime Stack Traces
  • FAQs
    • General FAQs
    • Open Source Disclosure

Integrations

  • Single Sign On (SSO) for authentication to Deepfactor
  • Integrate Jira with Deepfactor
  • Integrate Slack with Deepfactor
  • Okta
  • Deepfactor HTTPS webhook

Self managed Deepfactor portal

  • Deepfactor Portal architecture & deployment options
  • Install Self managed Deepfactor portal
    • Kubernetes Cluster
      • Prerequisites for deploying Deepfactor portal in Kubernetes Cluster
      • Deploying Deepfactor Portal in your Kubernetes Cluster
      • Install Deepfactor portal using Helm
      • Customizing Deepfactor portal deployment
        • Customizing your Deepfactor Portal Deployment in K8s
        • Deploy Deepfactor Portal With Resource Limits
        • Deploying Deepfactor Portal using external IP
        • Deepfactor Portal Installation with Existing Ingress Controller
    • AWS EC2
      • Prerequisites for installing Deepfactor Portal in AWS Cloud
      • Deploying Deepfactor on AWS using CFT
      • Install AWS Certificate Manager(ACM) certificate on Deepfactor portal EC2 instance
    • VMWare vSphere
      • Deepfactor Portal Proxy Configuration for OVA deployments
      • Prerequisites for deploying Deepfactor portal in VWware vSphere
      • Deploying Deepfactor on VMware vSphere
  • Manage Deepfactor Portal
    • Using Deepfactor APIs
    • Managing Users
    • Updating your Deepfactor Portal
    • Updating Deepfactor portal certificate
  • Deepfactor Portal Certificate
    • Generate certificate using cert-manager for Deepfactor portal
    • Create self-signed certificate for Deepfactor Portal on your K8s cluster
    • Create AWS Private CA Certificate for Deepfactor Portal on your K8s cluster
    • Create Let’s Encrypt certificate for Deepfactor Portal on your K8s cluster

Release Notes

  • Deepfactor Release Notes
  • Home
  • Docs
  • Tutorials
  • Runtime Security

Deepfactor CLI Reference

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.

  • Run your Container Images with Deepfactor
  • Run your Kubernetes workload with Deepfactor

 

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

 

 

Was this article helpful?
Still stuck? How can we help?

How can we help?

Updated on February 2, 2024
Introduction to Deepfactor Runtime Security

Powered by BetterDocs

Table of Contents
  • DF CLI Docker Init
  • App Launcher
  • Scanning your artifacts with dfctl
  • Design
  • Container
  • System Service
  • Miscellaneous
Deepfactor Icon

Deepfactor is a next-gen application security platform, using static container scan data + runtime analysis to prioritize vulnerabilities to those representing true risk to a business—based on reachability, runtime usage, deployment context, and exploit maturity.

Product Pricing Resources Company Documentation Login

SUBSCRIBE TO OUR NEWSLETTER!

Sign Up
LinkedIn Icon YouTube Icon GitHub Icon Twitter Icon

© 2025 Deepfactor, Inc. All Rights Reserved.

Privacy Statement | Terms of Service | Open Source Disclosure