API Reference

Constructs

PDKNagApp

Initializers

import { PDKNagApp } from '@aws/pdk/pdk-nag'

new PDKNagApp(props?: PDKNagAppProps)

Name	Type	Description
`props`	`PDKNagAppProps`	No description.

`props`^Optional

Type: PDKNagAppProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`synth`	Synthesize this stage into a cloud assembly.
`addExtendedNagResults`	No description.
`addNagResult`	No description.
`extendedNagResults`	Returns a list of ExtendedNagResult.
`nagResults`	Returns a list of NagResult.

`toString`

public toString(): string

Returns a string representation of this construct.

`synth`

public synth(options?: StageSynthesisOptions): CloudAssembly

Synthesize this stage into a cloud assembly.

Once an assembly has been synthesized, it cannot be modified. Subsequent calls will return the same assembly.

`options`^Optional

Type: aws-cdk-lib.StageSynthesisOptions

`addExtendedNagResults`

public addExtendedNagResults(results: ExtendedNagResult): void

`results`^Required

Type: ExtendedNagResult

`addNagResult`

public addNagResult(result: NagResult): void

`result`^Required

Type: NagResult

`extendedNagResults`

public extendedNagResults(): ExtendedNagResult[]

Returns a list of ExtendedNagResult.

Note: app.synth() must be called before this to retrieve results.

`nagResults`

public nagResults(): NagResult[]

Returns a list of NagResult.

Note: app.synth() must be called before this to retrieve results.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isStage`	Test whether the given construct is a stage.
`of`	Return the stage this construct is contained with, if available.
`isApp`	Checks if an object is an instance of the `App` class.

`isConstruct`

import { PDKNagApp } from '@aws/pdk/pdk-nag'

PDKNagApp.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

`x`^Required

Type: any

Any object.

`isStage`

import { PDKNagApp } from '@aws/pdk/pdk-nag'

PDKNagApp.isStage(x: any)

Test whether the given construct is a stage.

`x`^Required

Type: any

`of`

import { PDKNagApp } from '@aws/pdk/pdk-nag'

PDKNagApp.of(construct: IConstruct)

Return the stage this construct is contained with, if available.

If called on a nested stage, returns its parent.

`construct`^Required

Type: constructs.IConstruct

`isApp`

import { PDKNagApp } from '@aws/pdk/pdk-nag'

PDKNagApp.isApp(obj: any)

Checks if an object is an instance of the App class.

`obj`^Required

Type: any

The object to evaluate.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`artifactId`	`string`	Artifact ID of the assembly if it is a nested stage. The root stage (app) will return an empty string.
`assetOutdir`	`string`	The cloud assembly asset output directory.
`outdir`	`string`	The cloud assembly output directory.
`policyValidationBeta1`	`aws-cdk-lib.IPolicyValidationPluginBeta1[]`	Validation plugins to run during synthesis.
`stageName`	`string`	The name of the stage.
`account`	`string`	The default account for all resources defined within this stage.
`parentStage`	`aws-cdk-lib.Stage`	The parent stage or `undefined` if this is the app.
`region`	`string`	The default region for all resources defined within this stage.
`nagPacks`	`cdk-nag.NagPack[]`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`artifactId`^Required

public readonly artifactId: string;

Type: string

Artifact ID of the assembly if it is a nested stage. The root stage (app) will return an empty string.

Derived from the construct path.

`assetOutdir`^Required

public readonly assetOutdir: string;

Type: string

The cloud assembly asset output directory.

`outdir`^Required

public readonly outdir: string;

Type: string

The cloud assembly output directory.

`policyValidationBeta1`^Required

public readonly policyValidationBeta1: IPolicyValidationPluginBeta1[];

Type: aws-cdk-lib.IPolicyValidationPluginBeta1[]
Default: no validation plugins are used

Validation plugins to run during synthesis.

If any plugin reports any violation, synthesis will be interrupted and the report displayed to the user.

`stageName`^Required

public readonly stageName: string;

Type: string

The name of the stage.

Based on names of the parent stages separated by hypens.

`account`^Optional

public readonly account: string;

Type: string

The default account for all resources defined within this stage.

`parentStage`^Optional

public readonly parentStage: Stage;

Type: aws-cdk-lib.Stage

The parent stage or undefined if this is the app.

*

`region`^Optional

public readonly region: string;

Type: string

The default region for all resources defined within this stage.

`nagPacks`^Required

public readonly nagPacks: NagPack[];

Type: cdk-nag.NagPack[]

Structs

ExtendedNagResult

Represents the result of applying a CDK Nag rule to a resource.

Initializer

import { ExtendedNagResult } from '@aws/pdk/pdk-nag'

const extendedNagResult: ExtendedNagResult = { ... }

Properties

Name	Type	Description
`compliance`	`NagResultCompliance`	Compliance status of the rule against the resource.
`nagPackName`	`string`	The name of the nag pack this rule is from.
`resource`	`aws-cdk-lib.CfnResource`	The resource the rule was applied to.
`ruleExplanation`	`string`	Why the rule exists.
`ruleId`	`string`	The ID of the rule in this nag pack.
`ruleInfo`	`string`	Why the rule was triggered.
`ruleLevel`	`cdk-nag.NagMessageLevel`	The severity level of the rule.
`ruleOriginalName`	`string`	The original name of the rule (regardless of nag pack).
`errorMessage`	`string`	The error that was thrown, only set for error results.
`findingId`	`string`	The finding that was checked, only set for non-compliant results.
`suppressionReason`	`string`	The reason the rule was suppressed, if any.

`compliance`^Required

public readonly compliance: NagResultCompliance;

Type: NagResultCompliance

Compliance status of the rule against the resource.

`nagPackName`^Required

public readonly nagPackName: string;

Type: string

The name of the nag pack this rule is from.

`resource`^Required

public readonly resource: CfnResource;

Type: aws-cdk-lib.CfnResource

The resource the rule was applied to.

`ruleExplanation`^Required

public readonly ruleExplanation: string;

Type: string

Why the rule exists.

`ruleId`^Required

public readonly ruleId: string;

Type: string

The ID of the rule in this nag pack.

`ruleInfo`^Required

public readonly ruleInfo: string;

Type: string

Why the rule was triggered.

`ruleLevel`^Required

public readonly ruleLevel: NagMessageLevel;

Type: cdk-nag.NagMessageLevel

The severity level of the rule.

`ruleOriginalName`^Required

public readonly ruleOriginalName: string;

Type: string

The original name of the rule (regardless of nag pack).

`errorMessage`^Optional

public readonly errorMessage: string;

Type: string

The error that was thrown, only set for error results.

`findingId`^Optional

public readonly findingId: string;

Type: string

The finding that was checked, only set for non-compliant results.

`suppressionReason`^Optional

public readonly suppressionReason: string;

Type: string

The reason the rule was suppressed, if any.

Message

Message instance.

Initializer

import { Message } from '@aws/pdk/pdk-nag'

const message: Message = { ... }

Properties

Name	Type	Description
`messageDescription`	`string`	Message description.
`messageType`	`string`	Message type as returned from cdk-nag.

`messageDescription`^Required

public readonly messageDescription: string;

Type: string

Message description.

`messageType`^Required

public readonly messageType: string;

Type: string

Message type as returned from cdk-nag.

NagResult

Nag result.

Initializer

import { NagResult } from '@aws/pdk/pdk-nag'

const nagResult: NagResult = { ... }

Properties

Name	Type	Description
`messages`	`Message[]`	List of messages.
`resource`	`string`	Resource which triggered the message.

`messages`^Required

public readonly messages: Message[];

Type: Message[]

List of messages.

`resource`^Required

public readonly resource: string;

Type: string

Resource which triggered the message.

PDKNagAppProps

Initializer

import { PDKNagAppProps } from '@aws/pdk/pdk-nag'

const pDKNagAppProps: PDKNagAppProps = { ... }

Properties

Name	Type	Description
`analyticsReporting`	`boolean`	Include runtime versioning information in the Stacks of this app.
`autoSynth`	`boolean`	Automatically call `synth()` before the program exits.
`context`	`{[ key: string ]: any}`	Additional context values for the application.
`defaultStackSynthesizer`	`aws-cdk-lib.IReusableStackSynthesizer`	The stack synthesizer to use by default for all Stacks in the App.
`outdir`	`string`	The output directory into which to emit synthesized artifacts.
`policyValidationBeta1`	`aws-cdk-lib.IPolicyValidationPluginBeta1[]`	Validation plugins to run after synthesis.
`postCliContext`	`{[ key: string ]: any}`	Additional context values for the application.
`stackTraces`	`boolean`	Include construct creation stack trace in the `aws:cdk:trace` metadata key of all constructs.
`treeMetadata`	`boolean`	Include construct tree metadata as part of the Cloud Assembly.
`failOnError`	`boolean`	Determines whether any errors encountered should trigger a test failure.
`failOnWarning`	`boolean`	Determines whether any warnings encountered should trigger a test failure.
`nagPacks`	`cdk-nag.NagPack[]`	Custom nag packs to execute.

`analyticsReporting`^Optional

public readonly analyticsReporting: boolean;

Type: boolean
Default: Value of 'aws:cdk:version-reporting' context key

Include runtime versioning information in the Stacks of this app.

`autoSynth`^Optional

public readonly autoSynth: boolean;

Type: boolean
Default: true if running via CDK CLI (CDK_OUTDIR is set), false otherwise

Automatically call synth() before the program exits.

If you set this, you don't have to call synth() explicitly. Note that this feature is only available for certain programming languages, and calling synth() is still recommended.

`context`^Optional

public readonly context: {[ key: string ]: any};

Type: {[ key: string ]: any}
Default: no additional context

Additional context values for the application.

Context set by the CLI or the context key in cdk.json has precedence.

Context can be read from any construct using node.getContext(key).

`defaultStackSynthesizer`^Optional

public readonly defaultStackSynthesizer: IReusableStackSynthesizer;

Type: aws-cdk-lib.IReusableStackSynthesizer
Default: A DefaultStackSynthesizer with default settings

The stack synthesizer to use by default for all Stacks in the App.

The Stack Synthesizer controls aspects of synthesis and deployment, like how assets are referenced and what IAM roles to use. For more information, see the README of the main CDK package.

`outdir`^Optional

public readonly outdir: string;

Type: string
Default: If this value is not set, considers the environment variable CDK_OUTDIR. If CDK_OUTDIR is not defined, uses a temp directory.

The output directory into which to emit synthesized artifacts.

You should never need to set this value. By default, the value you pass to the CLI's --output flag will be used, and if you change it to a different directory the CLI will fail to pick up the generated Cloud Assembly.

This property is intended for internal and testing use.

`policyValidationBeta1`^Optional

public readonly policyValidationBeta1: IPolicyValidationPluginBeta1[];

Type: aws-cdk-lib.IPolicyValidationPluginBeta1[]
Default: no validation plugins

Validation plugins to run after synthesis.

`postCliContext`^Optional

public readonly postCliContext: {[ key: string ]: any};

Type: {[ key: string ]: any}
Default: no additional context

Additional context values for the application.

Context provided here has precedence over context set by:

The CLI via --context
The context key in cdk.json
The AppProps.context property

This property is recommended over the AppProps.context property since you can make final decision over which context value to take in your app.

Context can be read from any construct using node.getContext(key).

Example

// context from the CLI and from `cdk.json` are stored in the
// CDK_CONTEXT env variable
const cliContext = JSON.parse(process.env.CDK_CONTEXT!);

// determine whether to take the context passed in the CLI or not
const determineValue = process.env.PROD ? cliContext.SOMEKEY : 'my-prod-value';
new App({
  postCliContext: {
    SOMEKEY: determineValue,
  },
});

`stackTraces`^Optional

public readonly stackTraces: boolean;

Type: boolean
Default: true stack traces are included unless aws:cdk:disable-stack-trace is set in the context.

Include construct creation stack trace in the aws:cdk:trace metadata key of all constructs.

`treeMetadata`^Optional

public readonly treeMetadata: boolean;

Type: boolean
Default: true

Include construct tree metadata as part of the Cloud Assembly.

`failOnError`^Optional

public readonly failOnError: boolean;

Type: boolean
Default: false

Determines whether any errors encountered should trigger a test failure.

`failOnWarning`^Optional

public readonly failOnWarning: boolean;

Type: boolean
Default: false

Determines whether any warnings encountered should trigger a test failure.

`nagPacks`^Optional

public readonly nagPacks: NagPack[];

Type: cdk-nag.NagPack[]
Default: DEFAULT_NAG_PACKS

Custom nag packs to execute.

Classes

AwsPrototypingChecks

Check best practices for prototypes.

Initializers

import { AwsPrototypingChecks } from '@aws/pdk/pdk-nag'

new AwsPrototypingChecks(props?: NagPackProps)

Name	Type	Description
`props`	`cdk-nag.NagPackProps`	No description.

`props`^Optional

Type: cdk-nag.NagPackProps

Methods

Name	Description
`visit`	Check if CfnResource and apply rules.

`visit`

public visit(node: IConstruct): void

Check if CfnResource and apply rules.

`node`^Required

Type: constructs.IConstruct

Properties

Name	Type	Description
`readPackName`	`string`	No description.

`readPackName`^Required

public readonly readPackName: string;

Type: string

PDKNag

Helper for create a Nag Enabled App.

Initializers

import { PDKNag } from '@aws/pdk/pdk-nag'

new PDKNag()

Name	Type	Description

Static Functions

Name	Description
`addResourceSuppressionsByPathNoThrow`	Wrapper around NagSuppressions which does not throw.
`app`	Returns an instance of an App with Nag enabled.
`getStackAccountRegex`	Returns a stack account regex.
`getStackPartitionRegex`	Returns a stack partition regex.
`getStackPrefix`	Returns a prefix comprising of a delimited set of Stack Ids.
`getStackRegionRegex`	Returns a stack region regex.

`addResourceSuppressionsByPathNoThrow`

import { PDKNag } from '@aws/pdk/pdk-nag'

PDKNag.addResourceSuppressionsByPathNoThrow(stack: Stack, path: string, suppressions: NagPackSuppression[], applyToChildren?: boolean)

Wrapper around NagSuppressions which does not throw.

`stack`^Required

Type: aws-cdk-lib.Stack

stack instance.

`path`^Required

Type: string

resource path.

`suppressions`^Required

Type: cdk-nag.NagPackSuppression[]

list of suppressions to apply.

`applyToChildren`^Optional

Type: boolean

whether to apply to children.

`app`

import { PDKNag } from '@aws/pdk/pdk-nag'

PDKNag.app(props?: PDKNagAppProps)

Returns an instance of an App with Nag enabled.

`props`^Optional

Type: PDKNagAppProps

props to initialize the app with.

`getStackAccountRegex`

import { PDKNag } from '@aws/pdk/pdk-nag'

PDKNag.getStackAccountRegex(stack: Stack)

Returns a stack account regex.

`stack`^Required

Type: aws-cdk-lib.Stack

stack instance.

`getStackPartitionRegex`

import { PDKNag } from '@aws/pdk/pdk-nag'

PDKNag.getStackPartitionRegex(stack: Stack)

Returns a stack partition regex.

`stack`^Required

Type: aws-cdk-lib.Stack

stack instance.

`getStackPrefix`

import { PDKNag } from '@aws/pdk/pdk-nag'

PDKNag.getStackPrefix(stack: Stack)

Returns a prefix comprising of a delimited set of Stack Ids.

For example: StackA/NestedStackB/

`stack`^Required

Type: aws-cdk-lib.Stack

stack instance.

`getStackRegionRegex`

import { PDKNag } from '@aws/pdk/pdk-nag'

PDKNag.getStackRegionRegex(stack: Stack)

Returns a stack region regex.

`stack`^Required

Type: aws-cdk-lib.Stack

stack instance.

Enums

NagResultCompliance

Possible statuses for nag rules.

Members

Name	Description
`COMPLIANT`	Resource complies with the rule.
`NON_COMPLIANT`	Resource does not comply with the rule.
`NON_COMPLIANT_SUPPRESSED`	Resource does not comply with the rule, but the rule was suppressed.
`ERROR`	An error occurred applying the rule.
`ERROR_SUPPRESSED`	An error occurred applying the rule, but the rule was suppressed.
`NOT_APPLICABLE`	The rule is not applicable to the resource.

`COMPLIANT`

Resource complies with the rule.

`NON_COMPLIANT`

Resource does not comply with the rule.

`NON_COMPLIANT_SUPPRESSED`

Resource does not comply with the rule, but the rule was suppressed.

`ERROR`

An error occurred applying the rule.

`ERROR_SUPPRESSED`

An error occurred applying the rule, but the rule was suppressed.

`NOT_APPLICABLE`

The rule is not applicable to the resource.

Last update: 2024-10-30

API Reference

Constructs

PDKNagApp

Initializers

propsOptional

Methods

toString

synth

optionsOptional

addExtendedNagResults

resultsRequired

addNagResult

resultRequired

extendedNagResults

nagResults

Static Functions

isConstruct

xRequired

isStage

xRequired

of

constructRequired

isApp

objRequired

Properties

nodeRequired

artifactIdRequired

assetOutdirRequired

outdirRequired

policyValidationBeta1Required

stageNameRequired

accountOptional

parentStageOptional

regionOptional

nagPacksRequired

Structs

ExtendedNagResult

Initializer

Properties

complianceRequired

nagPackNameRequired

resourceRequired

ruleExplanationRequired

ruleIdRequired

ruleInfoRequired

ruleLevelRequired

ruleOriginalNameRequired

errorMessageOptional

findingIdOptional

suppressionReasonOptional

Message

Initializer

Properties

messageDescriptionRequired

messageTypeRequired

NagResult

Initializer

Properties

messagesRequired

resourceRequired

PDKNagAppProps

Initializer

Properties

analyticsReportingOptional

autoSynthOptional

contextOptional

defaultStackSynthesizerOptional

outdirOptional

policyValidationBeta1Optional

postCliContextOptional

stackTracesOptional

treeMetadataOptional

failOnErrorOptional

failOnWarningOptional

nagPacksOptional

Classes

AwsPrototypingChecks

Initializers

propsOptional

Methods

`props`^Optional

`toString`

`synth`

`options`^Optional

`addExtendedNagResults`

`results`^Required

`addNagResult`

`result`^Required

`extendedNagResults`

`nagResults`

`isConstruct`

`x`^Required

`isStage`

`x`^Required

`of`

`construct`^Required

`isApp`

`obj`^Required

`node`^Required

`artifactId`^Required

`assetOutdir`^Required

`outdir`^Required

`policyValidationBeta1`^Required

`stageName`^Required

`account`^Optional

`parentStage`^Optional

`region`^Optional

`nagPacks`^Required

`compliance`^Required

`nagPackName`^Required

`resource`^Required

`ruleExplanation`^Required

`ruleId`^Required

`ruleInfo`^Required

`ruleLevel`^Required

`ruleOriginalName`^Required

`errorMessage`^Optional

`findingId`^Optional

`suppressionReason`^Optional

`messageDescription`^Required

`messageType`^Required

`messages`^Required

`resource`^Required

`analyticsReporting`^Optional

`autoSynth`^Optional

`context`^Optional

`defaultStackSynthesizer`^Optional

`outdir`^Optional

`policyValidationBeta1`^Optional

`postCliContext`^Optional

`stackTraces`^Optional

`treeMetadata`^Optional

`failOnError`^Optional

`failOnWarning`^Optional

`nagPacks`^Optional

`props`^Optional

`visit`

`node`^Required

`readPackName`^Required

`addResourceSuppressionsByPathNoThrow`

`stack`^Required

`path`^Required

`suppressions`^Required

`applyToChildren`^Optional

`app`

`props`^Optional

`getStackAccountRegex`

`stack`^Required

`getStackPartitionRegex`

`stack`^Required

`getStackPrefix`

`stack`^Required

`getStackRegionRegex`

`stack`^Required

`COMPLIANT`

`NON_COMPLIANT`

`NON_COMPLIANT_SUPPRESSED`

`ERROR`

`ERROR_SUPPRESSED`

`NOT_APPLICABLE`