Jenkins

Overview

A test can be performed externally by authenticating a StrikeOne Admin account from Jenkins and then calling the test orchestrator endpoint with the appropiate parameters. The following example stage lets users execute tests from Jenkins, and only complete the stage if the test has been completed or not.

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, parsedScanId and tool. Both parsed IDs can be obtained directly by going to the Domains or the Scans tab of an asset and copying it from any table element.

The following values are valid for the tool field:

• openvas
• owasp_zap
• dep_check
• nuclei
• gitleaks

IMPORTANT

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

• OWASP Dependency Check (dep_check) and GitLeaks (gitleaks) 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's ID that's returned when the test is executed to check its status. In the provided example, the test's status is retrieved every 60 seconds, and the stage either completes, or fails.

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',
                        parsedScanId: '192079369',
                        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)

            }

        }
}