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://deepfactorstg.wpengine.com/doc/deploying-deepfactor-on-aws-using-cft/
  • Deploy Deepfactor on VMWare ESXi – https://deepfactorstg.wpengine.com/doc/deploying-deepfactor-on-aws-using-cft/
• 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: