Jenkins

Deepfactor integrates with Jenkins using a Jenkins plugin. This provides a simple mechanism to automatically instrument your applications using Deepfactor as part of the build process.

From your Jenkins portal, follow the instructions below to integrate Jenkins and Deepfactor and automatically instrument your applications.

First, download the Deepfactor Jenkins plugin installer available here to your local drive. Then go to your Jenkins home page Dashboard and click on Manage Jenkins. 

Next, click on Manage Plugins.

Navigate to the Advanced Tab.

Scroll down to Upload Plugin.

Choose deepfactor-plugin.hpi from your local drive and select Upload. Wait for the file to be uploaded and installed.

You can optionally restart Jenkins (recommended if you are reinstalling the plugin) or verify the plugin installation by clicking on Manage Plugins by going to Dashboard → Manage Jenkins → Manage Plugins and selecting the Installed tab.

Note: the version number may vary (from the above screenshot) based on what version you have installed.

Deepfactor Configuration #

To configure Deepfactor, you must configure the global parameters. To do this, go to Manage Jenkins and Click on Configure System.

Next, Scroll down to Deepfactor Configuration and fill in the following parameters:

• • Admin Portal URL – Your Deepfactor portal URL.
  • Verify Portal Certificate – Deepfactor portal uses a self-signed certificate by default. If you have configured a custom SSL certificate on your portal and want this plugin to verify the certificate presented by Deepfactor portal APIs, you can enable this option.

• • Deepfactor API Token – Please refer to Managing Deepfactor API Tokens to learn how to obtain the token from your Deepfactor portal.

• Deepfactor Run Token – This can be obtained from your Deepfactor portal by going to the Home/Applications page → Run With Deepfactor (Top-right corner) → Docker (left pane) → Step 2 → Copy only the token from export DF_RUN_TOKEN=token and paste here:

Finally, save the configuration.

Deepfactor Build Steps #

The Deepfactor Jenkins plugin supports the following build steps. You can use the same steps in Jenkins Freestyle or Pipeline projects.

Pipeline Usage #

deepfactor #

This build step will enable you to add Deepfactor to your Docker image.

Prerequisite: Ensure you have docker installed on the Jenkins agent where you are running this build step.

Please refer to https://www.jenkins.io/doc/book/using/using-agents/ to learn about running your jobs using Jenkins agents.

Please refer to https://docs.docker.com/engine/install/ to learn how to install Docker engine in your environment.

Build step command: deepfactor.

Sample Pipeline

pipeline {
      // agent any
      // or an agent node
      agent { label 'myjenkinsagent' }
      stages {
          stage("DeepFactor Docker Build") {
              steps {
                  deepfactor pullImage: true,
                      imageToBeInstrumented: 'swaggerapi/petstore3',
                      appName: 'My Application',
                      componentName: 'petstore',
                      componentVersion: '1.0.0',
                      instrumentedImageName:'petstore3-df'
              }
          }
      }
  }

Upon successful execution of this step, you will have the instrumented image on your Jenkins agent node. You can also use the same in your subsequent build steps.

dfDASTScan #

This build step will enable you to trigger a Deepfactor enabled DAST scan on an active web service running on your application.

Build step command: dfDASTscan (case sensitive)

Sample Pipeline

pipeline {
      // agent any
      // or an agent node
      agent { label 'myjenkinsagent' }
      stages {
          stage("DeepFactor DAST Scan") {
              steps {
                  dfDASTscan appName: 'My Application',
                      componentName: 'petstore',
                      webservicePort: 8069,
                      envName: 'PreProd',
                      scanConfigName: 'jenkinsscan'
              }
          }
      }
  }

Upon successful execution of this step, the DAST scan will start and its status reported every minute in the console log. The job will end only when the scan is completed, irrespective of the successful or unsuccessful outcome. You can verify the scan status on your Deepfactor portal as well.

dfreport #

This build step will enable you to generate an HTML alerts report from a component.

Build step command: dfreport

Sample Pipeline

pipeline {
      //agent any
      // or an agent node
      agent { label 'myjenkinsagent' }
      stages {
          stage("DeepFactor Report"){
              steps{
                  dfreport appName: 'My Application',
                      componentName: 'petstore',
                      envName: 'PreProd',
                      delay: 6
              }
          }
      }
  }

Upon successful completion of this step, the Deepfactor report will be available at dfreports/dfreport.html under the job’s workspace. Due to the security restrictions in Jenkins, opening the link directly may show an unformatted report. To view a formatted report, we recommend that you save the report locally and then open it in a browser.

Freestyle Projects #

Once the plugin installation is complete, in any of the Freestyle project configurations, you will see the following new Deepfactor build steps, along with other existing build steps.

Deepfactor Build Image #

This build step will enable you to add Deepfactor to your docker image.

Prerequisite: Ensure you have docker installed on the Jenkins node where you are running this build step.

Upon successful execution of this step, you will have the instrumented image on your Jenkins agent node. You can use the same in your subsequent build steps.

Deepfactor DAST Scan #

This build step will enable you to trigger a Deepfactor enabled DAST scan on an active web service running on your application.

Upon successful execution of this step, the DAST scan will start, and the status reported every minute in the console log. The job will end only when the scan is completed, irrespective of the successful or unsuccessful outcome. You can verify the scan status on the Deepfactor portal as well.

Deepfactor Report #

This build step will enable you to generate an HTML report of alerts from a component.

Upon successful completion of this step, the Deepfactor report will be available at dfreports/dfreport.html under the job’s workspace.

Due to Jenkins security restrictions, opening the link directly may show an unformatted report. To view a formatted report, save the report locally, and open it in a browser.