neuvector-vulnerability-scanner-plugin

NeuVector Vulnerability Scanner Jenkins Plugin

• NeuVector Vulnerability Scanner Jenkins Plugin
• Description
• Notes
• Requirements
• Setup the configuration in Jenkins
  • Controller \& Scanner
  • Standalone
  • How to set up in build setp / pipeline
• Setup K8s plugin in Jenkins
  • Set up the k8s machine in jenkins server
  • Pipeline example to run K8s agent mode
• Setup Pipeline to build large scale parallel scan
  • Use Token mode (2.4- or 2.5+ with token mode)
  • Use API Key mode (2.5+ api key mode)

Description

This is a Jenkins Plugin to do security vulnerabilities scanning on registries and local images with the NeuVector Scanner.

Notes

• It supports two scan modes. By default, it uses the Controller & Scanner mode.
  • Standalone mode, run the service inside the docker images
  • Controller & Scanner mode, run the service inside external controller
• Support running jenkins pod with K8s agent mode from 2.2+
• Support multi-controller endpoint from 2.4+
• Support api key verification from 2.5+, will has 2 mode to verify
  • Token: Disable the api key verification by checking the Disable API Key Verification checkbox, will use account and password to verify
  • API Key: Use an API key for verification. In this mode, the plugin will leverage large-scale parallel scanning.

Requirements

• For the Controller & Scanner mode, you need to install the NeuVector controller and scanner in the network. To scan the local image (the image on the Jenkins machine), the Controller & Scanner needs to be installed on the node where the image exists.

• For the standalone mode, Docker must be installed on the same host with Jenkins. Also, add jenkins user to the docker group.

     sudo usermod -aG docker jenkins
  

• If you run the Jenkins as a container, remember to mount a host directory -v /var/jenkins_home:/var/jenkins_home

  For example,
  

    docker run -p 8080:8080 -v /var/jenkins_home:/var/jenkins_home -v /var/run/docker.sock:/var/run/docker.sock -v $(which docker):$(which docker) --name=jenkins jenkins/jenkins:lts
  

  If you want to mount a host directory which is not /var/jenkins_home, for example /home/neuvector/jenkins_home. Please remember to add an environment variable JENKINS_MOUNT_PATH='/home/neuvector/jenkins_home'

  For example,
  

  • docker CLI

    docker run -p 8080:8080 -e JENKINS_MOUNT_PATH='/home/neuvector/jenkins_home' -v /home/neuvector/jenkins_home:/var/jenkins_home -v /var/run/docker.sock:/var/run/docker.sock -v $(which docker):$(which docker) --name=jenkins jenkins/jenkins:lts
    

  • docker-compose.yml

        jenkins-node:
        image: jenkins/jenkins:lts
        container_name: jenkins-node
        user: root
        ports:
            - 8080:8080
            - 50000:50000
        volumes:
            - /home/neuvector/jenkins_home:/var/jenkins_home
            - /usr/bin/docker:/usr/bin/docker
            - /var/run/docker.sock:/var/run/docker.sock:ro
        environment:
            - JENKINS_MOUNT_PATH=/home/neuvector/jenkins_home
    

    Setup the configuration in Jenkins

    After installing the plugin, you will find the NeuVector Vulnerability Scanner section in the global configuration page (Jenkins UI > Manage Jenkins > Configure System), and the first section you will see is to configure Controller & Scanner, then is the Standalone section.

Controller & Scanner

• Once you have done the following settings, you may click the Test Connection button to validate the values. It will show Connection Success or an error message.
• Supports multi-controller mode, allowing users to set up multiple controllers as servers and select one when generating the pipeline. If no controller is selected, the one named “default” will be chosen automatically.
• The controller endpoint name must be unique. If a duplicate is detected, it will be automatically removed when the user clicks the save button.

1. Enter values for the Controller & Scanner mode which includes the NeuVector Scanner source name, controller rest api url, username, and password.
2. TLS certificate check will check the consistency of between the certificate you provide in NeuVector Server Certificate and the server. Here is how we find the certificate in your server.
   1. Access into the pod of the expose cluster
   2. File location should /etc/neuvector/certs/ssl-cert.pem
   3. Copy the content and paste it here as the certificate.
3. You can disable TLS check by by clicking Skip TLS certificate check.
4. You can disable the api key verification by checking the Disable API Key Verification checkbox.
   1. Disable the api key verification uses account and password to verify
   2. Not disable the api key verification uses api key to verify
5. The timeout minutes value will terminate the build step within the time entered. The default value of 0 means no timeout will occur

Standalone

1. Enter values for the standalone scanner mode which includes NeuVector Scanner Registry URL, NeuVector Scanner Image Repository, NeuVector Scanner Registry User, NeuVector Scanner Registry Password.
2. Click the ‘Add Registry’ to enter values for the registry you will use in your project. If you just want to scan local images, you don’t need to add a registry here.

How to set up in build setp / pipeline

In your project configuration page, choose the NeuVector Vulnerability Scanner plugin from the drop down menu in the ‘Add build step’ / ‘pipeline’, these two have simiar configure pages.

1. Check the checkbox “Scan with Standalone scanner” if you want to do the scan in the standalone scanner mode. By default, it uses Controller & Scanner mode to do the scan.
2. Choose the controller endpoint you want to use if user select the controller mode, user can ignore it if select the standalone mode.
3. Define the registry in the global config page and choose the registry name here. Enter the repository (image) name and tag name. You may choose Jenkins default environment variables for the repository or tag. e.g. $JOB_NAME, $BUILD_TAG, $BUILD_NUMBER.
4. Enter the values for the number of high or medium, the vulnerability names that present to fail the build, the vulnerability names that are exempt from the scan. If you choose “Scan with Standalone”, the scan timeout is 10 minutes by default.
5. Finish the config, go back to the project page then click build. When the build finishes, a NeuVector report will be generated.

Setup K8s plugin in Jenkins

Set up the k8s machine in jenkins server

Pipeline example to run K8s agent mode

Here we provide an example pipeline from our testing machine.

pipeline {
    agent {
      // kubernetes represent the machine name.
      kubernetes {
        yaml '''
        apiVersion: v1
        kind: Pod
        spec:
          containers:
          - name: docker
            image: docker:dind
            command: ["/bin/sh", "-c"]
            args: ["dockerd & sleep infinity"]
            securityContext:
              privileged: true
              runAsUser: 0
          imagePullSecrets:
            - name: my-dockerhub-secret
        '''
      }
    }
    stages {
        stage('docker pull') {
            steps {
                // run the docker we declare above
                container('docker') {
                    script {
                        neuvector nameOfVulnerabilityToExemptFour: '', nameOfVulnerabilityToExemptOne: '', nameOfVulnerabilityToExemptThree: '', nameOfVulnerabilityToExemptTwo: '', nameOfVulnerabilityToFailFour: '', nameOfVulnerabilityToFailOne: '', nameOfVulnerabilityToFailThree: '', nameOfVulnerabilityToFailTwo: '', numberOfHighSeverityToFail: '', numberOfMediumSeverityToFail: '', controllerEndpointUrlSelection: 'your controller Endpoint', registrySelection: 'your registry', repository: 'your repo', scanTimeout: 10, standaloneScanner: true, tag: 'some tag', registrySelection: 'your choice'
                    }
                }
            }
        }
    }
}

Setup Pipeline to build large scale parallel scan

Use Token mode (2.4- or 2.5+ with token mode)

pipeline {
    agent any
    environment {
        REPO_NAME = 'your repo'
        REGISTRY_SELECTION = 'your registry'
        CONTROLLER = 'your controller'
        MAX_CONCURRENT_SCANS = 32
    }
    stages {
        stage('Parallel Vulnerability Scanning') {
            steps {
                script {
                    // There is a limit of 250 tags per list (by Jenkins) 
                    TAGS_LIST_PART1 = ["your tags"...]
                    TAGS_LIST_PART2 = ["your tags"...]
                    TAGS_LIST_PART3 = ["your tags"...]
                    TAGS_LIST_PART4 = ["your tags"...]
                    TAGS_LIST_PART5 = ["your tags"...]...
                    def allTags = TAGS_LIST_PART1 + TAGS_LIST_PART2 + TAGS_LIST_PART3 + TAGS_LIST_PART4 + TAGS_LIST_PART5
                    def batches = allTags.collate(MAX_CONCURRENT_SCANS.toInteger()) // Ensure MAX_CONCURRENT_SCANS is an integer
                    def batchCounter = 1                    for (batch in batches) {
                        stage("Batch ${batchCounter}") {
                            def scans = [:]
                            batch.each { tag ->
                                def currentTag = tag
                                scans["Scan ${currentTag}"] = {
                                    stage("Scan ${currentTag}") {
                                        neuvector(
                                            controllerEndpointUrlSelection: CONTROLLER,
                                            registrySelection: REGISTRY_SELECTION,
                                            repository: REPO_NAME,
                                            scanTimeout: 20,
                                            tag: "${currentTag}"
                                        )
                                        echo "Scan for tag ${currentTag} complete"
                                    }
                                }
                            }
                            parallel scans
                        }
                        batchCounter++
                    }
                }
            }
        }
    }
}

Use API Key mode (2.5+ api key mode)

pipeline {
    agent any
    environment {
        REPO_NAME = 'your repo'
        REGISTRY_SELECTION = 'your registry'
        CONTROLLER = 'your controller'
    }
    stages {
        stage('Parallel Vulnerability Scanning') {
            steps {
                script {
                    // There is a limit of 250 tags per list (by Jenkins) 
                    TAGS_LIST_PART1 = ["your tags"...]
                    TAGS_LIST_PART2 = ["your tags"...]
                    TAGS_LIST_PART3 = ["your tags"...]
                    TAGS_LIST_PART4 = ["your tags"...]
                    TAGS_LIST_PART5 = ["your tags"...]...
                    def allTags = TAGS_LIST_PART1 + TAGS_LIST_PART2 + TAGS_LIST_PART3 + TAGS_LIST_PART4 + TAGS_LIST_PART5

                    def scans = [:]
                    
                    allTags.each { tag ->
                        def currentTag = tag
                        scans["Scan ${currentTag}"] = {
                            stage("Scan ${currentTag}") {
                                neuvector(
                                    controllerEndpointUrlSelection: CONTROLLER,
                                    registrySelection: REGISTRY_SELECTION,
                                    repository: REPO_NAME,
                                    scanTimeout: 20,
                                    tag: "${currentTag}"
                                )
                                echo "Scan for tag ${currentTag} complete"
                            }
                        }
                    }
                    parallel scans
                }
            }
        }
    }
}

This site is open source. Improve this page.