Jenkins Follow

 

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 https://docs.deepfactor.io/hc/en-us/articles/1500005374742 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 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.

 

Freestyle	Pipeline
DeepFactor Build Image	deepfactor
DeepFactor DAST Scan	dfDASTscan
DeepFactor Report	dfreport

 

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.

 

Parameter name	Type	Description
alpine	Boolean	Set to true if your application image is based on Alpine, false otherwise.
pullImage	Boolean	Set to true if DeepFactor should pull the latest image of your application (similar to --pull of docker build command).
imageToBeInstrumented	String	Application’s docker image name.
appName	String	Application name to be mapped/created in the DeepFactor portal.
componentName	String	Component name to be mapped/created in the DeepFactor portal.
componentVersion	String	Version of this component to reflect in the DeepFactor portal.
instrumentedImageName	String	Output DeepFactor instrumented Docker image name.

Sample Pipeline

pipeline {
    // agent any
    // or an agent node
    agent { label 'myjenkinsagent' }
    stages {
        stage("DeepFactor Docker Build") {
            steps {
                deepfactor alpine: true,
                    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)

Parameter name	Type	Description
appName	String	Application name as in DeepFactor portal.
componentName	String	Component name as in DeepFactor portal.
webservicePort	Integer	Port number on which the web service is running.
envName	String	[Optional] Environment under which the component is running. Default value is assumed to be 'Default'.
scanConfigName	String	In DeepFactor Portal, various parameters for a scan could be saved as a configuration with a name. The same could be used in subsequent scans or in this command. Please refer to https://docs.deepfactor.io/hc/en-us/articles/360052013714-Starting-a-DAST-Scan to learn how to save the scan configuration.

 

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 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

 

Parameter name	Type	Description
appName	String	Application name as in DeepFactor portal.
componentName	String	Component name as in DeepFactor portal.
envName	String	[Optional] Environment under which the component is running. Default value is assumed to be 'Default'.
delay	Integer	Number of minutes to wait before fetching the alerts to report. If you are triggering this step immediately after the scan completion, it is recommended to configure a value above 5 (minutes) for the alerts to be captured by the system for reporting. If you are handling the delay elsewhere or you are generating the report for a scan that ran earlier, this value could be 0 (zero).

 

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.

 

Parameter name	Description
Name of the image to be instrumented	Application’s Docker image name.
Alpine Image	Check this box if your application image is based on Alpine.
Pull image (--pull)	Check this box if DeepFactor should pull latest image of your application (similar to --pull of docker build command).
DeepFactor App Name	Application name to be mapped/created in DeepFactor portal.
DeepFactor Component Name	Component name to be mapped/created in DeepFactor portal.
DeepFactor Component Version	Version of this component to reflect in DeepFactor portal.
Instrumented image name	Output DeepFactor instrumented docker image name.

 

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.

Parameter name	Description
Application Name	Application name as in DeepFactor portal.
Component Name	Component name as in DeepFactor portal.
Webservice Port	Port number on which the web service is running.
Environment Name	[Optional] Environment under which the component is running. Blank (Default) value is assumed to be 'Default'.
Scan Config Name	In DeepFactor Portal, various parameters for a scan could be saved as a configuration with a name. The same could be used in subsequent scans or in this command. Please refer https://docs.deepfactor.io/hc/en-us/articles/360052013714-Starting-a-DAST-Scan to know how to save the scan configuration.

 

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

 

DeepFactor Report

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

 

Parameter name	Description
Application Name	Application name as in DeepFactor portal.
Component Name	Component name as in DeepFactor portal.
Environment Name	[Optional] Environment under which the component is running. Default (Blank) value is assumed to be 'Default'.
Delay to fetch report (minutes)	Number of minutes to wait before fetching the alerts to report. If you are triggering this step immediately after the scan completion, it is recommended to configure a value above 5 (minutes) for the alerts to be captured by the system for reporting. If you are handling the delay elsewhere or you are generating the report for a scan that ran earlier, this value could be 0 (zero).

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.