docs(integrations): Jenkinsfile documentation and examples (Checkmarx…

…#3038)

docs/configuration-file.md

@@ -28,7 +28,7 @@ queries-path: "assets/queries"
 output-path: "results.json"
 ```
 
-> 📝 flags that can receive multiple values can be either provided as a comma separated string or an array as in the example above
+> 📝   flags that can receive multiple values can be either provided as a comma separated string or an array as in the example above
 
 ---
 

docs/integrations.md

@@ -3,10 +3,13 @@
 You can integrate KICS with your favorite CI/CD pipelines.
 We provide plugins for some CI/CD tools. For some others we provide a tutorial on how the integration can be done.
 
-- Integrate KICS with [Github Actions](integrations_ghactions.md)
-- Integrate KICS with [GitLab CI](integrations_gitlabci.md)
-- Integrate KICS with [Azure Pipelines](integrations_azurepipelines.md)
-- Integrate KICS with [Bitbucket Pipelines](integrations_bitbucketpipelines.md)
+Integrate KICS with:
+
+- [Azure Pipelines](integrations_azurepipelines.md)
+- [Bitbucket Pipelines](integrations_bitbucketpipelines.md)
+- [Github Actions](integrations_ghactions.md)
+- [GitLab CI](integrations_gitlabci.md)
+- [Jenkins](integrations_jenkins.md)
 - More soon...
 
 The pipelines examples can be found in our [GitHub Repository](https://github.com/Checkmarx/kics/tree/master/examples)

docs/integrations_gitlabci.md

@@ -13,66 +13,7 @@ include:
   - remote: https://raw.githubusercontent.com/checkmarx/kics/master/examples/gitlab/KICS.v1.gitlabci.yaml
 ```
 
-### Full Pipeline Tutorial
-
-The following tutorial is a possible way of using KICS in GitLab CI. You can be creative and come up with different solutions that fit your pipelines.
-
-In this case we instruct the job to download and use the latest Linux version of KICS.
-
-1- Edit or add a new job in the .gitlab-ci.yml file in your repository.
-
-2- In the beginning of the job, instruct it to get the latest version of KICS, for example in `before_script`:
-```yaml
-before_script:
-  - apk add --no-cache libc6-compat curl
-  - TAG=`curl --silent "https://api.github.com/repos/Checkmarx/kics/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/'`
-  - VERSION=`echo $TAG | sed -r 's/^.{1}//'`
-  - wget -q -c "https://github.com/Checkmarx/kics/releases/download/${TAG}/kics_${VERSION}_linux_x64.tar.gz" -O - | tar -xz --directory /usr/bin &>/dev/null
-```
-
-3- Define the necessary stages. For instance, scan with KICS and consume the results
-```yaml
-stages:
-  - kics
-  - kics-result
-```
-
-4- Declare the KICS scan
-```yaml
-kics-scan:
-  stage: kics
-  script:
-    - kics scan -q /usr/bin/assets/queries -p ${PWD} -o ${PWD}/kics-results.json
-  artifacts:
-    name: kics-results.json
-    paths:
-      - kics-results.json
-```
-
-5- Declare the consumption of results
-```yaml
-kics-results:
-  stage: kics-result
-  before_script:
-    - export TOTAL_SEVERITY_COUNTER=`grep '"total_counter"':' ' kics-results.json | awk {'print $2'}`
-    - export SEVERITY_COUNTER_HIGH=`grep '"HIGH"':' ' kics-results.json | awk {'print $2'} | sed 's/.$//'`
-    - export SEVERITY_COUNTER_MEDIUM=`grep '"INFO"':' ' kics-results.json | awk {'print $2'} | sed 's/.$//'`
-    - export SEVERITY_COUNTER_LOW=`grep '"LOW"':' ' kics-results.json | awk {'print $2'} | sed 's/.$//'`
-    - export SEVERITY_COUNTER_INFO=`grep '"MEDIUM"':' ' kics-results.json | awk {'print $2'} | sed 's/.$//'`
-  script:
-    - |
-      echo "TOTAL SEVERITY COUNTER: $TOTAL_SEVERITY_COUNTER
-      SEVERITY COUNTER HIGH: $SEVERITY_COUNTER_HIGH
-      SEVERITY COUNTER MEDIUM: $SEVERITY_COUNTER_MEDIUM
-      SEVERITY COUNTER LOW: $SEVERITY_COUNTER_LOW
-      SEVERITY COUNTER INFO: $SEVERITY_COUNTER_INFO"
-    - if [ "$SEVERITY_COUNTER_HIGH" -ge "1" ];then echo "Please fix all $SEVERITY_COUNTER_HIGH HIGH SEVERITY ISSUES" && exit 1;fi
-```
-Notice the last line, where it is defined a failing CI condition in case there is at least 1 High Severity result.
-
----
-
-Here is the full example:
+### Full Example
 
 ```yaml
 image: alpine

docs/integrations_jenkins.md

@@ -0,0 +1,130 @@
+# Running KICS in Jenkins
+
+You can integrate KICS into your Jenkins CI/CD pipelines.
+
+This provides you the ability to run KICS scans in as a stage in your pipeline.
+
+## Declarative pipelines:
+
+Create a new pipeline clicking on **New Item** on the left menu bar, then fill in the name of your pipeline and select the option "pipeline":
+
+<img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/jenkins-creating-pipeline.png" width="850">
+
+Paste one of the pipeline examples bellow:
+
+<img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/jenkins-paste-pipeline.png" width="850">
+
+Save and run your pipeline.
+
+<img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/jenkins-paste-success.png" width="850">
+
+Click on the build number to download the reports stored as artifacts.
+
+<img src="https://raw.githubusercontent.com/Checkmarx/kics/master/docs/img/jenkins-pipeline-artifacts.png" width="850">
+
+### Install and run
+
+The following pipeline uses downloads KICS binaries and place them under `/usr/bin/kics` before scanning a project:
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Checkout Code') {
+      steps {
+        git(branch: 'master', url: 'https://github.com/GoogleCloudPlatform/terraform-google-examples')
+      }
+    }
+    // Other stages ...
+    stage('KICS scan') {
+      steps {
+        installKICS()
+        sh "mkdir -p results"
+        sh(script: '/usr/bin/kics scan --ci --no-color -p ${WORKSPACE} --output-path results --report-formats "json,sarif,html"')
+        archiveArtifacts(artifacts: 'results/*.html,results/*.sarif,results/*.json', fingerprint: true)
+      }
+    }
+  }
+}
+
+def installKICS(){
+  def installScript = '''
+    LATEST_VERSION=1.2.4
+    if ! command -v /usr/bin/kics; then
+      wget -q -c https://github.com/Checkmarx/kics/releases/download/v${LATEST_VERSION}/kics_${LATEST_VERSION}_Linux_x64.tar.gz -O /tmp/kics.tar.gz
+      tar xfzv /tmp/kics.tar.gz -C /usr/bin
+      rm -f kics.tar.gz
+    fi
+    /usr/bin/kics version
+  '''
+
+  sh(script: installScript)
+}
+```
+
+### Using Docker
+
+The following pipeline uses KICS docker image to scan a project and publishes the HTML report in Jenkins.
+
+Plugins required:
+- [HTML Publisher Plugin](https://plugins.jenkins.io/htmlpublisher/)
+- [Docker Plugin](https://plugins.jenkins.io/docker-plugin/)
+- [Docker Pipeline Plugin](https://plugins.jenkins.io/docker-workflow/)
+
+```groovy
+pipeline {
+    agent {
+        docker {
+            image 'ubuntu:latest'
+        }
+    }
+    options {
+        timeout(time: 30, unit: 'MINUTES')
+        buildDiscarder(logRotator(numToKeepStr: '30', artifactNumToKeepStr: '30'))
+        disableConcurrentBuilds()
+    }
+    stages {
+        stage('Checkout Code') {
+          steps {
+              git branch: 'master', url: 'https://github.com/GoogleCloudPlatform/terraform-google-examples'
+              stash includes: '**/*', name: 'source'
+          }
+        }
+        stage('KICS scan') {
+            steps {
+                script {
+                    docker.image('checkmarx/kics:latest-alpine').inside("--entrypoint=''") {
+                      unstash 'source'
+                      sh('/app/bin/kics -p \$(pwd) -q /app/bin/assets/queries --ci -o results.html')
+                      archiveArtifacts(artifacts: 'results.html', fingerprint: true)
+                      publishHTML([allowMissing: true, alwaysLinkToLastBuild: true, keepAll: true, reportDir: '.', reportFiles: 'results.html', reportName: 'KICS Results', reportTitles: ''])
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+The report will be published in pure HTML by default, if you want to enable your browser to load css and javascript embedded in the report.html you'll have to configure a custom Content-Security-Policy HTTP header.
+
+| 📝 &nbsp; WARNING                                                    |
+|:---------------------------------------------------------------------|
+| Only disable Jenkins security features if you know what you're doing |
+
+</br>
+
+Go to **Manage Jenkins** > **Script Console**
+
+Paste the following script and run:
+
+```groovy
+System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "sandbox allow-scripts; default-src *; style-src * http://* 'unsafe-inline' 'unsafe-eval'; script-src 'self' http://* 'unsafe-inline' 'unsafe-eval'");
+```
+
+Jenkins will exhibit the following warning:
+
+```
+The default Content-Security-Policy is currently overridden using the hudson.model.DirectoryBrowserSupport.CSP system property, which is a potential security issue when browsing untrusted files. As an alternative, you can set up a resource root URL that Jenkins will use to serve some static files without adding Content-Security-Policy headers.
+```
+

examples/jenkins/agent-docker-html-report-declarative.jenkinsfile

@@ -0,0 +1,32 @@
+pipeline {
+    agent {
+        docker {
+            image 'ubuntu:latest'
+        }
+    }
+    options {
+        timeout(time: 30, unit: 'MINUTES')
+        buildDiscarder(logRotator(numToKeepStr: '30', artifactNumToKeepStr: '30'))
+        disableConcurrentBuilds()
+    }
+    stages {
+        stage('Checkout Code') {
+          steps {
+              git branch: 'master', url: 'https://github.com/GoogleCloudPlatform/terraform-google-examples'
+              stash includes: '**/*', name: 'source'
+          }
+        }
+        stage('KICS scan') {
+            steps {
+                script {
+                    docker.image('checkmarx/kics:latest-alpine').inside("--entrypoint=''") {
+                      unstash 'source'
+                      sh('/app/bin/kics -p \$(pwd) -q /app/bin/assets/queries --ci -o results.html')
+                      archiveArtifacts(artifacts: 'results.html', fingerprint: true)
+                      publishHTML([allowMissing: true, alwaysLinkToLastBuild: true, keepAll: true, reportDir: '.', reportFiles: 'results.html', reportName: 'KICS Results', reportTitles: ''])
+                    }
+                }
+            }
+        }
+    }
+}

examples/jenkins/agent-linux-simple-declarative.jenkinsfile

@@ -0,0 +1,32 @@
+pipeline {
+  agent any
+  stages {
+    stage('Checkout Code') {
+      steps {
+        git(branch: 'master', url: 'https://github.com/GoogleCloudPlatform/terraform-google-examples')
+      }
+    }
+    stage('KICS scan') {
+      steps {
+        installKICS()
+        sh "mkdir -p results"
+        sh(script: '/usr/bin/kics scan --ci --no-color -p ${WORKSPACE} --output-path results --report-formats "json,sarif,html"')
+        archiveArtifacts(artifacts: 'results/*.html,results/*.sarif,results/*.json', fingerprint: true)
+      }
+    }
+  }
+}
+
+def installKICS(){
+  def installScript = '''
+    LATEST_VERSION=1.2.4
+    if ! command -v /usr/bin/kics; then
+      wget -q -c https://github.com/Checkmarx/kics/releases/download/v${LATEST_VERSION}/kics_${LATEST_VERSION}_Linux_x64.tar.gz -O /tmp/kics.tar.gz
+      tar xfzv /tmp/kics.tar.gz -C /usr/bin
+      rm -f kics.tar.gz
+    fi
+    /usr/bin/kics version
+  '''
+
+  sh(script: installScript)
+}

mkdocs.yml

@@ -34,10 +34,11 @@ nav:
           - OpenAPI: queries/openapi-queries.md
   - Integrations:
       - Overview: integrations.md
-      - Github Actions: integrations_ghactions.md
-      - Gitlab CI: integrations_gitlabci.md
       - Azure DevOps: integrations_azurepipelines.md
       - Bitbucket Pipelines: integrations_bitbucketpipelines.md
+      - Github Actions: integrations_ghactions.md
+      - Gitlab CI: integrations_gitlabci.md
+      - Jenkins: integrations_jenkins.md
   - Project:
       - Roadmap: roadmap.md
       - Plans: "https://github.com/Checkmarx/kics/projects"