AWS inspector: Jenkins plugin: IAM/OIDC auth, credential hygiene, CSP warnings
Summary
Major rewrite of the Amazon Inspector Jenkins plugin documentation. Added authentication guidance that recommends assuming an IAM role (including via Jenkins-issued OIDC tokens) over storing long-term AWS access keys, a sample OIDC trust policy scoped with aud/sub conditions so only specific jobs can assume the role, advice to use a read-only registry access token for Docker credentials, the recommendation to give the controller's credentials only the permissions of the scan role, a warning that IAM-user access keys with programmatic access present a security risk, and a warning that removing Jenkins' Content Security Policy lets any workspace HTML run scripts in users' browsers. Also documents a new Step 5 for serving the HTML report, new plugin parameters (malicious package blocking, license collection, EPSS, CVE suppression/auto-fail), troubleshooting errors, and updated per-file change.
Security assessment
The change is security documentation rather than a fix: it steers users to IAM role assumption with OIDC ID tokens ("OIDC doesn't require you to store long-term AWS credentials in Jenkins"), shows a trust policy restricted by `aud`/`sub` conditions to a single job, recommends least privilege for the controller's default credential chain ("Any job that uses the build step can use those credentials, so give them only the permissions of the role that you created in Step 1"), advises a read-only registry token instead of an account password, and explicitly warns that Jenkins' CSP must be removed at the cost of allowing arbitrary build-artifact HTML/JS to execute. No specific vulnerability, CVE, or incident is referenced (the CVE IDs such as CVE-2023-1234 are illustrative parameter examples), so security_issue_related is false while the credential-hardening and CSP-exposure guidance is documented.
Evidence
+This scenario requires IAM users with programmatic access and long-term credentials, which presents a security risk. To help mitigate this risk, we recommend that you provide these users with only the permissions they require to perform the task and that you remove these users when they are no longer needed. Access keys can be updated if necessary. For more information, see [Update access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-credentials-access-keys-update.html) in the _IAM User Guide_.
Diff
diff --git a/inspector/latest/user/cicd-jenkins.md b/inspector/latest/user/cicd-jenkins.md index b1abf35..6d3874d 100644 --- a//inspector/latest/user/cicd-jenkins.md +++ b//inspector/latest/user/cicd-jenkins.md @@ -7 +7 @@ -Step 1. Set up an AWS accountStep 2. Install the Amazon Inspector Jenkins Plugin(Optional) Step 3. Add docker credentials to Jenkins(Optional) Step 4. Add AWS credentialsStep 5. Add CSS support in a Jenkins scriptStep 6. Add Amazon Inspector Scan to your buildStep 7. View your Amazon Inspector vulnerability reportTroubleshooting +Step 1. Set up an AWS accountStep 2. Install the Amazon Inspector Jenkins plugin(Optional) Step 3. Add Docker credentials to Jenkins(Optional) Step 4. Add AWS credentials to JenkinsStep 5. Allow Jenkins to display the HTML reportStep 6. Add Amazon Inspector Scan to your buildStep 7. View your Amazon Inspector vulnerability reportTroubleshooting @@ -11 +11 @@ Step 1. Set up an AWS accountStep 2. Install the Amazon Inspector Jenkins Plugin -The Jenkins plugin leverages the [Amazon Inspector SBOM Generator](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html#sbomgen-supported) binary and Amazon Inspector Scan API to produce detailed reports at the end of your build, so you can investigate and remediate risk before deployment. With the Amazon Inspector Jenkins plugin, you can add Amazon Inspector vulnerability scans to your Jenkins pipeline. Amazon Inspector vulnerability scans can be configured to pass or fail pipeline executions based on the number and severity of vulnerabilities detected. You can view the latest version of the Jenkins plugin in the Jenkins marketplace at [https://plugins.jenkins.io/amazon-inspector-image-scanner/](https://plugins.jenkins.io/amazon-inspector-image-scanner/). The following steps describe how to set up the Amazon Inspector Jenkins plugin. +The Amazon Inspector Jenkins plugin adds Amazon Inspector vulnerability scans to your Jenkins builds. The plugin runs the [Amazon Inspector SBOM Generator](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html#sbomgen-supported) to create a software bill of materials (SBOM) for a container image. It sends the SBOM to the Amazon Inspector Scan API and produces detailed reports at the end of your build, so you can investigate and remediate risk before deployment. You can fail the build based on the number and severity of vulnerabilities, Exploit Prediction Scoring System (EPSS) scores, specific common vulnerabilities and exposures (CVEs), or malicious packages. For the latest version of the plugin, see [Amazon Inspector Scanner](https://plugins.jenkins.io/amazon-inspector-image-scanner/) on the Jenkins plugins website. The following steps describe how to set up the Amazon Inspector Jenkins plugin. @@ -15 +15 @@ The Jenkins plugin leverages the [Amazon Inspector SBOM Generator](https://docs. -Before completing the following steps, you must upgrade Jenkins to version 2.387.3 or higher for the plugin to run. +The plugin requires Jenkins 2.541.3 or later. The Amazon Inspector SBOM Generator is available only for Linux, so run your builds on Linux with an x86_64 (amd64) or arm64 CPU. With the **Automatic** installation method, the Jenkins controller must also run Linux. @@ -21 +21 @@ Configure an AWS account with an IAM role that allows access to the Amazon Inspe -## Step 2. Install the Amazon Inspector Jenkins Plugin +## Step 2. Install the Amazon Inspector Jenkins plugin @@ -25 +25 @@ The following procedure describes how to install the Amazon Inspector Jenkins pl - 1. From the Jenkins dashboard, choose **Manage Jenkins** , and then choose **Manage Plugins**. + 1. From the Jenkins dashboard, choose **Manage Jenkins** , and then choose **Plugins**. @@ -27 +27 @@ The following procedure describes how to install the Amazon Inspector Jenkins pl - 2. Choose **Available**. + 2. Choose **Available plugins**. @@ -29 +29 @@ The following procedure describes how to install the Amazon Inspector Jenkins pl - 3. From the **Available** tab, search for **Amazon Inspector Scans** , and then install the plugin. + 3. Search for **Amazon Inspector Scanner** , select it, and then choose **Install**. @@ -34 +34 @@ The following procedure describes how to install the Amazon Inspector Jenkins pl -## (Optional) Step 3. Add docker credentials to Jenkins +## (Optional) Step 3. Add Docker credentials to Jenkins @@ -38 +38 @@ The following procedure describes how to install the Amazon Inspector Jenkins pl -Only add docker credentials if the docker image is in a private repository. Otherwise, skip this step. +Only add Docker credentials if the image is in a private repository. Otherwise, skip this step. @@ -40 +40 @@ Only add docker credentials if the docker image is in a private repository. Othe -The following procedure describes how to add docker credentials to Jenkins from the Jenkins dashboard. +The following procedure describes how to add Docker credentials to Jenkins from the Jenkins dashboard. @@ -44 +44 @@ The following procedure describes how to add docker credentials to Jenkins from - 2. Choose **Global credentials** and then **Add credentials**. + 2. Choose **Global** , and then choose **Add Credentials**. @@ -46 +46 @@ The following procedure describes how to add docker credentials to Jenkins from - 3. For **Kind** , select **Username with password**. + 3. Select **Username with password** , and then choose **Next**. @@ -50 +50 @@ The following procedure describes how to add docker credentials to Jenkins from - 5. Enter your details, and then choose **OK**. + 5. Enter the user name and password for your registry, and then choose **Create**. If your registry supports access tokens, we recommend that you use a read-only token as the password instead of your account password. @@ -55 +55 @@ The following procedure describes how to add docker credentials to Jenkins from -## (Optional) Step 4. Add AWS credentials +## (Optional) Step 4. Add AWS credentials to Jenkins @@ -57 +57,14 @@ The following procedure describes how to add docker credentials to Jenkins from -###### Note +The plugin calls the Amazon Inspector Scan API from the Jenkins controller. When you configure the build step in Step 6, you choose one of the following ways for the plugin to authenticate: + + * **(Recommended) IAM role** – The plugin assumes the role that you created in Step 1. To assume the role, the plugin uses the credentials that the Jenkins controller already has, such as an Amazon EC2 instance profile. Those credentials need permission to call `sts:AssumeRole` on the role. The plugin can also assume the role with an OpenID Connect (OIDC) ID token that Jenkins issues. OIDC doesn't require you to store long-term AWS credentials in Jenkins. + + * **AWS credentials** – An access key for an IAM user, stored in Jenkins. + + * **AWS profile name** – A named profile in the AWS configuration files of the user that runs the Jenkins controller. + + + + +If you don't configure any of these, the plugin uses the default credential provider chain on the Jenkins controller, such as environment variables or an Amazon EC2 instance profile. Any job that uses the build step can use those credentials, so give them only the permissions of the role that you created in Step 1. You only need to add credentials to Jenkins to use an access key or OIDC. Otherwise, skip this step. + +###### Warning @@ -59 +72 @@ The following procedure describes how to add docker credentials to Jenkins from -Only add AWS credentials if you want to authenticate based on an IAM user. Otherwise, skip this step. +This scenario requires IAM users with programmatic access and long-term credentials, which presents a security risk. To help mitigate this risk, we recommend that you provide these users with only the permissions they require to perform the task and that you remove these users when they are no longer needed. Access keys can be updated if necessary. For more information, see [Update access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-credentials-access-keys-update.html) in the _IAM User Guide_. @@ -61 +74 @@ Only add AWS credentials if you want to authenticate based on an IAM user. Other -The following procedure describes how to add AWS credentials from the Jenkins dashboard. +###### To add an access key @@ -65 +78 @@ The following procedure describes how to add AWS credentials from the Jenkins da - 2. Choose **Global credentials** and then **Add credentials**. + 2. Choose **Global** , and then choose **Add Credentials**. @@ -67 +80 @@ The following procedure describes how to add AWS credentials from the Jenkins da - 3. For **Kind** , select **AWS Credentials**. + 3. Select **AWS Credentials** , and then choose **Next**. @@ -69 +82 @@ The following procedure describes how to add AWS credentials from the Jenkins da - 4. Enter your details, including your **Access Key ID** and **Secret Access Key** , and then choose **OK**. + 4. Enter your **Access Key ID** and **Secret Access Key** , and then choose **Create**. @@ -74 +87 @@ The following procedure describes how to add AWS credentials from the Jenkins da -## Step 5. Add CSS support in a Jenkins script +###### To add an OIDC credential @@ -76 +89,7 @@ The following procedure describes how to add AWS credentials from the Jenkins da -The following procedure describes how to add CSS support in a Jenkins script. + 1. From the Jenkins dashboard, choose **Manage Jenkins** , **Credentials** , and then **System**. + + 2. Choose **Global** , and then choose **Add Credentials**. + + 3. Select **OpenID Connect id token** , and then choose **Next**. + + 4. For **Audience** , enter `sts.amazonaws.com`, and then choose **Create**. To see the issuer URI of the credential, open it and choose **Update credential**. @@ -78 +97 @@ The following procedure describes how to add CSS support in a Jenkins script. - 1. Restart Jenkins. + 5. In IAM, create an OIDC identity provider with the issuer URI as the provider URL and `sts.amazonaws.com` as the audience. For more information, see [Create an OpenID Connect (OIDC) identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). @@ -80 +99 @@ The following procedure describes how to add CSS support in a Jenkins script. - 2. From the Dashboard, choose **Manage Jenkins** , **Nodes** , **Built-In Node** , and then **Script Console**. + 6. Add a statement to the trust policy of the role that you created in Step 1 that allows the provider to call `sts:AssumeRoleWithWebIdentity`. Include a condition on the provider's `aud` key with the value `sts.amazonaws.com`. To allow only specific jobs to assume the role, also add a condition on the `sub` key, which contains the URL of the job by default. The following example statement allows only the job `my-job` on a Jenkins controller at `jenkins.example.com` to assume the role. @@ -82 +101,13 @@ The following procedure describes how to add CSS support in a Jenkins script. - 3. In the text box, add the line `System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "")`, and then choose **Run**. + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::111122223333:oidc-provider/jenkins.example.com/oidc" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "jenkins.example.com/oidc:aud": "sts.amazonaws.com", + "jenkins.example.com/oidc:sub": "https://jenkins.example.com/job/my-job/" + } + } + } @@ -87 +118,5 @@ The following procedure describes how to add CSS support in a Jenkins script. -## Step 6. Add Amazon Inspector Scan to your build +###### Note + +AWS must be able to reach the issuer URI over HTTPS, and the URI shouldn't include a port number. If your Jenkins controller isn't reachable from the internet, or its URL includes a port, use a different issuer. For more information, see [Picking an issuer](https://github.com/jenkinsci/oidc-provider-plugin#picking-an-issuer) in the OpenID Connect Provider plugin documentation on the GitHub website. + +## Step 5. Allow Jenkins to display the HTML report @@ -89 +124 @@ The following procedure describes how to add CSS support in a Jenkins script. -You can add Amazon Inspector Scan to your build by adding a build step in your project or by using the Jenkins declarative pipeline. +The plugin creates an HTML report that uses inline CSS and JavaScript. By default, Jenkins serves build artifacts with a Content Security Policy (CSP) that blocks both. As a result, the report has no styling and shows zero findings, even when the scan found vulnerabilities. Use one of the following options so that the report displays correctly. @@ -91 +126 @@ You can add Amazon Inspector Scan to your build by adding a build step in your p -### Amazon Inspector Scan to your build by adding a build step in your project + * **(Recommended) Serve build artifacts from another domain** – Choose **Manage Jenkins** and then **System**. Under **Serve resource files from another domain** , enter a **Resource Root URL** that points to your Jenkins controller with a different host name than your Jenkins URL. Jenkins doesn't apply the CSP to files that it serves from this URL. For more information, see [Resource Root URL](https://www.jenkins.io/doc/book/security/user-content/#resource-root-url) in the Jenkins documentation. @@ -93 +128 @@ You can add Amazon Inspector Scan to your build by adding a build step in your p - 1. On the configuration page, scroll down to **Build Steps** , and choose **Add build step**. Then select **Amazon Inspector Scan**. + * **Remove the CSP** – Set the `hudson.model.DirectoryBrowserSupport.CSP` system property to an empty value. To apply the change immediately, choose **Manage Jenkins** and then **Script Console** , run `System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "")`, and then reload the report. Only Jenkins administrators can use the Script Console. This change lasts until Jenkins restarts. To keep it, start Jenkins with the Java option `-Dhudson.model.DirectoryBrowserSupport.CSP=`. @@ -95 +129,0 @@ You can add Amazon Inspector Scan to your build by adding a build step in your p - 2. Choose between two inspector-sbomgen installation methods: **Automatic** or **Manual**. The automatic option allows the plugin to download the most recent version. It also makes sure you always have the latest features, security updates, and bug fixes. @@ -97 +130,0 @@ You can add Amazon Inspector Scan to your build by adding a build step in your p - 1. (Option 1) Choose **Automatic** to download the latest version of inspector-sbomgen. This option automatically detects the operating system and CPU architecture that's currently in use. @@ -99 +131,0 @@ You can add Amazon Inspector Scan to your build by adding a build step in your p - 2. (Option 2) Choose **Manual** if you want to set up the Amazon Inspector SBOM Generator binary for scanning. If you choose this method, make sure to provide the full path to a previously downloaded version of inspector-sbomgen. @@ -101 +133 @@ You can add Amazon Inspector Scan to your build by adding a build step in your p -For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html#install-sbomgen) in [Amazon Inspector SBOM Generator](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator.html). +###### Warning @@ -103 +135,3 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 3. Complete the following to finish configuring the Amazon Inspector Scan build step: +Removing the CSP allows any HTML file in a workspace or build artifact to run scripts in the browsers of your Jenkins users. Only remove it if you trust everyone who can change files in your builds, and all of your build agents. For more information, see [Configuring Content Security Policy](https://www.jenkins.io/doc/book/security/configuring-content-security-policy/) in the Jenkins documentation. + +## Step 6. Add Amazon Inspector Scan to your build @@ -105 +139 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 1. Input your **Image Id**. The image can be local, remote, or archived. Image names should follow the Docker naming convention. If analyzing an exported image, provide the path to the expected tar file. See the following example Image Id paths: +You can add Amazon Inspector Scan as a build step in a freestyle project, or as a step in a Jenkins pipeline. @@ -107 +141 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 1. For local or remote containers: `NAME[:TAG|@DIGEST]` +### Add Amazon Inspector Scan as a build step @@ -109 +143 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 2. For a tar file: `/path/to/image.tar` + 1. On the configuration page of your project, under **Build Steps** , choose **Add build step** , and then choose **Amazon Inspector Scan**. @@ -111 +145 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 2. Select an **AWS Region** to send the scan request through. + 2. For **Inspector-sbomgen Installation Method** , choose one of the following: @@ -113 +147 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 3. (Optional) For **Report Artifact Name** , enter a custom name for the artifacts generated during the build process. This helps uniquely identify and manage them. + * **Automatic** – The plugin downloads the latest version of the Amazon Inspector SBOM Generator at the start of each build. The Jenkins controller must run Linux and be able to reach `amazon-inspector-sbomgen.s3.amazonaws.com` over HTTPS. @@ -115 +149 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 4. (Optional) For **Skip files** , specify one or more directories you want to exclude from scanning. Consider this option for directories that do not need to be scanned due to size. + * **Manual** – Enter the full path to an `inspector-sbomgen` binary that you downloaded, such as `/opt/inspector/inspector-sbomgen`. Choose this option to use a specific version of the Amazon Inspector SBOM Generator, or if the Jenkins controller can't download it. The plugin checks the path on the Jenkins controller, but runs the binary on the machine that runs the build. If these are different machines, put the binary at the same path on both. For download links, see [Installing Sbomgen](./sbom-generator.html#install-sbomgen). @@ -117 +151 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 5. (Optional) For **Docker credentials** , select your Docker username. Do this only if your container image is in a private repository. + 3. For **Image ID** , enter the image to scan. The image can be local, remote, or archived, and its name must follow the Docker naming convention: @@ -119 +153 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 6. (Optional) You can provide the following supported AWS authentication methods: + * For a local or remote image: `NAME[:TAG|@DIGEST]` @@ -121 +155 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 1. (Optional) For **IAM role** , provide a role ARN (arn:aws:iam::`AccountNumber`:role/`RoleName`). + * For an image exported to a tar file: `/path/to/image.tar` @@ -123 +157 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 2. (Optional) For **AWS credentials** , specify AWS credentials to authenticate based on an IAM user. + 4. (Optional) For **Report Artifact Name** , enter a prefix for the file name of the SBOM that the build archives. The default is `default-report`. The name can contain up to 255 letters, numbers, periods (.), underscores (_), and hyphens (-). @@ -125 +159 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 3. (Optional) For **AWS profile name** , provide the name of a profile to authenticate using a profile name. + 5. (Optional) For **Skip Files** , enter the files and directories to exclude from the scan, one per line or separated by commas without spaces. Consider this option for large directories that don't need to be scanned. @@ -127 +161 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 7. (Optional) Select **Enable vulnerability thresholds**. With this option, you can determine whether your build fails if a scanned vulnerability exceeds a value. If all values equal `0`, the build succeeds, regardless of how many vulnerabilities are scanned. For the EPSS score, the value can be from 0 to 1. If a scanned vulnerability exceeds a value, the build fails, and all CVEs with an EPSS score above the value show in the console. + 6. (Optional) For **Docker Credentials** , choose the credentials that you added in Step 3. @@ -129 +163 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] - 4. Choose **Save**. + 7. For **AWS Region** , choose the Region to send the scan request to. @@ -130,0 +165 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] + 8. Under **AWS Authentication Options (Choose One)** , configure one of the following options. If you leave all of them empty, the plugin uses the default credential provider chain on the Jenkins controller. @@ -131,0 +167 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] + * For **IAM Role** , enter the Amazon Resource Name (ARN) of the role that you created in Step 1, such as `arn:aws:iam::`111122223333`:role/`InspectorCICDscan-role``. To assume the role with OIDC, also choose the credential that you added in Step 4 for **OIDC Credentials**. @@ -132,0 +169 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] + * For **AWS Credentials** , choose the access key that you added in Step 4. @@ -134 +171 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] -### Add Amazon Inspector Scan to your build using the Jenkins declarative pipeline + * For **AWS Profile Name** , enter the name of a profile on the Jenkins controller. @@ -136 +173 @@ For more information, see [Installing Amazon Inspector SBOM Generator (Sbomgen)] -You can add Amazon Inspector Scan to your build using the Jenkins declarative pipeline automatically or manually. +If you configure more than one option, the plugin uses the first one in this order: **AWS Credentials** , **IAM Role** with **OIDC Credentials** , **IAM Role** , and then **AWS Profile Name**. @@ -138 +175 @@ You can add Amazon Inspector Scan to your build using the Jenkins declarative pi -###### To automatically download the SBOMGen declarative pipeline + 9. (Optional) Under **Scan Output Filters** , choose the checks that can fail the build. For a description of each option, see Scan output filters. @@ -140 +177 @@ You can add Amazon Inspector Scan to your build using the Jenkins declarative pi - * To add Amazon Inspector Scan to a build, use the following example syntax. Replace `IMAGE_PATH` with the path to your image (such as `alpine:latest`), `IAM_ROLE` with the ARN of the IAM role you configured in step 1, and `ID` with your Docker credential ID if you are using a private repository. You can optionally enable vulnerability thresholds and specify values for each severity. + 10. Choose **Save**. @@ -144,0 +182,4 @@ You can add Amazon Inspector Scan to your build using the Jenkins declarative pi +### Add Amazon Inspector Scan to a Jenkins pipeline +