@shieldly/cdk-guard

@shieldly/cdk-guard

AI-Powered AWS security analysis for CDK apps. Catch risky IAM policies and CloudFormation misconfigurations on every cdk synth — before you deploy.

npm install --save-dev @shieldly/cdk-guard

Get an API key at shieldly.io/app/api (API keys require a Builder plan or above; a free demo runs without a key).

Privacy: your CDK templates are never logged. Cache keys are one-way SHA-256 hashes.

Ways to use it

1. CLI — no code changes (any language CDK app)

Runs cdk synth then analyzes all synthesized stacks:

npx @shieldly/cdk-guard

# Pass extra cdk synth flags after --
npx @shieldly/cdk-guard -- --context env=prod

# Fail only on Critical findings
npx @shieldly/cdk-guard --fail-on Critical

# Analyze an existing cdk.out/ without re-synthesizing
npx @shieldly/cdk-guard --no-synth --out-dir cdk.out

# JSON output for scripting
npx @shieldly/cdk-guard --format json | jq '.[].findings[]'

Set your API key via environment variable:

export SHIELDLY_API_KEY=sk_live_...
npx @shieldly/cdk-guard

2. CDK Construct — hook-based (JavaScript/TypeScript CDK apps)

Add ShieldlyGuard to your CDK app. It runs automatically after cdk synth via process.on('beforeExit') — no explicit call needed.

import * as cdk from 'aws-cdk-lib';
import { ShieldlyGuard } from '@shieldly/cdk-guard';

const app = new cdk.App();

// Add the guard — reads SHIELDLY_API_KEY from environment by default.
new ShieldlyGuard({
  failOn: 'High',  // Critical | High | Medium | Low | none
});

new MyStack(app, 'MyStack');
// Guard analyzes cdk.out/ automatically when the process exits.

Options:

Option	Type	Default	Description
apiKey	string	SHIELDLY_API_KEY env	Shieldly API key
failOn	string	'High'	Exit code 1 if findings at or above this severity
outDir	string	'cdk.out'	CDK output directory to analyze
apiUrl	string	https://api.shieldly.io	Override for self-hosted / dev
silent	boolean	false	Suppress all console output

3. Explicit post-synth (ESM with top-level await)

import * as cdk from 'aws-cdk-lib';
import { shieldlyGuard } from '@shieldly/cdk-guard';

const app = new cdk.App();
const stack = new MyStack(app, 'MyStack');
const assembly = app.synth();

const { failed } = await shieldlyGuard(assembly.directory, {
  failOn: 'High',
});
if (failed) process.exit(1);

4. cdk.json hook

Runs analysis after every cdk synth automatically — works with any CDK language:

{
  "app": "node bin/my-app.js",
  "hooks": {
    "afterSynth": ["npx", "@shieldly/cdk-guard", "--no-synth"]
  }
}

CI / CD

GitHub Actions

- name: CDK security check
  run: npx @shieldly/cdk-guard
  env:
    SHIELDLY_API_KEY: ${{ secrets.SHIELDLY_API_KEY }}

package.json scripts

{
  "scripts": {
    "synth:check": "cdk synth && npx @shieldly/cdk-guard --no-synth",
    "deploy:safe": "npx @shieldly/cdk-guard && cdk deploy"
  }
}

How it works

• Reads the CDK manifest (cdk.out/manifest.json) to find synthesized stack templates for the current synthesis only (not stale outputs from prior runs).
• Sends each *.template.json to the Shieldly AI analysis engine (POST /v1/analyze/cf).
• The AI analyzes IAM roles, policies, resource policies, and CloudFormation security configurations, explaining each finding in plain English and providing the tightened policy.
• Prints results to the terminal. Exits with code 1 if any finding meets or exceeds the failOn severity threshold.

What it analyzes

• IAM roles and managed policies
• Inline policies on Lambda functions, EC2 instances, ECS tasks
• Resource policies (S3 bucket policies, SQS queue policies, KMS key policies)
• CloudFormation security misconfigurations (public S3 buckets, unencrypted resources, overly permissive security groups)

Related

• shieldly.io — web-based IAM Advisor (free demo, no signup)
• @shieldly/cli — analyze from any terminal
• shieldly-io/action — GitHub Action for PR gating
• VS Code extension — search "Shieldly" in the Marketplace
• REST API — integrate into any pipeline

Amazon Web Services (AWS) is a trademark of Amazon.com, Inc. Shieldly is not affiliated with, endorsed by, or sponsored by Amazon Web Services.