@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.91

package/docs/snippets/rdb/deploying.mdx

@@ -0,0 +1,178 @@
+---
+title: Deploying your Relational Database
+---
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+import Drawer from '@components/drawer.astro';
+
+The relational database generator creates CDK or Terraform infrastructure based on your selected `iac`.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The CDK construct is created in `common/constructs`. Example usage:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+    ...
+    const db = new MyDatabase(this, 'Db', {
+      vpc,
+      vpcSubnets: {
+        subnetType: SubnetType.PRIVATE_ISOLATED,
+      }
+    });
+  }
+}
+```
+
+This provisions an Aurora cluster with RDS Proxy, admin credentials, application database user, runtime config registration, and migration handler.
+
+The generated infrastructure creates two database users:
+- **Admin user** - Created during cluster provisioning with credentials stored in AWS Secrets Manager
+- **Application user** - Created via a Lambda custom resource with IAM authentication enabled and DML privileges (SELECT, INSERT, UPDATE, DELETE) on the application database
+</Fragment>
+<Fragment slot="terraform">
+The Terraform module is created in `common/terraform`. Example usage:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+
+  # Database subnets have no internet route; Lambda subnets need NAT egress.
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
+
+  tags = local.common_tags
+}
+```
+
+This provisions an Aurora cluster with RDS Proxy, admin credentials, create-db-user Lambda, runtime config registration, migration Lambda, and container registry resources.
+
+The database module registers its connection details under the `database` <Link path="guides/runtime-config">runtime configuration</Link> namespace, which the shared runtime configuration AppConfig application exposes by default.
+
+The generated infrastructure creates two database users:
+- **Admin user** - Created during cluster provisioning with credentials stored in AWS Secrets Manager
+- **Application user** - Created via a Lambda function with IAM authentication enabled and DML privileges (SELECT, INSERT, UPDATE, DELETE) on the application database
+</Fragment>
+</Infrastructure>
+
+The application user is automatically created with a random name and IAM authentication. The generated database client is already configured to authenticate as this user using short-lived RDS tokens, so your application code never handles database passwords.
+
+Your VPC should include public subnets, private subnets with egress, and private isolated subnets. The database can run in private isolated subnets, while application Lambda functions should run in private subnets with egress so they can reach AWS services such as AppConfig.
+
+<Drawer title="Example VPC configuration" trigger="Click here for an example VPC configuration.">
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+const vpc = new Vpc(this, 'Vpc', {
+  subnetConfiguration: [
+    {
+      name: 'public',
+      subnetType: SubnetType.PUBLIC,
+    },
+    {
+      name: 'private_with_egress',
+      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
+    },
+    {
+      name: 'private_isolated',
+      subnetType: SubnetType.PRIVATE_ISOLATED,
+    },
+  ],
+});
+```
+
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+data "aws_availability_zones" "available" {
+  state = "available"
+}
+
+resource "aws_vpc" "main" {
+  cidr_block           = "10.0.0.0/16"
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+}
+
+# Isolated subnets for the database: no route to the internet
+resource "aws_subnet" "database" {
+  count             = 2
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index)
+  availability_zone = data.aws_availability_zones.available.names[count.index]
+}
+
+# Private subnets with NAT egress for Lambda functions and runtimes,
+# so they can reach AWS services such as AppConfig
+resource "aws_subnet" "private" {
+  count             = 2
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index + 2)
+  availability_zone = data.aws_availability_zones.available.names[count.index]
+}
+
+# Public subnet hosting the NAT gateway
+resource "aws_subnet" "public" {
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = cidrsubnet(aws_vpc.main.cidr_block, 8, 4)
+  availability_zone = data.aws_availability_zones.available.names[0]
+}
+
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+}
+
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block = "0.0.0.0/0"
+    gateway_id = aws_internet_gateway.main.id
+  }
+}
+
+resource "aws_route_table_association" "public" {
+  subnet_id      = aws_subnet.public.id
+  route_table_id = aws_route_table.public.id
+}
+
+resource "aws_eip" "nat" {
+  domain = "vpc"
+}
+
+resource "aws_nat_gateway" "main" {
+  allocation_id = aws_eip.nat.id
+  subnet_id     = aws_subnet.public.id
+  depends_on    = [aws_internet_gateway.main]
+}
+
+resource "aws_route_table" "private" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block     = "0.0.0.0/0"
+    nat_gateway_id = aws_nat_gateway.main.id
+  }
+}
+
+resource "aws_route_table_association" "private" {
+  count          = 2
+  subnet_id      = aws_subnet.private[count.index].id
+  route_table_id = aws_route_table.private.id
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+</Drawer>
+
+Use the <Link path="guides/connection">`connection`</Link> generator to connect a project to this database — see the connection guide for the relevant compute type (e.g. FastAPI, MCP server, agent) for the infrastructure wiring required to reach it.

package/docs/snippets/rdb/encryption-key-rotation.mdx

@@ -0,0 +1,30 @@
+---
+title: Encryption Key Rotation
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The KMS key used to encrypt the Aurora cluster and its credentials secret has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableKeyRotation: false,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_key_rotation = false
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/engine-version.mdx

@@ -0,0 +1,63 @@
+---
+title: Engine Version
+---
+import Infrastructure from '@components/infrastructure.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Pin a specific Aurora engine version.
+
+By default, the generated local database container image matches the default Aurora engine version. If you change the Aurora engine version, it's recommended to also use a matching local container image version for maximum compatibility. See the AWS release notes for [Aurora PostgreSQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/aurorapostgresql-release-calendar.html) and [Aurora MySQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html) to identify the corresponding community database version.
+
+The local database image is configured in the `localDev.image` field of the generated `config.json` file in your database project root. Update that value when you change engine versions.
+
+<OptionFilter when={{ engine: 'postgres' }}>
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  engineVersion: AuroraPostgresEngineVersion.VER_17_7,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  engine_version = "17.7"
+}
+```
+</Fragment>
+</Infrastructure>
+</OptionFilter>
+
+<OptionFilter when={{ engine: 'mysql' }}>
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  engineVersion: AuroraMysqlEngineVersion.VER_3_12_0,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  engine_version = "8.0.mysql_aurora.3.12.0"
+}
+```
+</Fragment>
+</Infrastructure>
+</OptionFilter>

package/docs/snippets/rdb/infrastructure.mdx

@@ -0,0 +1,35 @@
+---
+title: RDB Infrastructure
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src
+        - app
+          - dbs
+            - \<name>.ts Infrastructure specific to your database
+        - core
+          - rdb
+            - aurora.ts Generic Aurora database construct
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src
+        - app
+          - dbs
+            - \<name>
+              - \<name>.tf Module specific to your database
+        - core
+          - rdb
+            - aurora
+              - aurora.tf Generic Aurora module
+    </FileTree>
+  </Fragment>
+</Infrastructure>

package/docs/snippets/rdb/logging-mysql.mdx

@@ -0,0 +1,5 @@
+---
+title: MySQL Query Logging
+---
+
+The `audit` and `error` logs are exported for [Aurora MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Integrating.CloudWatch.html) — `general` and `slowquery` are deliberately excluded since they log full statement text, including DML values. [Advanced Auditing](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Auditing.html) is scoped to connections and DDL (`server_audit_events=CONNECT,QUERY_DDL`), so statement parameter values are never logged.

package/docs/snippets/rdb/logging-postgres.mdx

@@ -0,0 +1,5 @@
+---
+title: PostgreSQL Query Logging
+---
+
+The `postgresql` log is exported for [Aurora PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.CloudWatch.html), with logging scoped to DDL statements only (`log_statement=ddl`) so statement parameter values are never logged — as long as each statement is sent on its own. `log_statement=ddl` logs the entire raw text of a multi-statement batch (e.g. a single `psql -c "a;b;c"` call) verbatim if any statement in it is DDL, including any DML values in that same batch.

package/docs/snippets/rdb/performance-insights.mdx

@@ -0,0 +1,36 @@
+---
+title: Performance Insights
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Performance Insights is enabled on the Aurora writer instance by default (encrypted with the cluster's KMS key). Aurora engine logs are also exported to [CloudWatch Logs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_LogAccess.html) by default, configured to surface schema-level activity without leaking row data.
+
+Exported log volume — and so [CloudWatch Logs ingestion cost](https://aws.amazon.com/cloudwatch/pricing/) — scales with schema changes and connections rather than query traffic, since the log types that carry full statement text are excluded. On Aurora MySQL the `CONNECT` audit event is emitted per connection, so workloads that open a connection per request produce more than ones that pool.
+
+Disable log export per database if not required:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableCloudwatchLogs: false,
+  enablePerformanceInsights: false,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_cloudwatch_logs      = false # disable if not required
+  enable_performance_insights = false # disable if not required
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/rds-proxy.mdx

@@ -0,0 +1,50 @@
+---
+title: RDS Proxy Configuration
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The generated infrastructure includes an [RDS Proxy](https://aws.amazon.com/rds/proxy/) by default, which sits between your application and the Aurora cluster. RDS Proxy provides several benefits:
+
+- **Connection pooling** - Maintains a pool of database connections that can be shared across application instances, reducing the overhead of establishing new connections
+- **Connection resilience** - Automatically handles failovers and reconnects during Aurora instance replacements or maintenance
+- **IAM authentication** - Supports IAM-based database authentication, eliminating the need to manage database credentials in your application code
+- **Improved security** - Enforces TLS encryption for all connections
+
+:::note[Additional Cost]
+RDS Proxy is enabled by default but incurs additional charges on top of the Aurora cluster cost. See [AWS RDS Proxy pricing](https://aws.amazon.com/rds/proxy/pricing/) for details. If you would prefer to disable the proxy, see the section below.
+:::
+
+#### Disable RDS Proxy
+
+You can disable the RDS proxy as follows:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableRdsProxy: false,
+});
+```
+
+When RDS Proxy is disabled, your application connects directly to the Aurora cluster endpoint.
+</Fragment>
+<Fragment slot="terraform">
+
+By default, RDS Proxy is enabled. You can disable it if needed:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_rds_proxy = false
+}
+```
+
+When RDS Proxy is disabled, your application connects directly to the Aurora cluster endpoint.
+</Fragment>
+</Infrastructure>
+

package/docs/snippets/rdb/removal-policy.mdx

@@ -0,0 +1,57 @@
+---
+title: Removal Policy
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The CDK construct retains the Aurora cluster by default (`removalPolicy: RemovalPolicy.RETAIN`). Change this when you want CDK stack deletion to snapshot or destroy the cluster instead.
+
+When using `RemovalPolicy.DESTROY`, deletion protection must also be disabled before the cluster can be deleted.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  removalPolicy: RemovalPolicy.SNAPSHOT,
+});
+```
+
+For an ephemeral environment where the database should be deleted with the stack:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  deletionProtection: false,
+  removalPolicy: RemovalPolicy.DESTROY,
+});
+```
+
+::::caution[Data Loss]
+`RemovalPolicy.DESTROY` will permanently erase all data when the stack is deleted. Use only in ephemeral environments (such as automated tests). Use `RETAIN` or `SNAPSHOT` for all persistent and production stacks to prevent data loss.
+::::
+</Fragment>
+<Fragment slot="terraform">
+
+Terraform does not use CDK removal policies. By default, the module creates a final snapshot on deletion (`skip_final_snapshot = false`). To skip the final snapshot for an ephemeral environment:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  deletion_protection = false
+  skip_final_snapshot = true
+}
+```
+
+::::caution[Data Loss]
+`skip_final_snapshot = true` will permanently erase all data when the cluster is deleted. Use only in ephemeral environments (such as automated tests). Keep `skip_final_snapshot = false` for all persistent and production stacks to prevent data loss.
+::::
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/serverless-capacity.mdx

@@ -0,0 +1,32 @@
+---
+title: Serverless Capacity
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Control Aurora Serverless v2 scaling limits to match your workload. Both providers default to a minimum of 0.5 ACUs and a maximum of 4.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  serverlessV2MinCapacity: 0.5,
+  serverlessV2MaxCapacity: 8,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  serverless_min_capacity = 0.5
+  serverless_max_capacity = 8
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/recommended-prerequisites.mdx

@@ -0,0 +1,10 @@
+---
+title: Recommended Prerequisites
+---
+- [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
+  - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version`
+- [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account are required to deploy your application (as well as for some local development workflows).
+- [Docker](https://www.docker.com/) or [Finch >= 1.6.0](https://runfinch.com/) is required for some generators. For Docker, [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up; Finch supports [multi-platform builds](https://runfinch.com/docs/getting-started/building-images/#building-a-multi-architecture-container-image) out of the box.
+- [Terraform >= 1.12](https://developer.hashicorp.com/terraform/install) is required if you choose to use this for infrastructure as code instead of CDK
+  - verify by running `terraform --version`
+- If you are using [VSCode](https://code.visualstudio.com/), we recommend installing the [Nx Console VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console).

package/docs/snippets/required-prerequisites.mdx

@@ -4,9 +4,6 @@ title: Required Prerequisites
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 - [Node >= 22](https://nodejs.org/en/download) (We recommend using something like [NVM](https://github.com/nvm-sh/nvm) to manage your node versions)
   - verify by running `node --version`
-- [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
-  - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version`
 - [UV >= 0.5.29](https://docs.astral.sh/uv/getting-started/installation/)
   1. install Python 3.14 by running: `uv python install 3.14.0`
-  2. verify with `uv python list --only-installed`
-- [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account (where your application will be deployed)
+  2. verify with `uv python list --only-installed`

package/docs/snippets/runtime-config-app-id-note.mdx

@@ -0,0 +1,8 @@
+---
+title: Runtime Config App ID Note
+---
+import Link from '@components/link.astro';
+
+:::note[Runtime config]
+This relies on the `RUNTIME_CONFIG_APP_ID` environment variable to fetch configuration from AWS AppConfig at runtime. Projects built with this plugin (APIs, Agents, MCP servers) already have this variable configured automatically. For other projects, ensure `RUNTIME_CONFIG_APP_ID` is set in the runtime environment with the AppConfig application ID provisioned by your infrastructure. For more information, see the <Link path="guides/runtime-config">Runtime Configuration guide</Link>.
+:::

package/docs/snippets/shared-constructs.mdx

@@ -5,7 +5,7 @@ import { FileTree } from '@astrojs/starlight/components';
 import Infrastructure from '@components/infrastructure.astro';
 import Link from '@components/link.astro';
 
-Since this generator vends infrastructure as code based on your chosen `iacProvider`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
+Since this generator vends infrastructure as code based on your chosen `iac`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
 
 The common infrastructure as code project is structured as follows:
 

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

@@ -0,0 +1,37 @@
+---
+title: Container Image Scanning
+---
+
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+
+The Docker image built for this project can be scanned for vulnerabilities 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 **exits non-zero** 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. The scan is not cached, since the image it reads lives in the container engine rather than on disk — so it always scans the real image, and fails loudly rather than reporting a cached pass for an image that is no longer there. Each run therefore takes tens of seconds per image and refreshes Trivy's vulnerability database, so it needs network access. The vended `trivy` root script scans every image in the workspace:
+
+<PackageManagerShortCommand commands={['trivy']} />
+
+:::tip[Run Trivy in CI]
+The scan is intentionally not wired into `build` since this can introduce unnecessary friction when iterating during development, as Trivy's vulnerabilty database is continually updated with new CVEs.
+
+Instead we recommend running the above command as a dedicated step in your CI pipeline prior to deployment to production stages.
+:::
+
+:::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).