- It is best practice to catch issues as early as possible in the development cycle since it both improves security and decreases the workload for both developers and security.
- In order to do this, CrowdStrike is offering solutions for developers at build time that allow them to assess their Docker container images and review summarized report data integrated with their favorite CI/CD tools like Jenkins.
- Customers will use this feature by downloading from Falcon console, and following Falcon documentation to install our plugins on top of their existing self-hosted CI/CD solutions.
- Customers will then generate a new authentication token within Falcon console, and configure their plugin to use this credential for communication with existing Falcon APIs.
- Users of this plugin receive a unique HTML view of the Image Assessment report data embedded inside Jenkins.
- Users of this plugin can choose to use the information Falcon provides to actively abort the deployment of vulnerable container images as an in-line step in the build pipeline.
Image Assessment is focused on identifying vulnerabilities in container images.
This plugin is leveraging that existing feature of Falcon via the Falcon API.
For more information about CrowdStrike's Image Assessment feature:
- Login to Falcon console.
- Navigate to
Menu > Support and resources > Documentation > Kubernetes & Containers > Container Security > Assessing your images
.
- Java >= 8
- Jenkins >= 2.319.1
- Docker Engine + CLI (any version)
- Must have a paid subscription to CrowdStrike Falcon
- Your
CID
should have:Product Bundle
:Cloud Workload Protection (CWP)
SKU
:Falcon Container Image Scanning
- Your
CID
>User
should have:Role
:Falcon Container Image Admin
- Your API
ClientID
should have:Scope
:Falcon Container Image
bothREAD
+WRITE
- Your
-
- Go to "Manage Jenkins" > "Manage Plugins" > "Available".
- Search for "CrowdStrike Security".
- Install the plugin.
-
- Download the latest stable release version of this plugin from Falcon console.
Falcon console > Support > Tool Downloads
- Click to download
CrowdStrike Security for Jenkins
file archive. - Extract the
.zip
archive locally. - Look for the
.hpi
file which is the format of a Jenkins plugin.
- Upload the plugin to Jenkins
- In Jenkins, navigate to
Manage Jenkins > Manage plugins
. - Click on the
advanced
tab. - Click
Choose File
and select the.hpi
file you extracted from archive, earlier
- In Jenkins, navigate to
- Download the latest stable release version of this plugin from Falcon console.
-
Click
Deploy
-
Additional resources to Installing a new plugin in Jenkins.
These settings are used for authenticating Jenkins plugin to Falcon services. You can fill them in manually, or use the automatic configuration option (ie. if you have a large fleet of Jenkins servers).
- Generate the token to enable communication with Falcon API by Jenkins.
- Login to Falcon console.
- If you have defined more than one Customer ID (
CID
), it's important to choose the one with appropriate permissions from top-right navigation drop-down menu in Falcon console, before proceeding. - Visit
Falcon console > Support > API Clients & Keys
- Select
Falcon Container Image
permission withREAD
andWRITE
access checked. - Click
Add
button to finish creating your credentials. - On the following screen you will be given
Client ID
andSecret
values. Copy these to your clipboard.
-
In Jenkins, navigate to
Manage Jenkins > Manage Credentials > System > Global Credentials > Add Credentials
-
In Jenkins, navigate to
Manage Jenkins > Configure System > CrowdStrike Security
,- Select the
Credential ID
(generated above). - Select a
Falcon Cloud
from the dropdown menu. - Click the
Save
button.
- Select the
It represents the server where a) your Customer ID (CID) has a subscription, b) where you generated the Client ID
and Secret
credentials (where they are active/accepted), c) where this plugin will push your Docker container images to for assessment, and d) where this plugin will pull the Image Assessment reports from. The table below shows which cloud the user selection will correspond with.
Falcon Cloud (User Selection) | Cloud Env | Type | Falcon API Domain | Falcon Registry Domain | Access |
---|---|---|---|---|---|
us-1.crowdstrike.com | Beta (CSA) | Production | api.crowdstrike.com | container-upload.us-1.crowdstrike.com | Public |
us-2.crowdstrike.com | Maverick | Production | api.us-2.crowdstrike.com | container-upload.us-2.crowdstrike.com | Public |
eu-1.crowdstrike.com | Lion | Production | api.eu-1.crowdstrike.com | container-upload.eu-1.crowdstrike.com | Public |
us-gov-1.crowdstrike.com | Eagle | Production | api.laggar.gcw.crowdstrike.com | container-upload.laggar.gcw.crowdstrike.com | DoD IL4 |
us-gov-2.crowdstrike.com | Merlin | Production | api.us-gov-2.crowdstrike.com | container-upload.us-gov-2.crowdstrike.com | DoD IL5 |
- Subscribing customers will have a Customer ID (CID).
- A single CID can create many ClientIDs.
- Each ClientID should have minimum permission set needed to do a task (ie. so if someone stole the credential from Jenkins, they would only be able to upload images for assessment)
Jenkins administrators in an enterprise environment would most likely rather use Jenkins Configuration as Code (JCasC) which imports configuration from YAML files. We offer compatibility with this plugin.
- Install
Configuration as Code
Plugin on your Jenkins instance.
To configure your Vault in Jenkins add the following to jenkins.yaml
:
unclassified:
crowdStrikeSecurity:
falconCloud: "FALCON CLOUD"
falconCredentialId: "Falcon_Credential_Id"
credentials:
system:
domainCredentials:
- credentials:
- credentialsDefault:
description: "Falcon Token"
clientID: "${CLIENT_ID}"
id: "falconToken"
scope: GLOBAL
secret: "${SECRET_TOKEN}"
See handling secrets section in JCasC documentation to see how to handle sensitive information.
If you are unsure how your yaml file should look like, you can still use the UI to configure credentials. After you configured Credentials and global configurations you can use the export feature build into JCasC by visiting <jenkins-domain>/configuration-as-code/viewExport
To use a Job DSL plugin script with JCasC, add the following to the jenkins.yaml
:
jobs:
- script: >
pipelineJob('CrowdStrikeSecurity-Pipeline') {
definition {
cps {
script('''
pipeline {
agent any
stages {
stage('Scan image with CrowdStrike security') {
steps {
withCredentials([usernameColonPassword(credentialsId: 'INTEGRATION_ID', variable: '')]) {
crowdStrikeSecurity imageName: 'mongo', imageTag: 'bionic', enforce: true, skipImageUpload: true, timeout: 60
}
}
}
}
}
'''.stripIndent())
sandbox()
}
}
}
- script: >
job('CrowdStrikeSecurity-Freestyle') {
steps {
crowdStrikeSecurity() {
enforce(true)
skipImageUpload(true)
imageName('mongo')
imageTag('bionic')
timeout(60)
}
}
}
Depending on the type of jobs you have.
These settings must be specified for each Jenkins job, where the plugin is intended to be used to assess container images.
- In Jenkins, navigate to
New Item > Freestyle project
. - Fill the necessary details, and click on
Add build step
underBuild
section. - Select
CrowdStrike Security Plugin
.
- Enter the following details:
- For
When image does not comply with policy
, choose one:Enforce the recommendation
: if Falcon policy is set to "Prevent", Jenkins will enforce this by failing the build.
(You will still receive an Image Assessment report.)Skip image upload
: Select this option only if the image is already uploaded to CrowdStrike as part of a previous step. When selected, the plugin will not executedocker push
. It only retrieves the image scan report but does not upload the image to CrowdStrike for assessment.
- Image to assess:
Image Name
: name of the docker image that will be scanned by CrowdStrike Image Assessment.Image Tag
: tag of the docker image that will be scanned by CrowdStrike Image Assessment.Timeout
: how to long to wait (in seconds) before failing build, if unable to communicate with Falcon API.
- For
NOTICE: if Enforce the recommendation
option is not set, the plugin assumes docker
binary is installed and in $PATH
, and that it is already configured to connect to a running Docker Engine, where images will be pulled-to/pushed-from.
NOTICE: You may use environment $VARIABLES
in the field values above. (e.g., if Docker image tag is incrementing per-build)
- Click "Save"
- In Jenkins, navigate to
New Item > Pipeline
. - Fill the necessary details, and add your script to the Pipeline definition.
pipeline {
agent any
stages {
stage('Stage 1') {
steps {
withCredentials([usernameColonPassword(credentialsId: 'Falcon_Token', variable: '')]) {
crowdStrikeSecurity imageName: 'mongo', imageTag: 'bionic', enforce: true, timeout: 60
}
}
}
}
}
- Additional Pipeline information
Schedule the job to run normally, and the report will be stored among the job output as a set of artifact files.
- Inside the project, click on
Build Now
. - Under the
Build history
section on the left bar, the user would be able to click on the build to see theImage Assessment
output. - The report data is viewable in HTML displaying the details such as Build Blocked, Actions Needed, Vulnerabilities found, etc. if the build is successful.
- Additional troubleshooting details from stdout/stderr are available in
Console Output
.
Symptom | Possible cause | Solution |
---|---|---|
502 Bad Gateway -1001 -1002 -1004 -1005 -1006 -1010 |
||
-1002 -1004 |
docker binary is not found.image:tag name is not loaded into Docker Engine. |
docker CLI binary is installed and included in the OS environment PATH variable, in scope for Jenkins build scripts and shell execution contexts.docker CLI client binary.docker pull or docker build before the CrowdStrike Security build step begins, so that the container image is already loaded into the Docker Engine. |
docker tag failure.-1003 |
$VARIABLE syntax, ensure variable is predefined and in scope. |
|
404 Not Found |
Code | Name | Description |
---|---|---|
-1001 | AUTHENTICATION_FAILURE | User authentication failed. |
-1002 | DOCKER_LOGIN_FAILURE | Docker login has failed |
-1003 | DOCKER_TAG_FAILURE | Error in performing docker tag |
-1004 | DOCKER_PUSH_FAILURE | Error in performing docker push |
-1005 | FETCH_ASSESSMENT_REPORT_FAILURE | Error in fetching the CrowdStrike Security assessment report |
-1006 | FETCH_POLICY_REPORT_FAILURE | Error in fetching the CrowdStrike Security policy report |
-1007 | PREVENT_BUILD_DUE_TO_POLICY | CrowdStrike Security prevented the build due to the Falcon Policy. Please deselect Enforce the recommendation option in the per-build configuration if you do not want CrowdStrike Security to prevent this build. |
-1008 | PREVENT_BUILD_RECOMMENDATION | CrowdStrike Security recommends to prevent the build as per the Falcon Policy. Please select Enforce the recommendation option in the per-build configuration if you want CrowdStrike Security to enforce the policy. |
-1009 | HTML_GENERATION_FAILURE | Failed to generate HTML report |
-1010 | BUILD_TIMED_OUT | Build Step Timed-out. Try increasing the value in timeout field in the per-build configuration |
-1011 | INTERNAL_ERROR | CrowdStrike Security plugin faced an unknown internal error. |
If you want to double-check the vulnerabilities that are found in an existing container image, you can use the following tool.
This tool is a command-line container image assessment tool that looks for vulnerabilities in the Docker images. It unpacks the image locally, and uploads ONLY METADATA to Falcon, which then returns any known vulnerabilities.
The main disadvantage of using IVAN is it can only use its local disk to check for installed package vulnerabilities. Compared to the approach taken by this Jenkins plugin, and the Python script below, where the image layers are uploaded to Falcon, which can then perform more in-depth assessment on the server side, yielding additional more detailed data in the assessment report including detections for malware, application vulnerabilities, secret strings, etc.
If you suspect the image is fine but you want to make your Image Assessment Policy more/less strict, you will need to do that via the Falcon console. Talk to your Security Administrator if you do not have access, and give them the Policy Name shown in the Image Assessment report data.
If you suspect the plugin is the problem, you can try this alternative which is a command-line tool. It still talks to Falcon API, and the assessment happens remotely, but it doesn't require Jenkins or this plugin.
Alternatively, you can use the exit code of this script to pass/fail your Jenkins builds.
This Python script will upload your container image to Falcon API and return the Image Assessment report data as JSON to stdout. This will tell you about known vulnerabilities, malware, and secrets found in the image layers. However, it does not support the Image Assessment Policy prevent/alert feature.
- Paying customers may contact CrowdStrike Support team regarding:
- HOWTO plugin installation
- Troubleshooting plugin failure (NOT image vulnerability!)
- Troubleshooting Falcon API response
- Configuring Image Assessment Policy