add some util functions

Author: anthony-nhs

packages/cdkConstructs/src/index.ts

@@ -2,3 +2,4 @@
 export * from "./constructs/TypescriptLambdaFunction.js"
 export * from "./apps/createApp.js"
 export * from "./config/index.js"
+export * from "./utils/helpers.js"

packages/cdkConstructs/src/utils/helpers.ts

@@ -0,0 +1,128 @@
+import {Stack, CfnResource} from "aws-cdk-lib"
+import {NagPackSuppression, NagSuppressions} from "cdk-nag"
+import {IConstruct} from "constructs"
+
+/**
+ * Locate CloudFormation resources by their synthesized `aws:cdk:path` metadata.
+ *
+ * Use this helper when logical IDs vary between synths but the fully-qualified
+ * construct path is stable (for example when targeting resources for nag
+ * suppressions).
+ *
+ * @param construct - Root construct that will be walked recursively.
+ * @param paths - One or more fully qualified `aws:cdk:path` strings to match.
+ * @returns Every resource whose metadata path equals one of the supplied paths.
+ */
+export function findCloudFormationResourcesByPath(construct: IConstruct, paths: Array<string>): Array<CfnResource> {
+  const matches: Array<CfnResource> = []
+  const targetPaths = new Set(paths)
+  const seen = new Set<string>()
+  const search = (node: IConstruct): void => {
+    if (node instanceof CfnResource) {
+      const resourcePath = node.cfnOptions.metadata?.["aws:cdk:path"]
+      if (typeof resourcePath === "string" && targetPaths.has(resourcePath) && !seen.has(node.logicalId)) {
+        matches.push(node)
+        seen.add(node.logicalId)
+      }
+    }
+    for (const child of node.node.children) {
+      search(child)
+    }
+  }
+  search(construct)
+  return matches
+}
+
+/**
+ * Locate CloudFormation resources by CloudFormation type.
+ *
+ * Recursively traverses the construct tree and returns all `CfnResource`
+ * instances that match the provided `AWS::<Service>::<Resource>` type string.
+ *
+ * @param construct - Root construct to traverse.
+ * @param type - CloudFormation type identifier (for example `AWS::Lambda::Function`).
+ * @returns All resources whose `cfnResourceType` matches `type`.
+ */
+export function findCloudFormationResourcesByType(construct: IConstruct, type: string): Array<CfnResource> {
+  const matches: Array<CfnResource> = []
+  const search = (node: IConstruct): void => {
+    if (node instanceof CfnResource && node.cfnResourceType === type) {
+      matches.push(node)
+    }
+    for (const child of node.node.children) {
+      search(child)
+    }
+  }
+  search(construct)
+  return matches
+}
+/**
+ * Merge cfn-guard rule suppressions onto the provided resources.
+ *
+ * Ensures the metadata structure exists, deduplicates rule IDs, and leaves any
+ * pre-existing suppressions intact.
+ *
+ * @param resources - CloudFormation resources that require suppressions.
+ * @param rules - One or more cfn-guard rule identifiers to suppress.
+ */
+export function addSuppressions(resources: Array<CfnResource>, rules: Array<string>): void {
+  resources.forEach(resource => {
+    if (!resource.cfnOptions.metadata) {
+      resource.cfnOptions.metadata = {}
+    }
+    const existing = resource.cfnOptions.metadata.guard?.SuppressedRules || []
+    const combined = Array.from(new Set([...existing, ...rules]))
+    resource.cfnOptions.metadata.guard = {SuppressedRules: combined}
+  })
+}
+
+/**
+ * Apply the default lambda-focused cfn-guard suppressions.
+ *
+ * Finds every `AWS::Lambda::Function` in the stack and suppresses the common
+ * Lambda guard rules related to DLQ usage, VPC placement, and reserved concurrency.
+ *
+ * @param stack - Stack containing the Lambda resources to update.
+ */
+export function addLambdaCfnGuardSuppressions(stack: Stack): void {
+  const allLambdas = findCloudFormationResourcesByType(stack, "AWS::Lambda::Function")
+  addSuppressions(allLambdas, ["LAMBDA_DLQ_CHECK", "LAMBDA_INSIDE_VPC", "LAMBDA_CONCURRENCY_CHECK"])
+}
+
+/**
+ * Attach identical nag suppressions to several construct paths.
+ *
+ * Invokes `safeAddNagSuppression` for each path, allowing missing paths to be
+ * skipped without failing the entire operation.
+ *
+ * @param stack - CDK stack that contains the constructs.
+ * @param paths - Paths to apply the suppression group to.
+ * @param suppressions - Suppression definitions shared by all targets.
+ * The suppressions must include id and reason and can optionally include appliesTo.
+ */
+export function safeAddNagSuppressionGroup(
+  stack: Stack,
+  paths: Array<string>,
+  suppressions: Array<NagPackSuppression>
+) {
+  paths.forEach(path => safeAddNagSuppression(stack, path, suppressions))
+}
+
+/**
+ * Attach nag suppressions to a single construct path.
+ *
+ * Wraps `NagSuppressions.addResourceSuppressionsByPath` and logs an info-level
+ * message when the path cannot be resolved, preventing build failures in
+ * partially synthesized stacks.
+ *
+ * @param stack - CDK stack that contains the construct.
+ * @param path - Fully qualified CDK path to the resource.
+ * @param suppressions - Suppression entries to apply.
+ */
+export function safeAddNagSuppression(stack: Stack, path: string, suppressions: Array<NagPackSuppression>) {
+  try {
+    NagSuppressions.addResourceSuppressionsByPath(stack, path, suppressions)
+  } catch (err) {
+    console.log(`Could not find path ${path}: ${err}`)
+  }
+}

packages/cdkConstructs/tests/utils/helpers.test.ts

@@ -0,0 +1,131 @@
+import {
+  afterEach,
+  describe,
+  expect,
+  test,
+  vi
+} from "vitest"
+import {Stack, CfnResource} from "aws-cdk-lib"
+import {Code, Function as LambdaFunction, Runtime} from "aws-cdk-lib/aws-lambda"
+import {NagPackSuppression, NagSuppressions} from "cdk-nag"
+
+import * as helpers from "../../src/utils/helpers"
+
+const defaultSuppressionRules = ["LAMBDA_DLQ_CHECK", "LAMBDA_INSIDE_VPC", "LAMBDA_CONCURRENCY_CHECK"]
+
+const createResource = (stack: Stack, id: string, type = "Custom::Test", path?: string): CfnResource => {
+  const resource = new CfnResource(stack, id, {type, properties: {}})
+  resource.cfnOptions.metadata = {
+    ...(resource.cfnOptions.metadata ?? {}),
+    "aws:cdk:path": path ?? `${stack.stackName}/${id}`
+  }
+  return resource
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe("findCloudFormationResourcesByPath", () => {
+  test("returns unique matches for the provided metadata paths", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    const first = createResource(stack, "First", "Custom::Foo", "match/one")
+    const second = createResource(stack, "Second", "Custom::Foo", "match/two")
+    createResource(stack, "Third", "Custom::Foo", "nope")
+
+    const matches = helpers.findCloudFormationResourcesByPath(stack, ["match/one", "match/one", "match/two"])
+
+    expect(matches).toEqual([first, second])
+  })
+})
+
+describe("findCloudFormationResourcesByType", () => {
+  test("returns every resource whose CloudFormation type matches", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    const fooOne = createResource(stack, "FooOne", "Custom::Foo")
+    const fooTwo = createResource(stack, "FooTwo", "Custom::Foo")
+    createResource(stack, "Bar", "Custom::Bar")
+
+    const matches = helpers.findCloudFormationResourcesByType(stack, "Custom::Foo")
+
+    expect(matches).toEqual([fooOne, fooTwo])
+  })
+})
+
+describe("addSuppressions", () => {
+  test("merges new rules, deduplicates them, and creates metadata when missing", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    const existing = createResource(stack, "Existing")
+    existing.cfnOptions.metadata = {
+      ...existing.cfnOptions.metadata,
+      guard: {SuppressedRules: ["EXISTING", "SHARED"]}
+    }
+    const empty = createResource(stack, "Empty")
+
+    helpers.addSuppressions([existing, empty], ["SHARED", "NEW"])
+
+    expect(existing.cfnOptions.metadata?.guard?.SuppressedRules).toEqual(["EXISTING", "SHARED", "NEW"])
+    expect(empty.cfnOptions.metadata?.guard?.SuppressedRules).toEqual(["SHARED", "NEW"])
+  })
+})
+
+describe("addLambdaCfnGuardSuppressions", () => {
+  test("applies the default lambda suppressions to every lambda in the stack", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    const lambdaOne = new LambdaFunction(stack, "LambdaOne", {
+      runtime: Runtime.NODEJS_18_X,
+      handler: "index.handler",
+      code: Code.fromInline("exports.handler = async () => {};")
+    })
+    const lambdaTwo = new LambdaFunction(stack, "LambdaTwo", {
+      runtime: Runtime.NODEJS_18_X,
+      handler: "index.handler",
+      code: Code.fromInline("exports.handler = async () => {};")
+    })
+
+    helpers.addLambdaCfnGuardSuppressions(stack)
+
+    const firstCfn = lambdaOne.node.defaultChild as CfnResource
+    const secondCfn = lambdaTwo.node.defaultChild as CfnResource
+    expect(firstCfn.cfnOptions.metadata?.guard?.SuppressedRules).toEqual(defaultSuppressionRules)
+    expect(secondCfn.cfnOptions.metadata?.guard?.SuppressedRules).toEqual(defaultSuppressionRules)
+  })
+})
+
+describe("safeAddNagSuppressionGroup", () => {
+  test("invokes cdk-nag for every provided path", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    const suppressions: Array<NagPackSuppression> = [{id: "RULE", reason: "already covered"}]
+    const spy = vi.spyOn(NagSuppressions, "addResourceSuppressionsByPath").mockImplementation(() => {})
+
+    helpers.safeAddNagSuppressionGroup(stack, ["one", "two"], suppressions)
+
+    expect(spy).toHaveBeenCalledTimes(2)
+    expect(spy).toHaveBeenNthCalledWith(1, stack, "one", suppressions)
+    expect(spy).toHaveBeenNthCalledWith(2, stack, "two", suppressions)
+  })
+})
+
+describe("safeAddNagSuppression", () => {
+  const sampleSuppressions: Array<NagPackSuppression> = [{id: "RULE", reason: "covered elsewhere"}]
+
+  test("routes suppressions to cdk-nag", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    const spy = vi.spyOn(NagSuppressions, "addResourceSuppressionsByPath").mockImplementation(() => {})
+
+    helpers.safeAddNagSuppression(stack, "path/to/resource", sampleSuppressions)
+
+    expect(spy).toHaveBeenCalledWith(stack, "path/to/resource", sampleSuppressions)
+  })
+
+  test("logs and swallows errors when the target path cannot be resolved", () => {
+    const stack = new Stack(undefined, "HelpersTestStack")
+    vi.spyOn(NagSuppressions, "addResourceSuppressionsByPath").mockImplementation(() => {
+      throw new Error("missing")
+    })
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+
+    expect(() => helpers.safeAddNagSuppression(stack, "missing/path", sampleSuppressions)).not.toThrow()
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("missing/path"))
+  })
+})