build(deps-dev)!: migrate to cdk-nag 3.0.1 (policy-validation plugin engine)#99
Merged
Conversation
…engine) cdk-nag v3 rewrites the rule packs from per-stack IAspects onto CDK's native policy validation framework, which changes how packs attach, how suppressions work, and — critically — how failure is signaled. This migration covers all of it; supersedes #94, whose bare version bump cannot compile against the v3 API. Engine: the five packs are now plugins registered once at the App root (attach_nag_packs, called from app.py and every nag-gating test fixture). apply_compliance_aspects stays per stack carrying the project's TemplateConventionChecks Aspect plus cdk-nag's WriteNagSuppressionsToCloudFormationAspect — per stack because Aspects do not cross cdk.Stage boundaries (verified live: an App-level registration silently skipped every Stage-nested stack), which is what keeps the v2-style cdk_nag Metadata audit trail in the templates and snapshots. Suppressions: NagSuppressions is gone; acknowledge_rules in nag_utils adapts this repo's unchanged {id, reason, applies_to} data shape onto Validations.of().acknowledge(). v3 matches granular IAM4/IAM5 findings individually — a bare rule id matches nothing — so every previously blanket wildcard is now enumerated with its exact finding id (singleton IAM4 managed policies, the BucketDeployment handler's seven s3 grants, the RUM cleanup log-group ARN, CodeDeploy and API Gateway CloudWatch roles). Two upstream sharp edges are worked around and documented in place: CDK's acknowledge API rejects ids with more than one '::' while the packs emit exactly such ids for IAM4 (metadata fallback in acknowledge_rules), and raw IAM5 resource finding ids reproduce whichever partition rendering the synth used (both arn:aws: and arn:<AWS::Partition>: forms acknowledged where ARNs embed partitions). Gate integrity: CDK signals validation failure by setting process.exitCode in the NODE process — jsii's throwaway kernel for a Python app — so neither app.synth() nor cdk synth fails natively (verified live: a non-compliant canary synthesized 'successfully' via the CLI). The hard gate is now explicit on both paths: scripts/check_validation_report.py (fails on violations AND on a missing report) runs after synth in make cdk-synth and the CI cdk-check job, and TestNagCompliance parses each shape's validation-report.json in-process, with test_nag_gate_can_fail as the non-vacuousness canary. That CLI checker caught the partition-rendering split during this very migration. The RUM cleanup grant ARN switched from a token-embedding monitor-id prefix to a monitor-name suffix wildcard: the delete call still targets the exact log group, and the literal ARN is what makes the finding id reproducible enough to acknowledge. Docs updated (CLAUDE.md nag sections, nine README passages); snapshots regenerated — the metadata diff is the v3 write-aspect recording acknowledgments subtree-wide.
🏗️ CDK infra diff — PR vs
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Supersedes #94 — the bare Dependabot bump cannot compile: cdk-nag v3 rewrites the packs from per-stack
IAspects onto CDK's policy validation framework, removesNagSuppressions, and changes granular-finding matching. This PR does the full migration.What changed
attach_nag_packs, called fromapp.pyand every nag-gating test fixture).apply_compliance_aspectsstays per stack withTemplateConventionChecksplus cdk-nag'sWriteNagSuppressionsToCloudFormationAspect— per stack because Aspects don't crosscdk.Stageboundaries (verified live; App-level registration silently dropped thecdk_nagtemplate metadata for every nested stack).acknowledge_rulesinnag_utils.pyadapts the repo's unchanged{id, reason, applies_to}data shape ontoValidations.of().acknowledge(). All 23 call sites converted with their data intact; previously-blanket granular wildcards (singleton IAM4/IAM5, BucketDeployment s3 grants, RUM cleanup ARN, CodeDeploy/APIGW roles) are now enumerated with exactRule[Finding]ids, since v3 matches granular findings individually.process.exitCodein the Node process — jsii's throwaway kernel for a Python app — so neitherapp.synth()norcdk synthfails natively (live-verified with a non-compliant canary). The hard gate is now explicit on both paths:scripts/check_validation_report.pyafter synth inmake cdk-synth+ CIcdk-check(fails on violations and on a missing report);TestNagComplianceparses each deployment shape'svalidation-report.jsonin-process, withtest_nag_gate_can_failas the non-vacuousness canary.Upstream sharp edges worked around (documented in place)
::, yet the packs emit exactly such ids for IAM4 managed-policy findings →acknowledge_rulesroutes those through theaws:cdk:acknowledged-rulesmetadata fallback the plugin demonstrably honors.arn:aws:under cdk.json'senablePartitionLiterals,arn:<AWS::Partition>:in flag-less test synth) → both forms acknowledged where ARNs embed partitions. The new CLI checker caught this split during the migration itself.Verification
make prfully green: lockfile drift check, all pre-commit hooks, mypy both venvs, markdownlint, unit tests (100% lambda/ gate), 146 CDK assertions (all four deployment shapes nag-clean + canary), Docker CLI synth +cdk-nag validation cleanfrom the report checker, OpenAPI drift.🤖 Generated with Claude Code