GitLab

Deepfactor integrates with GitLab pipelines to automate the runtime detection of application vulnerabilities when conducting integration testing.

The following prerequisites are required to integrate Deepfactor and GitLab:

• Deepfactor Portal set up:

  • Deploy Deepfactor on AWS - https://docs.deepfactor.io/hc/en-us/articles/360052479194-On-AWS-using-CloudFormation-Template

  • Deploy Deepfactor on VMWare ESXi - https://docs.deepfactor.io/hc/en-us/articles/360052676033-On-VMware-ESXi

• A valid Deepfactor API Token (DF_API_KEY)

• A valid Deepfactor Run Token (DF_RUN_TOKEN)

  • The DF_RUN_TOKEN can be retrieved by logging into the Deepfactor portal and clicking on the “Run with Deepfactor” button on your home screen.

Integration Instructions

First, edit your .gitlab-ci.yml pipeline to run your tests or deployment with Deepfactor. To provide this functionality for your pipeline, use the template from dfctl (Deepfactor Command Line Tool).

To get started, download the deepfactor.gitlab-ci.yml file from http://ci-assets.deepfactor.io/gitlab/deepfactor.gitlab-ci.yml. This file should be checked into your repository along with the .gitlab-ci.yml file.

Next, include the deepfactor.gitlab-ci.yml in your .gitlab-ci.yml:

include:
- local: deepfactor.gitlab-ci.yml

Add the DF_API_KEY and the DF_RUN_TOKEN to the project CI/CD variables as shown below.

Configuring a Deepfactor Job

All Deepfactor Jobs requires the following variables to be set at the pipeline level:

variables:
  DF_APP: "my-app-name" # the application name used in DeepFactor
  DF_COMPONENT: $CI_PROJECT_NAME # the component name can be the project name 
  DF_VERSION: $CI_PIPELINE_IID # the component version 
  DF_PORTAL_HOST: "your.deepfactorportal.io" #Host name of your DeepFactor deployment

Running a Test Job

Use the following sample Job code to run a test job.

test:
  stage: test
  services:
   - mongo
script:
  - npm install
  - npm run test
artifacts:
  paths:
   - ./src/test-results.xml

The above test Job can also be updated to be run with dfctl as follows:

test:
  stage: test
  services:
   - mongo
before_script:
   - !reference [.install_dfctl,script] # this script installs the dfctl cli
script:
   - npm install
   - dfctl run -a $DF_APP -c $DF_COMPONENT --version $DF_VERSION --cmd npm run test
artifacts:
   paths:
    - ./src/test-results.xml

Running a DAST Scan

It is assumed that as part of your CI/CD pipeline your application would be deployed to a testing/staging environment on which Active Scans will be performed.

Use the following Variables for DAST scans:

# Variables
#   DF_APP - The name of the application in DeepFactor
#   DF_COMPONENT - The name of component in DeepFactor
#   DF_VERSION - The component version
#   DF_SCAN_URL - The application web endpoint to run the DAST Scan against
#   DF_SCAN_TYPE - The scan type to use. Valid values are "web" or "api"
#   DF_SCAN_STRENGTH - The strength of the scan. Valid values are "Low","Medium" and "High"
#   DF_SCAN_API_DOCS_PATH - The relative path of the swagger or openapi document. Required for API Scan
#   DF_SCAN_AUTH_TYPE - The authentication mechanism to use for the scan. Valid values are "none", "form", "custom"
#
# for DF_SCAN_AUTH_TYPE="form" the following variables are required
#   DF_SCAN_AUTH_FORM_LOGIN_URI - The relative path of the login page
#   DF_SCAN_AUTH_FORM_USERNAME - The username to use to authenticate ( store as Project CI/CD Variable )
#   DF_SCAN_AUTH_FORM_PASSWORD - The password to use to authenticate ( store as Project CI/CD Variable )
#   DF_SCAN_AUTH_FORM_DATA - The post data for the login eg. username={%username%}&password={%password%}
#   DF_SCAN_AUTH_FORM_LOGGEDIN - The LoggedIn indicator html eg. <a href=&quot;logout.jsp&quot;>Logout</a>
#   DF_SCAN_AUTH_FORM_LOGGEDOUT - The LoggedOut indicator html eg. <a href=&quot;login.jsp&quot;>Login</a>
#
# for DF_SCAN_AUTH_TYPE="custom" the following variables are required
#     DF_SCAN_AUTH_CUSTOM_TOKEN - This token will be sent in Authorization header of each request made by the scanner. Please note, you may need to add Bearer before the token if you are using JWT.

Use the following to initiate a DAST Job:

deepfactor-web-scan:
   stage: deepfactor-web-scan
   extends: .deepfactor_webscan

Generating Deepfactor Reports

To generate Deepfactor alert reports after running tests and/or running a DAST Scan, use the following Job Variables:

# Variables for the deepfactor-report job
#   DF_APP - The name of the application in DeepFactor
#   DF_COMPONENT - The name of component in DeepFactor
#   DF_VERSION - The component version

To initiate a Report Job use the following:

deepfactor-report:
 stage: report
 when: delayed
 start_in: 30 minutes # arrive at this value after considering how long the webscan takes to complete in DeepFactor
 extends:
  - .deepfactor_report

Deepfactor Report Artifacts

After the Deepfactor reporting Job finishes, reports are generated as artifacts under the “reports/” folder.

Click on index.html to view the list of issues that Deepfactor detected and follow the links in the report to view the details in the Deepfactor portal.

GitLab Ultimate Edition - Security Dashboard

If you have the GitLab Ultimate Edition, then the DAST and Vulnerable Dependencies detected by Deepfactor are available to triage within the GitLab Security & Compliance Dashboard as follows: