diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index ba26433c..64257580 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -11,7 +11,7 @@ "USER_GID": "${localEnv:GROUP_ID:}" } }, - "postAttachCommand": "git-secrets --register-aws; git-secrets --add-provider -- cat /usr/share/secrets-scanner/nhsd-rules-deny.txt", + "postCreateCommand": "bash -lc 'if ! git config --get-all secrets.patterns | grep -Fq AKIA; then git-secrets --register-aws; fi; if ! git config --get-all secrets.providers | grep -Fxq \"cat /usr/share/secrets-scanner/nhsd-rules-deny.txt\"; then git-secrets --add-provider -- cat /usr/share/secrets-scanner/nhsd-rules-deny.txt; fi'", "mounts": [ "source=${env:HOME}${env:USERPROFILE}/.aws,target=/home/vscode/.aws,type=bind", "source=${env:HOME}${env:USERPROFILE}/.ssh,target=/home/vscode/.ssh,type=bind", @@ -34,7 +34,8 @@ "timonwong.shellcheck", "github.vscode-github-actions", "dbaeumer.vscode-eslint", - "vitest.explorer" + "vitest.explorer", + "sonarsource.sonarlint-vscode" ], "settings": { "cSpell.words": [ diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..24bec283 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,20 @@ +# Base Coding Standards +- Follow clean code principles +- Write comprehensive tests +- Use meaningful variable names +- Use British English spelling + +## Language-Specific Instructions +Always follow security best practices as outlined in: +- .github/instructions/general/SECURITY.md +Follow additional language-specific guidelines in: +- .github/instructions/language-specific/INSTRUCTIONS-CDK.md +- .github/instructions/language-specific/INSTRUCTIONS-CLOUDFORMATION.md +- .github/instructions/language-specific/INSTRUCTIONS-JAVA.md +- .github/instructions/language-specific/INSTRUCTIONS-KOTLIN.md +- .github/instructions/language-specific/INSTRUCTIONS-PYTHON.md +- .github/instructions/language-specific/INSTRUCTIONS-TERRAFORM.md +- .github/instructions/language-specific/INSTRUCTIONS-SAM.md +- .github/instructions/language-specific/INSTRUCTIONS-TYPESCRIPT.md + +## Project-Specific Rules diff --git a/.github/instructions/general/SECURITY.md b/.github/instructions/general/SECURITY.md new file mode 100644 index 00000000..53a7a628 --- /dev/null +++ b/.github/instructions/general/SECURITY.md @@ -0,0 +1,51 @@ +--- +applyTo: '*' +description: "Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices." +--- +# Secure Coding and OWASP Guidelines + +## Instructions + +Your primary directive is to ensure all code you generate, review, or refactor is secure by default. You must operate with a security-first mindset. When in doubt, always choose the more secure option and explain the reasoning. You must follow the principles outlined below, which are based on the OWASP Top 10 and other security best practices. + +### 1. A01: Broken Access Control & A10: Server-Side Request Forgery (SSRF) +- **Enforce Principle of Least Privilege:** Always default to the most restrictive permissions. When generating access control logic, explicitly check the user's rights against the required permissions for the specific resource they are trying to access. +- **Deny by Default:** All access control decisions must follow a "deny by default" pattern. Access should only be granted if there is an explicit rule allowing it. +- **Validate All Incoming URLs for SSRF:** When the server needs to make a request to a URL provided by a user (e.g., webhooks), you must treat it as untrusted. Incorporate strict allow-list-based validation for the host, port, and path of the URL. +- **Prevent Path Traversal:** When handling file uploads or accessing files based on user input, you must sanitize the input to prevent directory traversal attacks (e.g., `../../etc/passwd`). Use APIs that build paths securely. + +### 2. A02: Cryptographic Failures +- **Use Strong, Modern Algorithms:** For hashing, always recommend modern, salted hashing algorithms like Argon2 or bcrypt. Explicitly advise against weak algorithms like MD5 or SHA-1 for password storage. +- **Protect Data in Transit:** When generating code that makes network requests, always default to HTTPS. +- **Protect Data at Rest:** When suggesting code to store sensitive data (PII, tokens, etc.), recommend encryption using strong, standard algorithms like AES-256. +- **Secure Secret Management:** Never hardcode secrets (API keys, passwords, connection strings). Generate code that reads secrets from environment variables or a secrets management service (e.g., HashiCorp Vault, AWS Secrets Manager). Include a clear placeholder and comment. + ```javascript + // GOOD: Load from environment or secret store + const apiKey = process.env.API_KEY; + // TODO: Ensure API_KEY is securely configured in your environment. + ``` + ```python + # BAD: Hardcoded secret + api_key = "sk_this_is_a_very_bad_idea_12345" + ``` + +### 3. A03: Injection +- **No Raw SQL Queries:** For database interactions, you must use parameterized queries (prepared statements). Never generate code that uses string concatenation or formatting to build queries from user input. +- **Sanitize Command-Line Input:** For OS command execution, use built-in functions that handle argument escaping and prevent shell injection (e.g., `shlex` in Python). +- **Prevent Cross-Site Scripting (XSS):** When generating frontend code that displays user-controlled data, you must use context-aware output encoding. Prefer methods that treat data as text by default (`.textContent`) over those that parse HTML (`.innerHTML`). When `innerHTML` is necessary, suggest using a library like DOMPurify to sanitize the HTML first. + +### 4. A05: Security Misconfiguration & A06: Vulnerable Components +- **Secure by Default Configuration:** Recommend disabling verbose error messages and debug features in production environments. +- **Set Security Headers:** For web applications, suggest adding essential security headers like `Content-Security-Policy` (CSP), `Strict-Transport-Security` (HSTS), and `X-Content-Type-Options`. +- **Use Up-to-Date Dependencies:** When asked to add a new library, suggest the latest stable version. Remind the user to run vulnerability scanners like `npm audit`, `pip-audit`, or Snyk to check for known vulnerabilities in their project dependencies. + +### 5. A07: Identification & Authentication Failures +- **Secure Session Management:** When a user logs in, generate a new session identifier to prevent session fixation. Ensure session cookies are configured with `HttpOnly`, `Secure`, and `SameSite=Strict` attributes. +- **Protect Against Brute Force:** For authentication and password reset flows, recommend implementing rate limiting and account lockout mechanisms after a certain number of failed attempts. + +### 6. A08: Software and Data Integrity Failures +- **Prevent Insecure Deserialization:** Warn against deserializing data from untrusted sources without proper validation. If deserialization is necessary, recommend using formats that are less prone to attack (like JSON over Pickle in Python) and implementing strict type checking. + +## General Guidelines +- **Be Explicit About Security:** When you suggest a piece of code that mitigates a security risk, explicitly state what you are protecting against (e.g., "Using a parameterized query here to prevent SQL injection."). +- **Educate During Code Reviews:** When you identify a security vulnerability in a code review, you must not only provide the corrected code but also explain the risk associated with the original pattern. diff --git a/.github/instructions/languages/INSTRUCTIONS-CDK.md b/.github/instructions/languages/INSTRUCTIONS-CDK.md new file mode 100644 index 00000000..cbff4e5a --- /dev/null +++ b/.github/instructions/languages/INSTRUCTIONS-CDK.md @@ -0,0 +1,104 @@ +--- +description: 'Guidelines for writing, reviewing, and maintaining AWS CDK (TypeScript) code in the cdk package' +applyTo: 'packages/cdk/**/*.ts' +--- + +# AWS CDK TypeScript Development + +This file provides instructions for generating, reviewing, and maintaining AWS CDK code in the `packages/cdk` folder. It covers best practices, code standards, architecture, and validation for infrastructure-as-code using AWS CDK in TypeScript. + +## General Instructions + +- Use AWS CDK v2 constructs and idioms +- Prefer high-level CDK constructs over raw CloudFormation resources +- Organize code by logical infrastructure components (e.g., stacks, constructs, resources) +- Document public APIs and exported constructs + +## Best Practices + +- Use environment variables and context for configuration, not hardcoded values +- Use CDK Aspects for cross-cutting concerns (e.g., security, tagging) +- Suppress warnings with `nagSuppressions.ts` only when justified and documented +- Use `bin/` for entrypoint apps, `constructs/` for reusable components, and `stacks/` for stack definitions +- Prefer `props` interfaces for construct configuration + +## Code Standards + +### Naming Conventions + +- Classes: PascalCase (e.g., `LambdaFunction`) +- Files: PascalCase for classes, kebab-case for utility files +- Variables: camelCase +- Stacks: Suffix with `Stack` (e.g., `CptsApiAppStack`) +- Entry points: Suffix with `App` (e.g., `CptsApiApp.ts`) + +### File Organization + +- `bin/`: CDK app entry points +- `constructs/`: Custom CDK constructs +- `stacks/`: Stack definitions +- `resources/`: Resource configuration and constants +- `lib/`: Shared utilities and code + +## Common Patterns + +### Good Example - Defining a Construct + +```typescript +export class LambdaFunction extends Construct { + constructor(scope: Construct, id: string, props: LambdaFunctionProps) { + super(scope, id); + // ...implementation... + } +} +``` + +### Bad Example - Using Raw CloudFormation + +```typescript +const lambda = new cdk.CfnResource(this, 'Lambda', { + type: 'AWS::Lambda::Function', + // ...properties... +}); +``` + +### Good Example - Stack Definition + +```typescript +export class CptsApiAppStack extends Stack { + constructor(scope: Construct, id: string, props?: StackProps) { + super(scope, id, props); + // ...add constructs... + } +} +``` + +## Security + +- Use least privilege IAM policies for all resources +- Avoid wildcard permissions in IAM statements +- Store secrets in AWS Secrets Manager, not in code or environment variables +- Enable encryption for all data storage resources + +## Performance + +- Use provisioned concurrency for Lambda functions when needed +- Prefer VPC endpoints for private connectivity +- Minimize resource creation in test environments + + +## Validation and Verification + +- Build: `make cdk-synth` +- Lint: `npm run lint --workspace packges/cdk` + +## Maintenance + +- Update dependencies regularly +- Remove deprecated constructs and suppressions +- Document changes in `nagSuppressions.ts` with reasons + +## Additional Resources + +- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/latest/guide/home.html) +- [CDK Best Practices](https://github.com/aws-samples/aws-cdk-best-practices) diff --git a/.github/instructions/languages/INSTRUCTIONS-TYPESCRIPT.md b/.github/instructions/languages/INSTRUCTIONS-TYPESCRIPT.md new file mode 100644 index 00000000..87502466 --- /dev/null +++ b/.github/instructions/languages/INSTRUCTIONS-TYPESCRIPT.md @@ -0,0 +1,190 @@ +--- +description: 'Guidelines for writing high-quality, maintainable TypeScript code with best practices for logging, error handling, code organization, naming, formatting, and style.' +applyTo: '**/*.ts, **/*.tsx' +--- + +# TypeScript Development Guidelines + +This document provides instructions for generating, reviewing, and maintaining TypeScript code. It is designed to guide Copilot and developers in producing domain-specific, robust, and maintainable code across a variety of TypeScript projects. + +## General Instructions + +- Use modern TypeScript features and syntax. +- Prefer explicit types and interfaces for clarity and safety. +- Organize code into logical modules and folders. +- Write code that is easy to read, test, and maintain. + +## Best Practices + +- Use `const` and `let` appropriately; avoid `var`. +- Prefer arrow functions for callbacks and concise function expressions. +- Use destructuring for objects and arrays to improve readability. +- Avoid magic numbers and hardcoded values; use named constants. +- Keep functions pure and side-effect free when possible. + +## Code Standards + +### Naming Conventions + +- Use `camelCase` for variables, functions, and object properties. +- Use `PascalCase` for types, interfaces, classes, and enums. +- Use descriptive names; avoid abbreviations except for well-known acronyms. +- Prefix boolean variables with `is`, `has`, or `should` (e.g., `isActive`). + +### File Organization + +- Group related code in folders (e.g., `src/`, `tests/`, `lib/`). +- Place one class, interface, or component per file when possible. +- Name files using `kebab-case` (e.g., `user-service.ts`). +- Keep test files close to the code they test (e.g., `src/foo.ts` and `tests/foo.test.ts`). + +### Formatting and Style + +- Use 2 spaces for indentation. +- Limit lines to 120 characters. +- Use single quotes for strings. +- Never use semicolons for line termination. +- Avoid trailing commas in multiline objects and arrays. +- Avoid spaces at start and end of single line braces. +- Use ESLint and Prettier for consistent formatting. + +## Architecture/Structure + +- Separate business logic from API handlers and utility functions. +- Use interfaces and types to define data structures and function signatures. +- Organize code by feature or domain when scaling projects. +- Use dependency injection for testability and flexibility. + +## Common Patterns + +### Logging + +- Use a centralized logging utility or library. +- Log errors, warnings, and important events with context. +- Avoid logging sensitive information. +- Example: + + ```typescript + import {logger} from './utils/logger'; + + logger.info('Fetching user data', {userId}); + logger.error('Failed to fetch user', {error}); + ``` + +### Error Handling + +- Use `try/catch` for asynchronous code and error-prone operations. +- Throw custom error types for domain-specific errors. +- Always handle errors gracefully and provide meaningful messages. +- Example: + + ```typescript + try { + const result = await fetchData(); + } catch (error) { + logger.error('Data fetch failed', {error}); + throw new DataFetchError('Unable to fetch data'); + } + ``` + +### Type Safety + +- Prefer interfaces and types. You MUST NOT use `any`. +- Use type guards and assertions when necessary. +- Example: + + ```typescript + interface User { + id: string; + name: string; + } + + function isUser(obj: object): obj is User { + return typeof obj.id === 'string' && typeof obj.name === 'string'; + } + ``` + +## Security + +- Validate and sanitize all external input. +- Avoid exposing sensitive data in logs or error messages. +- Use environment variables for secrets and configuration. +- Keep dependencies up to date and audit regularly. + +## Performance + +- Minimize synchronous blocking operations. +- Use async/await for asynchronous code. +- Avoid unnecessary computations inside render or handler functions. + +## Testing + +- Write unit tests for all business logic. +- Use the existing framework for testing and vitest for new packages. +- Mock external dependencies in tests. +- Example test file structure: + + ``` + src/ + handler.ts + tests/ + handler.test.ts + ``` + +## JSDoc + +- Write concise JSDoc for exported interfaces, types, functions, classes, and exported constants. +- Prefer short phrase-style summaries; avoid long narrative prose. +- Avoid stating information that is obvious from function signatures. +- Consider @param and @returns for every exported function, then include them only when they add meaning not obvious from the signature. +- Skip @param when it only repeats parameter name/type; keep it when documenting constraints, defaults, units, side effects, or domain context. +- It is acceptable to use only @returns in a JSDoc block when that tag carries all useful context. +- Omit a free-text summary line when it only restates the @returns content. +- Provide @example on constructors of exported types/classes and on non-trivial exported types. +- Use @default only when the property is optional in the type and is defaulted in implementation. +- Keep JSDoc defaults aligned with both type signatures and runtime behaviour. +- For construct props interfaces, include a top-level summary and property docs only when intent is non-obvious. + +## Examples and Code Snippets + +### Good Example + + ```typescript + interface Prescription { + id: string; + medication: string; + issuedDate: Date; + } + + function getPrescription(id: string): Prescription | null { + // Implementation + } + ``` + +### Bad Example + + ```typescript + function getPrescription(id) { + // No type safety, unclear return type + } + ``` + +## Validation and Verification + +- Build: `npm run build` +- Lint: `npm run lint` +- Format: `npm run format` +- Test: `npm test` + +## Maintenance + +- Review and update instructions as dependencies or frameworks change. +- Update examples to reflect current best practices. +- Remove deprecated patterns and add new ones as needed. +- Ensure glob patterns match the intended files. + +## Additional Resources + +- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/) +- [ESLint TypeScript Plugin](https://typescript-eslint.io/) +- [Prettier Documentation](https://prettier.io/docs/en/options.html) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 94cbe247..f236db4f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,7 +27,7 @@ jobs: echo "commit_id=${{ github.sha }}" >> "$GITHUB_OUTPUT" echo "sha_short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT" get_config_values: - uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@97059401fbec4c0914532277dfe8ce95dd3213fd + uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@b0172dbdb3af4ae232873106553c316d79d784fc with: verify_published_from_main_image: true quality_checks: diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index 62801d5f..fe5b1861 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -9,7 +9,7 @@ env: jobs: get_config_values: - uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@97059401fbec4c0914532277dfe8ce95dd3213fd + uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@b0172dbdb3af4ae232873106553c316d79d784fc with: verify_published_from_main_image: false dependabot-auto-approve-and-merge: @@ -19,7 +19,7 @@ jobs: AUTOMERGE_APP_ID: ${{ secrets.AUTOMERGE_APP_ID }} AUTOMERGE_PEM: ${{ secrets.AUTOMERGE_PEM }} pr_title_format_check: - uses: NHSDigital/eps-common-workflows/.github/workflows/pr_title_check.yml@97059401fbec4c0914532277dfe8ce95dd3213fd + uses: NHSDigital/eps-common-workflows/.github/workflows/pr_title_check.yml@b0172dbdb3af4ae232873106553c316d79d784fc quality_checks: uses: NHSDigital/eps-common-workflows/.github/workflows/quality-checks-devcontainer.yml@352f15f692c23b18f67215ad858f27b06a878717 needs: [get_config_values, get_commit_id] diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fe96c002..cf39f01c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -10,7 +10,7 @@ env: jobs: get_config_values: - uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@97059401fbec4c0914532277dfe8ce95dd3213fd + uses: NHSDigital/eps-common-workflows/.github/workflows/get-repo-config.yml@b0172dbdb3af4ae232873106553c316d79d784fc with: verify_published_from_main_image: true get_commit_id: diff --git a/.gitignore b/.gitignore index d28ca73f..9cab097d 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,4 @@ _site/ .jekyll-metadata vendor .trivy_out/ +*.tgz diff --git a/.trivyignore.yaml b/.trivyignore.yaml index 0754eb44..34f78521 100644 --- a/.trivyignore.yaml +++ b/.trivyignore.yaml @@ -77,3 +77,6 @@ vulnerabilities: - id: CVE-2026-32141 statement: flatted expired_at: 2026-06-01 + - id: CVE-2026-33036 + statement: fast-xml-parser vulnerability accepted as risk - dependency of aws-sdk/client-dynamodb and redocly + expired_at: 2026-04-01 diff --git a/packages/cdkConstructs/src/constants.ts b/packages/cdkConstructs/src/constants.ts new file mode 100644 index 00000000..7f6ca498 --- /dev/null +++ b/packages/cdkConstructs/src/constants.ts @@ -0,0 +1,19 @@ +import {Fn} from "aws-cdk-lib" + +/** Imported cross-stack account resource values used by constructs in this package. */ +export const ACCOUNT_RESOURCES = { + CloudwatchEncryptionKMSPolicyArn: Fn.importValue("account-resources:CloudwatchEncryptionKMSPolicyArn"), + CloudwatchLogsKmsKeyArn: Fn.importValue("account-resources:CloudwatchLogsKmsKeyArn"), + EpsDomainName: Fn.importValue("eps-route53-resources:EPS-domain"), + EpsZoneId: Fn.importValue("eps-route53-resources:EPS-ZoneID"), + TrustStoreBucket: Fn.importValue("account-resources:TrustStoreBucket"), + TrustStoreBucketKMSKey: Fn.importValue("account-resources:TrustStoreBucketKMSKey"), + TrustStoreDeploymentBucket: Fn.importValue("account-resources:TrustStoreDeploymentBucket") +} + +/** Imported shared Lambda resource values used by Lambda and API Gateway constructs. */ +export const LAMBDA_RESOURCES = { + LambdaInsightsLogGroupPolicy: Fn.importValue("lambda-resources:LambdaInsightsLogGroupPolicy"), + SplunkDeliveryStream: Fn.importValue("lambda-resources:SplunkDeliveryStream"), + SplunkSubscriptionFilterRole: Fn.importValue("lambda-resources:SplunkSubscriptionFilterRole") +} diff --git a/packages/cdkConstructs/src/constructs/RestApiGateway.ts b/packages/cdkConstructs/src/constructs/RestApiGateway.ts new file mode 100644 index 00000000..fe532fd4 --- /dev/null +++ b/packages/cdkConstructs/src/constructs/RestApiGateway.ts @@ -0,0 +1,261 @@ +import {RemovalPolicy} from "aws-cdk-lib" +import { + CfnStage, + EndpointType, + LogGroupLogDestination, + MethodLoggingLevel, + MTLSConfig, + RestApi, + SecurityPolicy +} from "aws-cdk-lib/aws-apigateway" +import { + IManagedPolicy, + IRole, + ManagedPolicy, + PolicyStatement, + Role, + ServicePrincipal +} from "aws-cdk-lib/aws-iam" +import {Stream} from "aws-cdk-lib/aws-kinesis" +import {Key} from "aws-cdk-lib/aws-kms" +import {CfnSubscriptionFilter, LogGroup} from "aws-cdk-lib/aws-logs" +import {Construct} from "constructs" +import {accessLogFormat} from "./RestApiGateway/accessLogFormat.js" +import {Certificate, CertificateValidation} from "aws-cdk-lib/aws-certificatemanager" +import {Bucket} from "aws-cdk-lib/aws-s3" +import {BucketDeployment, Source} from "aws-cdk-lib/aws-s3-deployment" +import {ARecord, HostedZone, RecordTarget} from "aws-cdk-lib/aws-route53" +import {ApiGateway as ApiGatewayTarget} from "aws-cdk-lib/aws-route53-targets" +import {NagSuppressions} from "cdk-nag" +import {ACCOUNT_RESOURCES, LAMBDA_RESOURCES} from "../constants" + +/** Configuration for creating a REST API with optional mTLS and log forwarding integrations. */ +export interface RestApiGatewayProps { + /** Stack name, used as prefix for resource naming and DNS records. */ + readonly stackName: string + /** Shared retention period for API and deployment-related log groups. */ + readonly logRetentionInDays: number + /** Truststore object key to enable mTLS; leave undefined to disable mTLS. */ + readonly mutualTlsTrustStoreKey: string | undefined + /** Enables creation of a second subscription filter to forward logs to CSOC. */ + readonly forwardCsocLogs: boolean + /** Destination ARN used by the optional CSOC subscription filter. */ + readonly csocApiGatewayDestination: string + /** Managed policies attached to the API Gateway execution role. */ + readonly executionPolicies: Array +} + +/** Creates a regional REST API with standard logging, DNS, and optional mTLS/CSOC integration. */ +export class RestApiGateway extends Construct { + /** Created API Gateway instance. */ + public readonly api: RestApi + + /** IAM role assumed by API Gateway integrations. */ + public readonly role: IRole + + /** + * Builds API Gateway infrastructure and validates CSOC forwarding configuration. + * @example + * ```ts + * const api = new RestApiGateway(this, "MyApi", { + * stackName: "my-service", + * logRetentionInDays: 30, + * mutualTlsTrustStoreKey: "truststore.pem", + * forwardCsocLogs: true, + * csocApiGatewayDestination: "arn:aws:logs:eu-west-2:123456789012:destination:csoc", + * executionPolicies: [myLambdaInvokePolicy] + * }) + * api.api.root.addResource("patients") + * ``` + */ + public constructor(scope: Construct, id: string, props: RestApiGatewayProps) { + super(scope, id) + + if (props.forwardCsocLogs && props.csocApiGatewayDestination === "") { + throw new Error("csocApiGatewayDestination must be provided when forwardCsocLogs is true") + } + + // Imports + const cloudWatchLogsKmsKey = Key.fromKeyArn( + this, "cloudWatchLogsKmsKey", ACCOUNT_RESOURCES.CloudwatchLogsKmsKeyArn) + + const splunkDeliveryStream = Stream.fromStreamArn( + this, "SplunkDeliveryStream", LAMBDA_RESOURCES.SplunkDeliveryStream) + + const splunkSubscriptionFilterRole = Role.fromRoleArn( + this, "splunkSubscriptionFilterRole", LAMBDA_RESOURCES.SplunkSubscriptionFilterRole) + + const trustStoreBucket = Bucket.fromBucketArn( + this, "TrustStoreBucket", ACCOUNT_RESOURCES.TrustStoreBucket) + + const trustStoreDeploymentBucket = Bucket.fromBucketArn( + this, "TrustStoreDeploymentBucket", ACCOUNT_RESOURCES.TrustStoreDeploymentBucket) + + const trustStoreBucketKmsKey = Key.fromKeyArn( + this, "TrustStoreBucketKmsKey", ACCOUNT_RESOURCES.TrustStoreBucketKMSKey) + + const epsDomainName: string = ACCOUNT_RESOURCES.EpsDomainName + const hostedZone = HostedZone.fromHostedZoneAttributes(this, "HostedZone", { + hostedZoneId: ACCOUNT_RESOURCES.EpsZoneId, + zoneName: epsDomainName + }) + const serviceDomainName = `${props.stackName}.${epsDomainName}` + + // Resources + const logGroup = new LogGroup(this, "ApiGatewayAccessLogGroup", { + encryptionKey: cloudWatchLogsKmsKey, + logGroupName: `/aws/apigateway/${props.stackName}-apigw`, + retention: props.logRetentionInDays, + removalPolicy: RemovalPolicy.DESTROY + }) + + new CfnSubscriptionFilter(this, "ApiGatewayAccessLogsSplunkSubscriptionFilter", { + destinationArn: splunkDeliveryStream.streamArn, + filterPattern: "", + logGroupName: logGroup.logGroupName, + roleArn: splunkSubscriptionFilterRole.roleArn + }) + + if (props.forwardCsocLogs) { + new CfnSubscriptionFilter(this, "ApiGatewayAccessLogsCSOCSubscriptionFilter", { + destinationArn: props.csocApiGatewayDestination, + filterPattern: "", + logGroupName: logGroup.logGroupName, + roleArn: splunkSubscriptionFilterRole.roleArn + }) + } + + const certificate = new Certificate(this, "Certificate", { + domainName: serviceDomainName, + validation: CertificateValidation.fromDns(hostedZone) + }) + + let mtlsConfig: MTLSConfig | undefined + + if (props.mutualTlsTrustStoreKey) { + const trustStoreKeyPrefix = `cpt-api/${props.stackName}-truststore` + const logGroup = new LogGroup(this, "LambdaLogGroup", { + encryptionKey: cloudWatchLogsKmsKey, + logGroupName: `/aws/lambda/${props.stackName}-truststore-deployment`, + retention: props.logRetentionInDays, + removalPolicy: RemovalPolicy.DESTROY + }) + const trustStoreDeploymentPolicy = new ManagedPolicy(this, "TrustStoreDeploymentPolicy", { + statements: [ + new PolicyStatement({ + actions: [ + "s3:ListBucket" + ], + resources: [ + trustStoreBucket.bucketArn, + trustStoreDeploymentBucket.bucketArn + ] + }), + new PolicyStatement({ + actions: [ + "s3:GetObject" + ], + resources: [trustStoreBucket.arnForObjects(props.mutualTlsTrustStoreKey)] + }), + new PolicyStatement({ + actions: [ + "s3:DeleteObject", + "s3:PutObject" + ], + resources: [ + trustStoreDeploymentBucket.arnForObjects(trustStoreKeyPrefix + "/" + props.mutualTlsTrustStoreKey) + ] + }), + new PolicyStatement({ + actions: [ + "kms:Decrypt", + "kms:Encrypt", + "kms:GenerateDataKey" + ], + resources: [trustStoreBucketKmsKey.keyArn] + }), + new PolicyStatement({ + actions: [ + "logs:CreateLogStream", + "logs:PutLogEvents" + ], + resources: [ + logGroup.logGroupArn, + `${logGroup.logGroupArn}:log-stream:*` + ] + }) + ] + }) + NagSuppressions.addResourceSuppressions(trustStoreDeploymentPolicy, [ + { + id: "AwsSolutions-IAM5", + // eslint-disable-next-line max-len + reason: "Suppress error for not having wildcards in permissions. This is a fine as we need to have permissions on all log streams under path" + } + ]) + const trustStoreDeploymentRole = new Role(this, "TrustStoreDeploymentRole", { + assumedBy: new ServicePrincipal("lambda.amazonaws.com"), + managedPolicies: [trustStoreDeploymentPolicy] + }).withoutPolicyUpdates() + const deployment = new BucketDeployment(this, "TrustStoreDeployment", { + sources: [Source.bucket(trustStoreBucket, props.mutualTlsTrustStoreKey)], + destinationBucket: trustStoreDeploymentBucket, + destinationKeyPrefix: trustStoreKeyPrefix, + extract: false, + retainOnDelete: false, + role: trustStoreDeploymentRole, + logGroup: logGroup + }) + mtlsConfig = { + bucket: deployment.deployedBucket, + key: trustStoreKeyPrefix + "/" + props.mutualTlsTrustStoreKey + } + } + + const apiGateway = new RestApi(this, "ApiGateway", { + restApiName: `${props.stackName}-apigw`, + domainName: { + domainName: serviceDomainName, + certificate: certificate, + securityPolicy: SecurityPolicy.TLS_1_2, + endpointType: EndpointType.REGIONAL, + mtls: mtlsConfig + }, + disableExecuteApiEndpoint: mtlsConfig ? true : false, // NOSONAR + endpointConfiguration: { + types: [EndpointType.REGIONAL] + }, + deploy: true, + deployOptions: { + accessLogDestination: new LogGroupLogDestination(logGroup), + accessLogFormat: accessLogFormat(), + loggingLevel: MethodLoggingLevel.INFO, + metricsEnabled: true + } + }) + + const role = new Role(this, "ApiGatewayRole", { + assumedBy: new ServicePrincipal("apigateway.amazonaws.com"), + managedPolicies: props.executionPolicies + }).withoutPolicyUpdates() + + new ARecord(this, "ARecord", { + recordName: props.stackName, + target: RecordTarget.fromAlias(new ApiGatewayTarget(apiGateway)), + zone: hostedZone + }) + + const cfnStage = apiGateway.deploymentStage.node.defaultChild as CfnStage + cfnStage.cfnOptions.metadata = { + guard: { + SuppressedRules: [ + "API_GW_CACHE_ENABLED_AND_ENCRYPTED" + ] + } + } + + // Outputs + this.api = apiGateway + this.role = role + } +} diff --git a/packages/cdkConstructs/src/constructs/RestApiGateway/LambdaEndpoint.ts b/packages/cdkConstructs/src/constructs/RestApiGateway/LambdaEndpoint.ts new file mode 100644 index 00000000..940e9613 --- /dev/null +++ b/packages/cdkConstructs/src/constructs/RestApiGateway/LambdaEndpoint.ts @@ -0,0 +1,44 @@ +import {IResource, LambdaIntegration} from "aws-cdk-lib/aws-apigateway" +import {IRole} from "aws-cdk-lib/aws-iam" +import {HttpMethod, IFunction} from "aws-cdk-lib/aws-lambda" +import {Construct} from "constructs" + +/** Lambda container shape consumed by endpoint integration wiring. */ +export interface LambdaFunctionHolder { + /** Lambda invoked by this API resource method. */ + readonly function: IFunction +} + +/** Parameters used to create an API resource and attach a Lambda integration. */ +export interface LambdaEndpointProps { + /** Parent API resource under which this endpoint path is created. */ + parentResource: IResource + /** Path segment added beneath the parent resource. */ + readonly resourceName: string + /** HTTP method exposed on the created API resource. */ + readonly method: HttpMethod + /** Role assumed by API Gateway when invoking the integration Lambda. */ + restApiGatewayRole: IRole + /** Lambda reference used by the generated integration. */ + lambdaFunction: LambdaFunctionHolder +} + +/** Adds a child API resource and wires it to a Lambda integration with explicit credentials. */ +export class LambdaEndpoint extends Construct { + /** API resource created by this construct. */ + resource: IResource + + /** + * Creates the resource/method pair and stores the resulting API resource handle. + */ + public constructor(scope: Construct, id: string, props: LambdaEndpointProps) { + super(scope, id) + + const resource = props.parentResource.addResource(props.resourceName) + resource.addMethod(props.method, new LambdaIntegration(props.lambdaFunction.function, { + credentialsRole: props.restApiGatewayRole + })) + + this.resource = resource + } +} diff --git a/packages/cdkConstructs/src/constructs/RestApiGateway/accessLogFormat.ts b/packages/cdkConstructs/src/constructs/RestApiGateway/accessLogFormat.ts new file mode 100644 index 00000000..84262356 --- /dev/null +++ b/packages/cdkConstructs/src/constructs/RestApiGateway/accessLogFormat.ts @@ -0,0 +1,41 @@ +import {AccessLogFormat} from "aws-cdk-lib/aws-apigateway" + +/** + * @returns Access-log formatter configured with the package standard schema. + */ +export const accessLogFormat = (): AccessLogFormat => { + return AccessLogFormat.custom(JSON.stringify({ + requestId: "$context.requestId", + ip: "$context.identity.sourceIp", + caller: "$context.identity.caller", + user: "$context.identity.user", + requestTime: "$context.requestTime", + httpMethod: "$context.httpMethod", + resourcePath: "$context.resourcePath", + status: "$context.status", + protocol: "$context.protocol", + responseLength: "$context.responseLength", + accountId: "$context.accountId", + apiId: "$context.apiId", + stage: "$context.stage", + api_key: "$context.identity.apiKey", + identity: { + sourceIp: "$context.identity.sourceIp", + userAgent: "$context.identity.userAgent", + clientCert: { + subjectDN: "$context.identity.clientCert.subjectDN", + issuerDN: "$context.identity.clientCert.issuerDN", + serialNumber: "$context.identity.clientCert.serialNumber", + validityNotBefore: "$context.identity.clientCert.validity.notBefore", + validityNotAfter: "$context.identity.clientCert.validity.notAfter" + } + }, + integration:{ + error: "$context.integration.error", + integrationStatus: "$context.integration.integrationStatus", + latency: "$context.integration.latency", + requestId: "$context.integration.requestId", + status: "$context.integration.status" + } + })) +} diff --git a/packages/cdkConstructs/src/constructs/lambdaSharedResources.ts b/packages/cdkConstructs/src/constructs/lambdaSharedResources.ts index 20769cf8..7f89899e 100644 --- a/packages/cdkConstructs/src/constructs/lambdaSharedResources.ts +++ b/packages/cdkConstructs/src/constructs/lambdaSharedResources.ts @@ -1,5 +1,5 @@ import {Construct} from "constructs" -import {Fn, RemovalPolicy} from "aws-cdk-lib" +import {RemovalPolicy} from "aws-cdk-lib" import {Architecture, ILayerVersion, LayerVersion} from "aws-cdk-lib/aws-lambda" import {IKey, Key} from "aws-cdk-lib/aws-kms" import {CfnLogGroup, CfnSubscriptionFilter, LogGroup} from "aws-cdk-lib/aws-logs" @@ -13,6 +13,7 @@ import { } from "aws-cdk-lib/aws-iam" import {NagSuppressions} from "cdk-nag" import {LAMBDA_INSIGHTS_LAYER_ARNS} from "../config" +import {ACCOUNT_RESOURCES, LAMBDA_RESOURCES} from "../constants" import {addSuppressions} from "../utils/helpers" import {CfnDeliveryStream} from "aws-cdk-lib/aws-kinesisfirehose" import {Stream} from "aws-cdk-lib/aws-kinesis" @@ -46,14 +47,17 @@ export const createSharedLambdaResources = ( additionalPolicies, architecture, cloudWatchLogsKmsKey = Key.fromKeyArn( - scope, "cloudWatchLogsKmsKey", Fn.importValue("account-resources:CloudwatchLogsKmsKeyArn")), + scope, "cloudWatchLogsKmsKey", ACCOUNT_RESOURCES.CloudwatchLogsKmsKeyArn), cloudwatchEncryptionKMSPolicy = ManagedPolicy.fromManagedPolicyArn( - scope, "cloudwatchEncryptionKMSPolicyArn", Fn.importValue("account-resources:CloudwatchEncryptionKMSPolicyArn")), + scope, + "cloudwatchEncryptionKMSPolicyArn", + ACCOUNT_RESOURCES.CloudwatchEncryptionKMSPolicyArn + ), splunkDeliveryStream, splunkSubscriptionFilterRole = Role.fromRoleArn( - scope, "splunkSubscriptionFilterRole", Fn.importValue("lambda-resources:SplunkSubscriptionFilterRole")), + scope, "splunkSubscriptionFilterRole", LAMBDA_RESOURCES.SplunkSubscriptionFilterRole), lambdaInsightsLogGroupPolicy = ManagedPolicy.fromManagedPolicyArn( - scope, "lambdaInsightsLogGroupPolicy", Fn.importValue("lambda-resources:LambdaInsightsLogGroupPolicy")), + scope, "lambdaInsightsLogGroupPolicy", LAMBDA_RESOURCES.LambdaInsightsLogGroupPolicy), addSplunkSubscriptionFilter = true } = props const insightsLambdaLayerArn = architecture === Architecture.ARM_64 @@ -84,7 +88,7 @@ export const createSharedLambdaResources = ( }) } else { const splunkDeliveryStreamImport = Stream.fromStreamArn( - scope, "SplunkDeliveryStream", Fn.importValue("lambda-resources:SplunkDeliveryStream")) + scope, "SplunkDeliveryStream", LAMBDA_RESOURCES.SplunkDeliveryStream) new CfnSubscriptionFilter(scope, "LambdaLogsSplunkSubscriptionFilter", { destinationArn: splunkDeliveryStreamImport.streamArn, filterPattern: "", diff --git a/packages/cdkConstructs/src/index.ts b/packages/cdkConstructs/src/index.ts index 0c73b904..a964a253 100644 --- a/packages/cdkConstructs/src/index.ts +++ b/packages/cdkConstructs/src/index.ts @@ -1,5 +1,8 @@ // Export all constructs export * from "./constructs/TypescriptLambdaFunction.js" +export * from "./constructs/RestApiGateway.js" +export * from "./constructs/RestApiGateway/accessLogFormat.js" +export * from "./constructs/RestApiGateway/LambdaEndpoint.js" export * from "./constructs/PythonLambdaFunction.js" export * from "./apps/createApp.js" export * from "./config/index.js" diff --git a/packages/cdkConstructs/tests/apps/createApp.test.ts b/packages/cdkConstructs/tests/apps/createApp.test.ts index b5383d1a..2237b772 100644 --- a/packages/cdkConstructs/tests/apps/createApp.test.ts +++ b/packages/cdkConstructs/tests/apps/createApp.test.ts @@ -11,7 +11,7 @@ * * Note: The getBooleanConfigFromEnvVar function uses Boolean() which converts * any non-empty string (including "false", "0", etc.) to true. Tests account - * for this behavior. + * for this behaviour. */ import {App, Aspects, Tags} from "aws-cdk-lib" import { diff --git a/packages/cdkConstructs/tests/constructs/RestApiGateway.test.ts b/packages/cdkConstructs/tests/constructs/RestApiGateway.test.ts new file mode 100644 index 00000000..0853fddd --- /dev/null +++ b/packages/cdkConstructs/tests/constructs/RestApiGateway.test.ts @@ -0,0 +1,354 @@ +import {App, Stack} from "aws-cdk-lib" +import {Template, Match} from "aws-cdk-lib/assertions" +import {ManagedPolicy, PolicyStatement} from "aws-cdk-lib/aws-iam" +import { + describe, + test, + beforeAll, + expect +} from "vitest" + +import {RestApiGateway} from "../../src/constructs/RestApiGateway.js" + +describe("RestApiGateway without mTLS", () => { + let stack: Stack + let app: App + let template: Template + + beforeAll(() => { + app = new App() + stack = new Stack(app, "RestApiGatewayStack") + + const testPolicy = new ManagedPolicy(stack, "TestPolicy", { + description: "test execution policy", + statements: [ + new PolicyStatement({ + actions: ["lambda:InvokeFunction"], + resources: ["arn:aws:lambda:eu-west-2:123456789012:function:test-function"] + }) + ] + }) + + const apiGateway = new RestApiGateway(stack, "TestApiGateway", { + stackName: "test-stack", + logRetentionInDays: 30, + mutualTlsTrustStoreKey: undefined, + forwardCsocLogs: false, + csocApiGatewayDestination: "", + executionPolicies: [testPolicy] + }) + + // Add a dummy method to satisfy API Gateway validation + apiGateway.api.root.addMethod("GET") + + template = Template.fromStack(stack) + }) + + test("creates CloudWatch log group with correct properties", () => { + template.hasResourceProperties("AWS::Logs::LogGroup", { + LogGroupName: "/aws/apigateway/test-stack-apigw", + KmsKeyId: {"Fn::ImportValue": "account-resources:CloudwatchLogsKmsKeyArn"}, + RetentionInDays: 30 + }) + }) + + test("creates Splunk subscription filter", () => { + template.hasResourceProperties("AWS::Logs::SubscriptionFilter", { + FilterPattern: "", + RoleArn: {"Fn::ImportValue": "lambda-resources:SplunkSubscriptionFilterRole"}, + DestinationArn: {"Fn::ImportValue": "lambda-resources:SplunkDeliveryStream"} + }) + }) + + test("does not create CSOC subscription filter", () => { + const filters = template.findResources("AWS::Logs::SubscriptionFilter") + const filterCount = Object.keys(filters).length + expect(filterCount).toBe(1) + }) + + test("creates ACM certificate", () => { + template.hasResourceProperties("AWS::CertificateManager::Certificate", { + DomainName: { + "Fn::Join": ["", [ + "test-stack.", + {"Fn::ImportValue": "eps-route53-resources:EPS-domain"} + ]] + }, + DomainValidationOptions: [{ + DomainName: { + "Fn::Join": ["", [ + "test-stack.", + {"Fn::ImportValue": "eps-route53-resources:EPS-domain"} + ]] + }, + HostedZoneId: {"Fn::ImportValue": "eps-route53-resources:EPS-ZoneID"} + }], + ValidationMethod: "DNS" + }) + }) + + test("creates REST API Gateway with correct configuration", () => { + template.hasResourceProperties("AWS::ApiGateway::RestApi", { + Name: "test-stack-apigw", + EndpointConfiguration: { + Types: ["REGIONAL"] + }, + DisableExecuteApiEndpoint: false + }) + }) + + test("creates API Gateway domain name with TLS 1.2", () => { + template.hasResourceProperties("AWS::ApiGateway::DomainName", { + DomainName: { + "Fn::Join": ["", [ + "test-stack.", + {"Fn::ImportValue": "eps-route53-resources:EPS-domain"} + ]] + }, + EndpointConfiguration: { + Types: ["REGIONAL"] + }, + SecurityPolicy: "TLS_1_2" + }) + }) + + test("creates deployment with logging and metrics enabled", () => { + template.hasResourceProperties("AWS::ApiGateway::Stage", { + MethodSettings: [{ + LoggingLevel: "INFO", + MetricsEnabled: true, + DataTraceEnabled: false, + HttpMethod: "*", + ResourcePath: "/*" + }], + AccessLogSetting: Match.objectLike({ + Format: Match.stringLikeRegexp("requestId") + }) + }) + }) + + test("creates IAM role for API Gateway execution", () => { + template.hasResourceProperties("AWS::IAM::Role", { + AssumeRolePolicyDocument: { + Statement: [{ + Action: "sts:AssumeRole", + Effect: "Allow", + Principal: { + Service: "apigateway.amazonaws.com" + } + }], + Version: "2012-10-17" + } + }) + }) + + test("creates Route53 A record", () => { + template.hasResourceProperties("AWS::Route53::RecordSet", { + Name: { + "Fn::Join": ["", [ + "test-stack.", + {"Fn::ImportValue": "eps-route53-resources:EPS-domain"}, + "." + ]] + }, + Type: "A" + }) + }) + + test("sets guard metadata on stage", () => { + const stages = template.findResources("AWS::ApiGateway::Stage") + const stageKeys = Object.keys(stages) + expect(stageKeys.length).toBeGreaterThan(0) + + const stage = stages[stageKeys[0]] + expect(stage.Metadata).toBeDefined() + expect(stage.Metadata.guard).toBeDefined() + expect(stage.Metadata.guard.SuppressedRules).toContain("API_GW_CACHE_ENABLED_AND_ENCRYPTED") + }) +}) + +describe("RestApiGateway with CSOC logs", () => { + let stack: Stack + let app: App + let template: Template + + beforeAll(() => { + app = new App() + stack = new Stack(app, "RestApiGatewayStack") + + const testPolicy = new ManagedPolicy(stack, "TestPolicy", { + description: "test execution policy", + statements: [ + new PolicyStatement({ + actions: ["lambda:InvokeFunction"], + resources: ["arn:aws:lambda:eu-west-2:123456789012:function:test-function"] + }) + ] + }) + + const apiGateway = new RestApiGateway(stack, "TestApiGateway", { + stackName: "test-stack", + logRetentionInDays: 30, + mutualTlsTrustStoreKey: undefined, + forwardCsocLogs: true, + csocApiGatewayDestination: "arn:aws:logs:eu-west-2:123456789012:destination:csoc-destination", + executionPolicies: [testPolicy] + }) + + // Add a dummy method to satisfy API Gateway validation + apiGateway.api.root.addMethod("GET") + + template = Template.fromStack(stack) + }) + + test("creates both Splunk and CSOC subscription filters", () => { + const filters = template.findResources("AWS::Logs::SubscriptionFilter") + const filterCount = Object.keys(filters).length + expect(filterCount).toBe(2) + }) + + test("creates CSOC subscription filter with correct destination", () => { + template.hasResourceProperties("AWS::Logs::SubscriptionFilter", { + FilterPattern: "", + DestinationArn: "arn:aws:logs:eu-west-2:123456789012:destination:csoc-destination" + }) + }) +}) + +describe("RestApiGateway with mTLS", () => { + let stack: Stack + let app: App + let template: Template + + beforeAll(() => { + app = new App() + stack = new Stack(app, "RestApiGatewayStack") + + const testPolicy = new ManagedPolicy(stack, "TestPolicy", { + description: "test execution policy", + statements: [ + new PolicyStatement({ + actions: ["lambda:InvokeFunction"], + resources: ["arn:aws:lambda:eu-west-2:123456789012:function:test-function"] + }) + ] + }) + + const apiGateway = new RestApiGateway(stack, "TestApiGateway", { + stackName: "test-stack", + logRetentionInDays: 30, + mutualTlsTrustStoreKey: "truststore.pem", + forwardCsocLogs: false, + csocApiGatewayDestination: "", + executionPolicies: [testPolicy] + }) + + // Add a dummy method to satisfy API Gateway validation + apiGateway.api.root.addMethod("GET") + + template = Template.fromStack(stack) + }) + + test("creates trust store deployment log group", () => { + template.hasResourceProperties("AWS::Logs::LogGroup", { + LogGroupName: "/aws/lambda/test-stack-truststore-deployment", + KmsKeyId: {"Fn::ImportValue": "account-resources:CloudwatchLogsKmsKeyArn"}, + RetentionInDays: 30 + }) + }) + + test("creates trust store deployment policy with S3 permissions", () => { + interface PolicyResource { + Properties?: { + PolicyDocument?: { + Statement?: Array<{Action?: Array}> + } + } + } + interface Statement { + Action?: Array + } + + const policies = template.findResources("AWS::IAM::ManagedPolicy") + const trustStorePolicy = Object.values(policies).find((p: PolicyResource) => + p.Properties?.PolicyDocument?.Statement?.some((s: Statement) => + s.Action?.includes("s3:ListBucket") + ) + ) as PolicyResource + expect(trustStorePolicy).toBeDefined() + const statements = trustStorePolicy.Properties?.PolicyDocument?.Statement ?? [] + expect(statements.some((s: Statement) => s.Action?.includes("s3:ListBucket"))).toBe(true) + expect(statements.some((s: Statement) => s.Action?.includes("s3:GetObject"))).toBe(true) + expect(statements.some((s: Statement) => s.Action?.includes("kms:Decrypt"))).toBe(true) + expect(statements.some((s: Statement) => s.Action?.includes("logs:CreateLogStream"))).toBe(true) + }) + + test("creates trust store deployment role", () => { + template.hasResourceProperties("AWS::IAM::Role", { + AssumeRolePolicyDocument: { + Statement: Match.arrayWith([ + Match.objectLike({ + Action: "sts:AssumeRole", + Effect: "Allow", + Principal: { + Service: "lambda.amazonaws.com" + } + }) + ]), + Version: "2012-10-17" + } + }) + }) + + test("creates bucket deployment custom resource", () => { + const customResources = template.findResources("Custom::CDKBucketDeployment") + expect(Object.keys(customResources).length).toBeGreaterThan(0) + }) + + test("disables execute-api endpoint when mTLS is enabled", () => { + template.hasResourceProperties("AWS::ApiGateway::RestApi", { + Name: "test-stack-apigw", + DisableExecuteApiEndpoint: true + }) + }) + + test("configures mTLS on domain name", () => { + interface DomainNameResource { + Properties: { + MutualTlsAuthentication: { + TruststoreUri: unknown + } + } + } + + const domainNames = template.findResources("AWS::ApiGateway::DomainName") + const domainName = Object.values(domainNames)[0] as DomainNameResource + expect(domainName.Properties.MutualTlsAuthentication).toBeDefined() + expect(domainName.Properties.MutualTlsAuthentication.TruststoreUri).toBeDefined() + }) +}) + +describe("RestApiGateway validation errors", () => { + test("throws when forwardCsocLogs is true and csocApiGatewayDestination is empty string", () => { + const app = new App() + const stack = new Stack(app, "ValidationStack1") + const testPolicy = new ManagedPolicy(stack, "TestPolicy", { + description: "test execution policy", + statements: [ + new PolicyStatement({ + actions: ["lambda:InvokeFunction"], + resources: ["arn:aws:lambda:eu-west-2:123456789012:function:test-function"] + }) + ] + }) + + expect(() => new RestApiGateway(stack, "TestApiGateway", { + stackName: "test-stack", + logRetentionInDays: 30, + mutualTlsTrustStoreKey: undefined, + forwardCsocLogs: true, + csocApiGatewayDestination: "", + executionPolicies: [testPolicy] + })).toThrow("csocApiGatewayDestination must be provided when forwardCsocLogs is true") + }) +}) diff --git a/packages/cdkConstructs/tests/constructs/RestApiGateway/LambdaEndpoint.test.ts b/packages/cdkConstructs/tests/constructs/RestApiGateway/LambdaEndpoint.test.ts new file mode 100644 index 00000000..93178ea5 --- /dev/null +++ b/packages/cdkConstructs/tests/constructs/RestApiGateway/LambdaEndpoint.test.ts @@ -0,0 +1,99 @@ +import {App, Stack} from "aws-cdk-lib" +import {RestApi} from "aws-cdk-lib/aws-apigateway" +import {Role, ServicePrincipal} from "aws-cdk-lib/aws-iam" +import {Template, Match} from "aws-cdk-lib/assertions" +import { + Architecture, + Function as LambdaFunction, + HttpMethod, + Runtime +} from "aws-cdk-lib/aws-lambda" +import { + describe, + test, + beforeAll, + expect +} from "vitest" + +import {LambdaEndpoint} from "../../../src/constructs/RestApiGateway/LambdaEndpoint.js" + +describe("LambdaEndpoint construct", () => { + let stack: Stack + let template: Template + let construct: LambdaEndpoint + + beforeAll(() => { + const app = new App() + stack = new Stack(app, "LambdaEndpointStack") + + const api = new RestApi(stack, "TestApi") + + const credentialsRole = new Role(stack, "ApiGwRole", { + assumedBy: new ServicePrincipal("apigateway.amazonaws.com") + }) + + // Minimal lambda function stub that satisfies LambdaFunctionHolder interface + const lambdaFn = new LambdaFunction(stack, "DummyFn", { + runtime: Runtime.NODEJS_22_X, + handler: "index.handler", + code: { + bind: () => ({ + s3Location: {bucketName: "dummy", objectKey: "dummy.zip"} + }), + bindToResource: () => undefined, + isInline: false + } as unknown as never, + architecture: Architecture.X86_64 + }) + + construct = new LambdaEndpoint(stack, "TestLambdaEndpoint", { + parentResource: api.root, + resourceName: "test-resource", + method: HttpMethod.GET, + restApiGatewayRole: credentialsRole, + lambdaFunction: {function: lambdaFn} + }) + + template = Template.fromStack(stack) + }) + + test("creates an API Gateway resource with the correct path part", () => { + template.hasResourceProperties("AWS::ApiGateway::Resource", { + PathPart: "test-resource" + }) + }) + + test("creates a GET method on the resource", () => { + template.hasResourceProperties("AWS::ApiGateway::Method", { + HttpMethod: "GET" + }) + }) + + test("exposes the resource as a public property", () => { + expect(construct.resource).toBeDefined() + }) + + test("uses credentials role on the Lambda integration", () => { + template.hasResourceProperties("AWS::ApiGateway::Method", { + HttpMethod: "GET", + Integration: Match.objectLike({ + Type: "AWS_PROXY", + Credentials: { + "Fn::GetAtt": [ + Match.stringLikeRegexp("^ApiGwRole.*$"), + "Arn" + ] + } + }) + }) + }) +}) + +describe("LambdaEndpoint accepts TypescriptLambdaFunction via structural typing", () => { + test("LambdaFunctionHolder interface is satisfied by any object with a function property", () => { + // This is a compile-time check verified by the build step. Here we just + // assert the interface shape is correct at runtime. + const holder = {function: {} as unknown as never} + expect(holder.function).toBeDefined() + }) +}) diff --git a/sonar-project.properties b/sonar-project.properties index 8054cb01..d631f11b 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -2,6 +2,10 @@ sonar.organization=nhsdigital sonar.projectKey=NHSDigital_eps-cdk-utils sonar.host.url=https://sonarcloud.io +sonar.exclusions=\ + packages/serviceSearchClient/vitest.config.ts,\ + packages/enrichPrescriptions/vitest.config.ts + sonar.coverage.exclusions=\ **/*.test.*,\ **/jest.config.ts,scripts/*,\