Skip to content

API Reference

Constructs

PDKNagApp

Initializers

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

new PDKNagApp(props?: PDKNagAppProps)
Name Type Description
props PDKNagAppProps No description.

propsOptional

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.

optionsOptional
  • Type: aws-cdk-lib.StageSynthesisOptions

addExtendedNagResults
public addExtendedNagResults(results: ExtendedNagResult): void
resultsRequired

addNagResult
public addNagResult(result: NagResult): void
resultRequired

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.

xRequired
  • Type: any

Any object.


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

PDKNagApp.isStage(x: any)

Test whether the given construct is a stage.

xRequired
  • 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.

constructRequired
  • 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.

objRequired
  • 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.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


artifactIdRequired
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.


assetOutdirRequired
public readonly assetOutdir: string;
  • Type: string

The cloud assembly asset output directory.


outdirRequired
public readonly outdir: string;
  • Type: string

The cloud assembly output directory.


policyValidationBeta1Required
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.


stageNameRequired
public readonly stageName: string;
  • Type: string

The name of the stage.

Based on names of the parent stages separated by hypens.


accountOptional
public readonly account: string;
  • Type: string

The default account for all resources defined within this stage.


parentStageOptional
public readonly parentStage: Stage;
  • Type: aws-cdk-lib.Stage

The parent stage or undefined if this is the app.

*


regionOptional
public readonly region: string;
  • Type: string

The default region for all resources defined within this stage.


nagPacksRequired
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.

complianceRequired
public readonly compliance: NagResultCompliance;

Compliance status of the rule against the resource.


nagPackNameRequired
public readonly nagPackName: string;
  • Type: string

The name of the nag pack this rule is from.


resourceRequired
public readonly resource: CfnResource;
  • Type: aws-cdk-lib.CfnResource

The resource the rule was applied to.


ruleExplanationRequired
public readonly ruleExplanation: string;
  • Type: string

Why the rule exists.


ruleIdRequired
public readonly ruleId: string;
  • Type: string

The ID of the rule in this nag pack.


ruleInfoRequired
public readonly ruleInfo: string;
  • Type: string

Why the rule was triggered.


ruleLevelRequired
public readonly ruleLevel: NagMessageLevel;
  • Type: cdk-nag.NagMessageLevel

The severity level of the rule.


ruleOriginalNameRequired
public readonly ruleOriginalName: string;
  • Type: string

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


errorMessageOptional
public readonly errorMessage: string;
  • Type: string

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


findingIdOptional
public readonly findingId: string;
  • Type: string

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


suppressionReasonOptional
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.

messageDescriptionRequired
public readonly messageDescription: string;
  • Type: string

Message description.


messageTypeRequired
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.

messagesRequired
public readonly messages: Message[];

List of messages.


resourceRequired
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.

analyticsReportingOptional
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.


autoSynthOptional
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.


contextOptional
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).


defaultStackSynthesizerOptional
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.


outdirOptional
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.


policyValidationBeta1Optional
public readonly policyValidationBeta1: IPolicyValidationPluginBeta1[];
  • Type: aws-cdk-lib.IPolicyValidationPluginBeta1[]
  • Default: no validation plugins

Validation plugins to run after synthesis.


postCliContextOptional
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,
  },
});
stackTracesOptional
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.


treeMetadataOptional
public readonly treeMetadata: boolean;
  • Type: boolean
  • Default: true

Include construct tree metadata as part of the Cloud Assembly.


failOnErrorOptional
public readonly failOnError: boolean;
  • Type: boolean
  • Default: false

Determines whether any errors encountered should trigger a test failure.


failOnWarningOptional
public readonly failOnWarning: boolean;
  • Type: boolean
  • Default: false

Determines whether any warnings encountered should trigger a test failure.


nagPacksOptional
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.

propsOptional
  • 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.

nodeRequired
  • Type: constructs.IConstruct

Properties

Name Type Description
readPackName string No description.

readPackNameRequired
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.

stackRequired
  • Type: aws-cdk-lib.Stack

stack instance.


pathRequired
  • Type: string

resource path.


suppressionsRequired
  • Type: cdk-nag.NagPackSuppression[]

list of suppressions to apply.


applyToChildrenOptional
  • 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.

propsOptional

props to initialize the app with.


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

PDKNag.getStackAccountRegex(stack: Stack)

Returns a stack account regex.

stackRequired
  • Type: aws-cdk-lib.Stack

stack instance.


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

PDKNag.getStackPartitionRegex(stack: Stack)

Returns a stack partition regex.

stackRequired
  • 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/

stackRequired
  • Type: aws-cdk-lib.Stack

stack instance.


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

PDKNag.getStackRegionRegex(stack: Stack)

Returns a stack region regex.

stackRequired
  • 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-11-28