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. 

 

j1.png

 

Next, click on Manage Plugins.

 

j2.png

Navigate to the Advanced Tab.

j3.png

 

Scroll down to Upload Plugin.

 

j4.png

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

j5.png

 

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.

 

image__2_.png

 

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.

 

j7.png

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

j8.png

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

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

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.

j9.png

 

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

A 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. The 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 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.

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. The default (Blank) value is assumed to be 'Default.'

Delay to fetch report (minutes)

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

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.