diff --git a/packages/aws-cdk-lib/core/lib/validation/report.ts b/packages/aws-cdk-lib/core/lib/validation/report.ts index 6ea77f759c6f0..20cfcfb41cbb5 100644 --- a/packages/aws-cdk-lib/core/lib/validation/report.ts +++ b/packages/aws-cdk-lib/core/lib/validation/report.ts @@ -1,6 +1,116 @@ /** * Violation produced by the validation plugin. */ +export interface PolicyViolation { + /** + * The name of the rule. + */ + readonly ruleName: string; + + /** + * The description of the violation. + */ + readonly description: string; + + /** + * The resources violating this rule. + */ + readonly violatingResources: PolicyViolatingResource[]; + + /** + * How to fix the violation. + * + * @default - no fix is provided + */ + readonly fix?: string; + + /** + * The severity of the violation, only used for reporting purposes. + * This is useful for helping the user discriminate between warnings, + * errors, information, etc. + * + * @default - no severity + */ + readonly severity?: string; + + /** + * Additional metadata to include with the rule results. + * This can be used to provide additional information that is + * plugin specific. The data provided here will be rendered as is. + * + * @default - no rule metadata + */ + readonly ruleMetadata?: { readonly [key: string]: string }; +} + +/** + * Resource violating a specific rule. + */ +export interface PolicyViolatingResource { + /** + * The logical ID of the resource in the CloudFormation template. + */ + readonly resourceLogicalId: string; + + /** + * The locations in the CloudFormation template that pose the violations. + */ + readonly locations: string[]; + + /** + * The path to the CloudFormation template that contains this resource + */ + readonly templatePath: string; +} + +/** + * The final status of the validation report + */ +export enum PolicyValidationReportStatus { + /** + * No violations were found + */ + SUCCESS = 'success', + + /** + * At least one violation was found + */ + FAILURE = 'failure', +} + +/** + * The report emitted by the plugin after evaluation. + */ +export interface PolicyValidationPluginReport { + /** + * List of violations in the report. + */ + readonly violations: PolicyViolation[]; + + /** + * Whether or not the report was successful. + */ + readonly success: boolean; + + /** + * The version of the plugin that created the report. + * @default - no version + */ + readonly pluginVersion?: string; + + /** + * Arbitrary information about the report. + * + * @default - no metadata + */ + readonly metadata?: { readonly [key: string]: string }; +} + +/** + * Violation produced by the validation plugin. + * + * @deprecated Use `PolicyViolation` instead. + */ export interface PolicyViolationBeta1 { /** * The name of the rule. @@ -45,6 +155,8 @@ export interface PolicyViolationBeta1 { /** * Resource violating a specific rule. + * + * @deprecated Use `PolicyViolatingResource` instead. */ export interface PolicyViolatingResourceBeta1 { /** @@ -65,6 +177,8 @@ export interface PolicyViolatingResourceBeta1 { /** * The final status of the validation report + * + * @deprecated Use `PolicyValidationReportStatus` instead. */ export enum PolicyValidationReportStatusBeta1 { /** @@ -80,6 +194,8 @@ export enum PolicyValidationReportStatusBeta1 { /** * The report emitted by the plugin after evaluation. + * + * @deprecated Use `PolicyValidationPluginReport` instead. */ export interface PolicyValidationPluginReportBeta1 { /** diff --git a/packages/aws-cdk-lib/core/lib/validation/validation.ts b/packages/aws-cdk-lib/core/lib/validation/validation.ts index c9a8edeb8b2e8..64b01e1dd070d 100644 --- a/packages/aws-cdk-lib/core/lib/validation/validation.ts +++ b/packages/aws-cdk-lib/core/lib/validation/validation.ts @@ -1,4 +1,4 @@ -import type { PolicyValidationPluginReportBeta1 } from './report'; +import type { PolicyValidationPluginReport, PolicyValidationPluginReportBeta1 } from './report'; /** * Represents a validation plugin that will be executed during synthesis @@ -29,6 +29,54 @@ import type { PolicyValidationPluginReportBeta1 } from './report'; * } * } */ +export interface IPolicyValidationPlugin { + /** + * The name of the plugin that will be displayed in the validation + * report + */ + readonly name: string; + + /** + * The version of the plugin, following the Semantic Versioning specification (see + * https://semver.org/). This version is used for analytics purposes, to + * measure the usage of different plugins and different versions. The value of + * this property should be kept in sync with the actual version of the + * software package. If the version is not provided or is not a valid semantic + * version, it will be reported as `0.0.0`. + */ + readonly version?: string; + + /** + * The list of rule IDs that the plugin will evaluate. Used for analytics + * purposes. + * + * @default - No rule is reported + */ + readonly ruleIds?: string[]; + + /** + * The method that will be called by the CDK framework to perform + * validations. This is where the plugin will evaluate the CloudFormation + * templates for compliance and report and violations + */ + validate(context: IPolicyValidationContext): PolicyValidationPluginReport; +} + +/** + * Context available to the validation plugin + */ +export interface IPolicyValidationContext { + /** + * The absolute path of all templates to be processed + */ + readonly templatePaths: string[]; +} + +/** + * Represents a validation plugin that will be executed during synthesis + * + * @deprecated Use `IPolicyValidationPlugin` instead. + */ export interface IPolicyValidationPluginBeta1 { /** * The name of the plugin that will be displayed in the validation @@ -64,6 +112,8 @@ export interface IPolicyValidationPluginBeta1 { /** * Context available to the validation plugin + * + * @deprecated Use `IPolicyValidationContext` instead. */ export interface IPolicyValidationContextBeta1 { /** diff --git a/packages/aws-cdk-lib/core/test/validation/validation.test.ts b/packages/aws-cdk-lib/core/test/validation/validation.test.ts index c2312c2994596..690aee815f166 100644 --- a/packages/aws-cdk-lib/core/test/validation/validation.test.ts +++ b/packages/aws-cdk-lib/core/test/validation/validation.test.ts @@ -812,6 +812,12 @@ Policy Validation Report Summary const consoleReport = consoleErrorMock.mock.calls[1][0]; expect(consoleReport).toContain('Validation Report'); }); + + test('a plugin implementing Beta1 is assignable to IPolicyValidationPlugin', () => { + const beta1Plugin: core.IPolicyValidationPluginBeta1 = new FakePlugin('beta1-plugin', []); + const plugin: core.IPolicyValidationPlugin = beta1Plugin; + expect(plugin.name).toEqual('beta1-plugin'); + }); }); class FakePlugin implements core.IPolicyValidationPluginBeta1 {