@aws/nx-plugin-mcp 1.0.0-rc.38 → 1.0.0-rc.39

package/bin/aws-nx-mcp.js

@@ -21388,6 +21388,7 @@ const NX_VERSION = {
 	"make-dir-cli": "4.0.0",
 	mariadb: "3.5.3",
 	ncp: "2.0.0",
+	npm: "12.0.1",
 	"npm-check-updates": "22.2.9",
 	"oidc-client-ts": "3.5.0",
 	pg: "8.22.0",

package/docs/guides/docker-bundling.mdx

@@ -3,10 +3,34 @@ title: Docker Bundling
 description: Build and deploy Docker images for TypeScript and Python projects in an Nx Plugin for AWS workspace.
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, Code } from '@astrojs/starlight/components';
 import NxCommands from '@components/nx-commands.astro';
 import Link from '@components/link.astro';
 import Infrastructure from '@components/infrastructure.astro';
+import TrivyVersion from '@components/trivy-version.astro';
+import { CONTAINER_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
+
+export const trivyTarget = `{
+  "targets": {
+    "trivy": {
+      "cache": true,
+      "inputs": ["default", "^production"],
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": [
+          "rimraf dist/packages/my-project/trivy",
+          "make-dir dist/packages/my-project/trivy",
+          "ncp packages/my-project/.trivyignore dist/packages/my-project/trivy/.trivyignore",
+          "docker save -o dist/packages/my-project/trivy/image.tar my-scope-my-project:latest",
+          "docker run --rm -v \\"./dist/packages/my-project/trivy\\":/scan public.ecr.aws/aquasecurity/trivy:${CONTAINER_VERSIONS.trivy} image --input /scan/image.tar --ignorefile /scan/.trivyignore --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q"
+        ],
+        "parallel": false
+      },
+      "dependsOn": ["docker"]
+    }
+  }
+}`;
 
 Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">FastAPI</Link> project on Amazon ECS, or deploying a containerised Express server.
 
@@ -253,6 +277,36 @@ This clears the output directory, then copies both the bundle contents and the `
 
 <NxCommands commands={['docker my-project']} />
 
+## Scanning Images with Trivy
+
+It's good practice to scan your images for known vulnerabilities. The generators that follow this pattern add a `trivy` target which scans the built image with [Trivy](https://trivy.dev/), running from the [ECR-hosted Trivy image](https://gallery.ecr.aws/aquasecurity/trivy), and fails the build on `HIGH` or `CRITICAL` findings.
+
+Add a `trivy` target which `dependsOn` your `docker` target. It saves the built image to a tarball and scans it via a workspace-relative bind mount, so the same command works under both `docker` and `finch`:
+
+<Code lang="json" code={trivyTarget} />
+
+Then make `build` depend on `trivy` so the scan runs as part of a build:
+
+```json
+{
+  "targets": {
+    "build": {
+      "dependsOn": ["trivy"]
+    }
+  }
+}
+```
+
+<NxCommands commands={['trivy my-project']} />
+
+:::tip[Caching skips unchanged images]
+Because the image is fully determined by your project source, declaring `inputs` (here `default` and `^production`, matching the `bundle` target) lets Nx cache the scan and skip re-scanning an image that hasn't changed. Pin the Trivy image version (e.g. <code>trivy:<TrivyVersion /></code>) so scans are reproducible.
+:::
+
+:::note[Suppressing findings]
+Trivy reads a `.trivyignore` file (a list of vulnerability IDs, one per line) from the root of your project. `--ignore-unfixed` skips vulnerabilities with no available fix, so the scan only fails on issues you can action by upgrading tooling in your `Dockerfile`. See the [Trivy filtering documentation](https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids) for details.
+:::
+
 ## Infrastructure
 
 Wiring the resulting build-context directory to infrastructure as code is the same for both TypeScript and Python — only the path to the build-context directory differs (`dist/packages/my-project/bundle` for TypeScript, `dist/packages/my-project/docker` for Python).

package/docs/guides/py-agent.mdx

@@ -475,6 +475,10 @@ In order to build your Agent for Bedrock AgentCore Runtime, a `bundle` target is
 
 A `docker` target specific to your Agent is also added, which copies the `Dockerfile` and bundled artifacts into a docker context directory. This co-locates the `Dockerfile` with the built output, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.

package/docs/guides/py-mcp-server.mdx

@@ -171,6 +171,10 @@ In order to build your MCP server for Bedrock AgentCore Runtime, a `bundle` targ
 
 A `docker` target specific to your MCP server is also added, which copies the `Dockerfile` and bundled artifacts into a docker context directory. This co-locates the `Dockerfile` with the built output, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 <Snippet name="mcp/observability" parentHeading="Observability" />

package/docs/guides/py-rdb.mdx

@@ -153,6 +153,10 @@ The database client automatically:
 
 <Snippet name="rdb/deploying" parentHeading="Deploying your Database" />
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### RDS Proxy Configuration
 
 <Snippet name="rdb/rds-proxy" parentHeading="RDS Proxy Configuration" />

package/docs/guides/ts-agent.mdx

@@ -336,6 +336,10 @@ The generator configures a `<your-agent-name>-docker` target which copies the `D
 
 A `docker` target is also generated which prepares the docker context for all agents if you have multiple defined.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.

package/docs/guides/ts-mcp-server.mdx

@@ -178,6 +178,10 @@ The generator configures a `<your-server-name>-docker` target which copies the `
 
 A `docker` target is also generated which prepares the docker context for all MCP servers if you have multiple defined.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 <Snippet name="mcp/observability" parentHeading="Observability" />

package/docs/guides/ts-rdb.mdx

@@ -187,6 +187,10 @@ The Prisma client exposes fully typed models derived from your `prisma/models/`
 
 <Snippet name="rdb/deploying" parentHeading="Deploying your Database" />
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### RDS Proxy Configuration
 
 <Snippet name="rdb/rds-proxy" parentHeading="RDS Proxy Configuration" />

package/docs/snippets/trivy-image-scan.mdx

@@ -0,0 +1,27 @@
+---
+title: Container Image Scanning
+---
+
+The Docker image built for this project is scanned for vulnerabilities as part of the build using [Trivy](https://trivy.dev/), running from the [ECR-hosted Trivy image](https://gallery.ecr.aws/aquasecurity/trivy).
+
+A `trivy` target is added to your project which scans the built image and **fails the build** if any `HIGH` or `CRITICAL` severity vulnerability is found. The generated `Dockerfile` uses a base image with no known fixable vulnerabilities of these severities at time of generation, and upgrades bundled tooling (such as `npm`) to keep it that way.
+
+The scan uses the same container engine as your image build (`docker` or `finch`), so no additional tooling is required. Since the scan is only re-run when the image changes, an unchanged image is not re-scanned.
+
+:::caution[Unfixable vulnerabilities are ignored]
+The scan runs with `--ignore-unfixed`, so vulnerabilities without an available fix do not fail the build, since they cannot be actioned by upgrading tooling in your `Dockerfile` — they are not reported in the build's scan output. As new vulnerabilities are disclosed the result of scans may change over time, so review the image periodically by running `trivy image <your-image>` without the flag, and rebuild against a newer base image (or add container steps to apply available patches) once a fix is published.
+:::
+
+#### Suppressing Trivy Findings
+
+There may be instances where you want to suppress a specific vulnerability, for example when no fix is yet available and you have assessed the risk as acceptable.
+
+Add the vulnerability ID (one per line) to the `.trivyignore` file in the root of your project (i.e. next to your `project.json`):
+
+```gitignore
+# .trivyignore
+# node-tar arbitrary file write - not exploitable in our usage
+CVE-2024-XXXXX
+```
+
+For more details on filtering findings, refer to the [Trivy filtering documentation](https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.38",
+  "version": "1.0.0-rc.39",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",