StrikeOne Docs

Jenkins

Overview

A test can be performed externally by authenticating a StrikeOne Admin account from your preferred CI/CD application.

Remote Test Execution

Overview

In order to execute a test, you will need to have an authorization token. Users can generate API Tokens from the Integrations menu in the StrikeOne settings. The authorization token will allow users to perform any subsequent calls to other endpoints.

After obtaining our authorization token, the test orchestrator must be called. This POST request requires a body with an externalData object containing the fields testName, parsedDomainId and tool. Parsed domain IDs can be obtained directly by going to the Domains tab of an asset and copying it from any table element.

The following values are valid for the tool field:

  • openvas
  • owasp_zap
  • sonarqube
  • dep_check
  • nuclei
  • gitleaks
  • horusec

IMPORTANT

Some tools require or accept extra arguments for their execution. The list is as follows:

  • SonarQube (sonarqube), OWASP Dependency Check (dep_check), GitLeaks (gitleaks) and Horusec (horusec) require an additional toolData object to be included alongside externalData. This object will contain the projectUrl field (the repo URL, including its credentials if required), projectName (the repository's name) and projectBranch (the branch to clone, optional if using curl).

  • Nuclei (nuclei) accepts an additional toolData object to be included alongside externalData. This object may contain the templates field which is a string including the templates to use by Nuclei. This field is concatenated to a string including the -nts flag to be later used when running Nuclei.

If the test was successfully created, /api/vm/tests/external/execute will return a 200 code. If you wish to ensure that the stage only completes (or fails) depending on the test's final status you can make an additional call to /api/vm/tests/external/status/:testId using the Test ID that's returned when the test is executed to check its status.

Jenkins

Requirements

The stage example below requires the httpRequest plugin to be installed on Jenkins. Additionally, jsonSlurperClassic will need to be authorized before running the script.

Stage Example for Scripted Pipeline

import groovy.json.JsonSlurperClassic

node {

    env.NODEJS_HOME = "${tool 'nodejs_14.18.0'}"
    env.PATH = "${env.NODEJS_HOME}/bin:${env.PATH}"

    environment {
        SO_CREDENTIALS = credentials('so_api_token')
    }

    stage('Clean Workspace') {
        cleanWs()
    }

    stage('SCM') {
        checkout scm
    }

    stage('StrikeOne Admin Analysis') {
            withCredentials([string(credentialsId: 'so_api_token', variable: 'SO_API_TOKEN')]) {

                def toJson = {
                    input ->
                    groovy.json.JsonOutput.toJson(input)
                }

                def testBody = [
                    externalData: [
                        testName: 'Jenkins Test',
                        parsedDomainId: '192079240',
                        tool: 'owasp_zap'
                    ]
                ]

                // EXECUTE VM TEST
                def testRes = httpRequest contentType: 'APPLICATION_JSON', httpMode: 'POST', requestBody: toJson(testBody), customHeaders: [[name:'Authorization', value: "Bearer $SO_API_TOKEN"]], url: 'https://assessment.strikeone.io/api/vm/tests/external/execute'
                def testJson = new JsonSlurperClassic().parseText(testRes.content)
                def testId = testJson.payload.testId

                def maximumChecks = 30

                def checkTestStatus = {
                    String test ->

                    if (maximumChecks > 30) {
                        echo "StrikeOne Vulnerability Management test took too long to complete."
                        return true
                    }

                    sleep 60

                    def statusRes = httpRequest httpMode: 'GET', customHeaders: [[name:'Authorization', value: "Bearer ${SO_API_TOKEN}"]], url: "https://assessment.strikeone.io/api/vm/tests/external/status/${test}"
                    def statusJson = new JsonSlurperClassic().parseText(statusRes.content)
                    if (statusJson.payload.status == 'done') {
                        echo "StrikeOne Vulnerability Management test completed."
                        return true
                    }

                    if (statusJson.payload.status == 'failed') {
                        error "StrikeOne Vulnerability Management test failed."
                    }

                    maximumChecks++

                    checkTestStatus(test)
                }

                checkTestStatus(testId)

            }

        }
}

GitHub Actions

Requirements

The workflow example uses HTTP Request Action.

Job Example

  execute_so_test:
    name: Execute StrikeOne Test
    runs-on: self-hosted

    steps:
      - name: StrikeOne Test Execution
        id: strikeone_test_execution
        uses: fjogeleit/http-request-action@v1
        with:
          url: "https://assessment.strikeone.io/api/vm/tests/external/execute"
          method: "POST"
          customHeaders: '{"Content-Type": "application/json"}'
          bearerToken: ${{ secrets.SO_API_TOKEN }}
          data: '{"externalData": { "parsedDomainId": "192079240", "tool": "owasp_zap", "testName": "GitHub Actions Test" } }'
      - name: Show Response
        run: |
          echo ${{ steps.strikeone_test_execution.outputs.response }}

GitLab CI/CD

Requirements

None.

Job Example

strikeone-test:
  stage: test
  script:
    - echo "Execute StrikeOne Test"
    - RES=$(curl --request POST https://assessment.strikeone.io/api/vm/tests/external/execute --header "Content-Type:application/json" --header "Authorization:Bearer ${SO_API_TOKEN}" --data-raw '{"externalData":{"testName":"GitLab Test","parsedDomainId":"192079240","tool":"owasp_zap"}}')
    - echo RES is $RES
Last Updated: