diff --git a/docs/configuration-file.md b/docs/configuration-file.md index 0d9a77bf5c7..049585b74a7 100644 --- a/docs/configuration-file.md +++ b/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 --- diff --git a/docs/img/jenkins-creating-pipeline.png b/docs/img/jenkins-creating-pipeline.png new file mode 100644 index 00000000000..89df902f0ae Binary files /dev/null and b/docs/img/jenkins-creating-pipeline.png differ diff --git a/docs/img/jenkins-paste-pipeline.png b/docs/img/jenkins-paste-pipeline.png new file mode 100644 index 00000000000..e98cefd8e90 Binary files /dev/null and b/docs/img/jenkins-paste-pipeline.png differ diff --git a/docs/img/jenkins-pipeline-artifacts.png b/docs/img/jenkins-pipeline-artifacts.png new file mode 100644 index 00000000000..fe3f5909a0d Binary files /dev/null and b/docs/img/jenkins-pipeline-artifacts.png differ diff --git a/docs/img/jenkins-pipeline-success.png b/docs/img/jenkins-pipeline-success.png new file mode 100644 index 00000000000..db1d8926e3f Binary files /dev/null and b/docs/img/jenkins-pipeline-success.png differ diff --git a/docs/integrations.md b/docs/integrations.md index d0c380a8249..78930452ff1 100644 --- a/docs/integrations.md +++ b/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) diff --git a/docs/integrations_gitlabci.md b/docs/integrations_gitlabci.md index f4592ea4913..99ba1ad6a2b 100644 --- a/docs/integrations_gitlabci.md +++ b/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 diff --git a/docs/integrations_jenkins.md b/docs/integrations_jenkins.md new file mode 100644 index 00000000000..058868ed23f --- /dev/null +++ b/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": + + + +Paste one of the pipeline examples bellow: + + + +Save and run your pipeline. + + + +Click on the build number to download the reports stored as artifacts. + + + +### 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. + +| 📝   WARNING | +|:---------------------------------------------------------------------| +| Only disable Jenkins security features if you know what you're doing | + +
+ +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. +``` + diff --git a/examples/azure-pipelines.yaml b/examples/azure-pipelines/azure-pipelines.yaml similarity index 100% rename from examples/azure-pipelines.yaml rename to examples/azure-pipelines/azure-pipelines.yaml diff --git a/examples/bitbucket-pipelines.yaml b/examples/bitbucket/bitbucket-pipelines.yaml similarity index 100% rename from examples/bitbucket-pipelines.yaml rename to examples/bitbucket/bitbucket-pipelines.yaml diff --git a/examples/cx-kics-github-actions-sarif.yaml b/examples/github/kics-docker-runner-sarif.yaml similarity index 100% rename from examples/cx-kics-github-actions-sarif.yaml rename to examples/github/kics-docker-runner-sarif.yaml diff --git a/examples/jenkins/agent-docker-html-report-declarative.jenkinsfile b/examples/jenkins/agent-docker-html-report-declarative.jenkinsfile new file mode 100644 index 00000000000..14ba2746e0d --- /dev/null +++ b/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: '']) + } + } + } + } + } +} diff --git a/examples/jenkins/agent-linux-simple-declarative.jenkinsfile b/examples/jenkins/agent-linux-simple-declarative.jenkinsfile new file mode 100644 index 00000000000..bd0cda61db5 --- /dev/null +++ b/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) +} diff --git a/mkdocs.yml b/mkdocs.yml index b47e8485757..af21beda545 100644 --- a/mkdocs.yml +++ b/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"