DEV Community: Scott Burgholzer

Serverless IaC Risk Analysis: The Architecture Behind Blast Radius

Scott Burgholzer — Tue, 15 Sep 2026 19:40:50 +0000

Series: Introducing Blast Radius — See What Breaks Before You Deploy

The first two articles in this series were about what Blast Radius does and how to wire it into your pipeline. This one is about how it's built. If you've ever wanted to design a system that analyzes infrastructure changes before they deploy, or you're just curious how the risk scores in your PR comment actually get calculated, this is the under-the-hood tour.

I'm going to walk the same path the data walks: from the moment you submit a changeset, through format normalization, dependency discovery, scoring, the AI layer, and out to the frontend. Along the way I'll call out the decisions that mattered and a few that cost me a day to get right.

Four Constraints That Shaped Everything

Every meaningful decision in Blast Radius traces back to one of four constraints. It's worth stating them up front, because the rest of this article is really just the consequences.

It has to accept multiple IaC formats without the analysis engine knowing which one. CDK, CloudFormation, and Terraform describe the same change three different ways. If the scoring logic had to branch on "is this Terraform or CloudFormation," every feature would multiply across every format, and adding a fourth tool would mean touching code everywhere. The engine has to see exactly one shape.

It's asynchronous by nature. A real analysis takes 10-30 seconds. It's making live calls to AWS Config and Resource Explorer, walking a dependency graph, and optionally waiting on a Bedrock model. You can't hold an API Gateway request open that long. The "submit" step and the "give me the answer" step have to be decoupled, which means state has to live somewhere in between.

It should cost nothing at idle and scale with concurrent PRs. This is a tool that runs when someone opens an infrastructure PR. That might be zero times today and forty times tomorrow. Paying for an always-on cluster to serve bursty, unpredictable traffic is the wrong shape. Serverless bills per execution and scales out without anyone tuning autoscaling groups.

The output has to be explainable. A gate that says "blocked: risk 82" and can't tell you why is a gate people rip out the first time it's wrong. Every number the system produces has to decompose back into the inputs that created it. That constraint is the reason the scoring formula is three weighted factors and not a trained model.

Multi-format, async, serverless, explainable. Keep those in mind. Everything below is a response to one of them.

The Canonical Format — The One Decision That Matters Most

If I had to point to a single choice that made the rest of the system tractable, it's this: normalize every input into one canonical format at the edge, then build exactly one analysis engine behind it.

Here's the problem it solves. The same "replace this EC2 instance" event looks completely different depending on who's describing it:

Terraform encodes a replacement as an action array: ["delete", "create"]
CloudFormation encodes it as Action: "Modify" with Replacement: "True"
CDK calls it changeType: "REPLACE"

Three tools, one real-world event, three vocabularies. If discovery and scoring had to understand all three dialects, they'd carry that translation burden forever. Instead, an adapter translates each dialect into a single normalized record the moment it enters the system:

{
  resourceType: "AWS::EC2::Instance",
  resourceId: "i-abc123",
  provider: "aws",
  modificationType: "Replace"  // one consistent representation
}

From that point on, nothing downstream knows or cares where the change came from. Dependency discovery, risk scoring, visualization prep; they all operate on canonical manifests. Terraform-specific and CloudFormation-specific knowledge is quarantined inside the adapters.

The payoff shows up when you add a new tool. Supporting Pulumi or Ansible isn't a cross-cutting change; it's one adapter. You write a function that turns the new tool's diff into canonical records, and the entire engine works unchanged. That's the first constraint satisfied structurally, not by discipline. The architecture makes the wrong thing hard to do.

This is also why the pipeline decides whether to run an adapter as its very first branch, before anything else. The sourceFormat field only exists on the original input; once the manifest is canonical, that information is intentionally gone. So the system asks "does this need conversion?" up front. If the input is already canonical, it skips the adapter entirely and goes straight to validation.

Three formats, three adapters, one canonical manifest, one engine.

Why Step Functions Orchestrates the Pipeline

Given the async and serverless constraints, something has to coordinate a multi-step workflow where each step is a Lambda, steps can fail independently, and the whole thing runs unattended for half a minute. The candidates were the usual ones: chain Lambdas with SQS between them, fan events through EventBridge, or write a custom orchestrator.

I chose Step Functions, and the reason is worth unpacking.

SQS and EventBridge are great for decoupling events, but they're poor at expressing a workflow. The moment you need "run A, then B, then conditionally C, and if any of them fails, mark the whole thing failed," you end up implementing a state machine on top of queues: visibility timeouts, dead-letter queues, correlation IDs, and no single place to see where an execution actually is. A custom orchestrator has the same problem, plus you own all the retry and error semantics yourself.

Step Functions gives you the workflow as a first-class, inspectable object. The full pipeline reads almost like the outline of the analysis itself:

Is format "canonical"?
  No  → Adapter converts to canonical → prepare state
  Yes → skip adapter
→ Ingestion validates the manifest
→ Progress update (20%)
→ Resource Resolver discovers dependencies (AWS Config)
→ Progress update (40%)
→ Risk Assessor scores each resource
→ Progress update (60%)
→ Visualization Prep formats for the frontend + S3
→ Progress update (80%)
→ Is enableSummary = true?
  Yes → Risk Summary generates the AI explanation
  No  → skip summary
→ Mark analysis complete (100%)

Two implementation details in there are load-bearing, and both were the source of real bugs during development.

State preservation with `resultPath`

Each step needs the outputs of prior steps, not just its own immediate input. The naive approach — letting each Lambda's return value replace the state — throws away everything that came before. The pipeline uses resultPath for Discovery, Scoring, and Visualization Prep, which nests each step's output under a new key instead of overwriting the state object:

After Ingestion:  { analysisId, sourceFormat, validatedManifest, options }
After Discovery:  { ...above, discoveryResult: { dependencyGraph, coverage } }
After Scoring:    { ...above, scoringResult: { scoredResources, riskSummary } }
After VisPrep:    { ...above, visualizationResult: { ... } }

That's why Scoring can be handed an explicit payload of { dependencyGraph: $.discoveryResult.dependencyGraph, manifest: $.validatedManifest } — the state still carries both. Using outputPath here instead of resultPath would silently drop the manifest, and the failure wouldn't surface until scoring tried to read a field that no longer existed.

No zombie analyses

Every task state catches States.ALL. On any failure, the pipeline routes to UpdateStatusFailed (which marks the analysis failed in DynamoDB) and then to a terminal PipelineFailed state. This is a small thing that matters enormously for trust: it guarantees the frontend never shows an analysis stuck "running" forever. A crashed Lambda becomes a clean "failed" status the UI can render and the CLI can exit on, instead of a poll loop that never resolves. The CLI's stale detection (five unchanged polls = assumed failure) is a backstop, but the pipeline's catch-everything design is the primary guarantee.

The conditional branches — adapter-or-not at the front, summary-or-not near the end — are the reason Step Functions fits. The summary check uses Condition.and(isPresent('$.options.enableSummary'), booleanEquals(...)) specifically so a missing field doesn't crash the choice state. Expressing that kind of branching in a queue-based system is possible but miserable. Here it's a Choice state you can read at a glance.

Dependency Discovery — Reading the Real Graph, Not the Code

This is the part that makes Blast Radius more than a linter. Everything else operates on data; discovery goes and finds the data by asking AWS what's actually wired together in your account.

The Resource Resolver is the most complex Lambda in the system, and the algorithm is a bounded graph traversal. For each changed resource it queries AWS Config for relationships, then recursively walks those relationships up to maxDepth (default 5), building a graph of nodes and edges as it goes. The Config query itself is a SQL-like statement against the configuration aggregator:

SELECT relationships.resourceId, relationships.resourceType,
       relationships.name, awsRegion, accountId
WHERE resourceId = '<resourceId>'

The key insight is why AWS Config. It tracks the live relationship graph: which security group is attached to which network interface, which instance sits behind which load balancer. That's the ground truth IaC tools are blind to. Resource Explorer is the fallback for resources Config doesn't have full relationship data on, and that feeds a coverage classification:

Full — Config returned relationship data for this resource.
Partial — Resource Explorer found the resource but Config had limited data.
Unknown — the resource couldn't be found in either service.

Coverage is surfaced honestly rather than hidden. If the graph is incomplete, the output says so.

Three engineering details keep discovery correct and affordable:

Cycle protection. Real infrastructure graphs have cycles. The traversal carries a visited-set so a circular relationship (A depends on B depends on A) terminates instead of looping forever.
An LRU cache, 10,000 entries. Deep graphs re-encounter the same resources constantly. Caching Config responses turns a query storm into something far cheaper, and the resolver reports cacheStats: { hits, misses } so the effect is measurable.
Filtering incomplete relationships at the source. Config sometimes returns relationship entries with a missing resourceId. If those slipped through, they'd become orphan nodes and dangling edges — a graph that renders wrong and scores wronger. They're dropped the moment they come back from Config, which is the cleanest place to enforce the invariant. (The API layer filters again before handing data to the frontend, as defense in depth.)

The resolver runs with 1024 MB of memory and a 90-second timeout. Config result sets can be large, and this is the one step where being generous with resources pays off. It also uses a retry-with-backoff wrapper for its AWS calls: transient throttling retries (three attempts), and a service failure degrades the resource's coverage rather than aborting the whole analysis. A Config error alone drops the resource to partial; both Config and Resource Explorer failing drops to unknown. Either way the pipeline continues instead of dying over one unresolvable resource.

The Risk Formula — Deliberately Simple

The explainability constraint is most visible here. It would have been easy, and worse, to train a model. Instead, every resource's risk is a weighted sum of three factors, each normalized to 0-100:

impactScore = round(
  (depthScore        × 0.30) +
  (criticalityScore  × 0.40) +
  (changeTypeSeverity × 0.30)
)

The three factors answer three intuitive questions:

Factor	Question it answers	Weight	Behavior
Depth	How far from the change?	30%	Depth 1 = 100, depth 5 = 60, depth 10 = 10
Criticality	How important is this resource type?	40%	Database = 100, Lambda = 75, S3 = 50, log group = 25
Change severity	How dangerous is the action?	30%	Remove = 100, Replace = 80, Modify = 50, Add = 30

Criticality carries the most weight, and that's on purpose. What is affected matters more than how close it is or what's being done to it. Deleting a throwaway log group one hop away is genuinely less scary than modifying something three hops from a production database, and the weights are tuned so the numbers agree with that intuition. A Critical database at depth 1 hit by a Remove scores 100 (maximum danger); a Low log group at depth 5 hit by a Modify lands around 35 (medium, probably fine). Depth and change type split the remaining 60% evenly because both matter and neither should dominate.

The score-to-category mapping is a plain linear cut, and that's intentional too:

Score	Category
75-100	Critical (red)
50-74	High (orange)
25-49	Medium (yellow)
0-24	Low (green)

No curves, no thresholds that shift based on the graph. A reviewer can look at any score, ask "which factor drove that," and get a straight answer. Each scored resource even carries its dependencyChain — the ordered breadcrumb like sg-abc123 → ec2-instance-1 → rds-prod — and its highestRiskPath, the actual worst-case edges. So "why is this an 82" is always answerable from the resource itself. That auditability is the whole point. A gate people trust is a gate they can interrogate.

The AI Layer — Advisory, Structured, and Optional

The scoring formula is good at "how bad is each individual resource." It's deliberately bad at "is there a systemic pattern here." A fan-out where ten resources each score a harmless 65 but all hang off the single security group you're touching. Any one is fine; all ten failing together is an outage. That's the gap the AI layer fills.

Three principles govern how it's wired in.

The AI reasons over the highest-risk resources; it doesn't compute the scores. There's a clean division of labor. The deterministic engine produces the scored resources and the dependency graph. The Risk Summary Lambda selects the top few highest-scoring resources, hands them plus the overall risk summary to a Bedrock model (Anthropic Claude by default; the model ID is configurable via BEDROCK_MODEL_ID), and asks for a judgment about the deployment as a whole. The model isn't second-guessing arithmetic. It's reasoning about structure the arithmetic can't see. The whole call runs under a 15-second timeout and degrades gracefully: if Bedrock times out or errors, the pipeline still completes with scores intact, just without the narrative.

Its output is structured, not prose-only. The Lambda parses the model's response into a typed shape:

{ "summary": "…markdown…", "recommendDeploy": true, "confidence": "high" }

That structure is what makes the --ai-gate from the previous article possible. A CI gate can't act on a paragraph of English; it can act on recommendDeploy: false. The natural-language summary gets written back into the S3 visualization.json so the frontend and PR comment can render it, but the decision is a boolean the pipeline can branch on.

It's optional at every level. The summary step is a conditional branch in the state machine, gated on enableSummary. The Lambda itself checks both ENABLE_BEDROCK_SUMMARY and ENABLE_BEDROCK before doing anything. If Bedrock is disabled server-side, threshold gates keep working perfectly and the AI gate returns a clean error rather than a confusing empty result. This matters because Bedrock model access isn't universal. The system has to be fully useful without it, and it is.

Frontend and API — Where the Shapes Meet

Two design decisions on the presentation side are worth surfacing, because they're the kind of thing that's invisible when it works and infuriating when it doesn't.

Runtime config, not build-time config. The frontend is a static React SPA served from CloudFront, but it needs to know the API Gateway URL, which isn't known until the stack deploys. Baking the URL in at build time would mean rebuilding the frontend for every deployment and every environment. Instead, CDK writes a /config.json alongside the static assets, and the SPA fetches it at runtime to resolve the API URL. The same build artifact works across environments and in both auth and no-auth modes. It's a small pattern that removes a whole category of "works in staging, wrong URL in prod" bugs.

The API translates between two vocabularies. The pipeline's internal visualization format speaks in nodes and edges. The frontend wants scoredResources and a dependencyGraph shaped for Cytoscape.js. Rather than push that translation into the React app, where it'd be re-implemented and drift, the API handler does the mapping in one place. It also does the final orphan-node and dangling-edge filtering here, so the frontend is guaranteed a clean, renderable graph and never has to defend against malformed input. Put the adaptation at the boundary, keep the consumer simple.

Lessons Learned

A few things this system taught me that generalize well beyond Blast Radius.

Node.js 22 Lambda handlers must be async. This one cost real time. On the Node.js 22 runtime, a synchronous handler returns null — the runtime resolves before your work does. The adapters were the victims: written as plain synchronous functions, they'd "succeed" and hand the pipeline a null manifest, and the failure surfaced three steps later in discovery where it made no sense. The fix is trivial (make handlers async); finding it was not. If you're on a recent Node Lambda runtime, make every handler async by default and save yourself the afternoon.

Dependency injection beats module mocking for testability. Every Lambda that talks to AWS takes an optional deps parameter. In tests you pass mock clients directly; in production the Lambda builds its own. The subtle part is how you detect which you got, because the Lambda runtime passes the Context object as the second argument, which is truthy. A naive deps ?? createDefaultDeps() would treat the Context as your dependencies and explode. The pattern that actually works is a shape check: deps && 'configClient' in deps ? deps : createDefaultDeps(). It looks fussy, but it's the difference between tests that inject cleanly and a production crash that only reproduces in the real runtime. (The next article goes deep on the testing philosophy this enables: property-based tests, and zero vi.mock() calls.)

Long-running pipelines need progress, not just a spinner. A 30-second analysis with no feedback feels broken. The pipeline emits explicit progress updates at fixed milestones — 20% after ingestion, 40% after discovery, 60% after scoring, 80% after visualization, 100% at completion — written to DynamoDB where the frontend and CLI can poll them. The percentages are coarse on purpose. They map to real pipeline stages rather than a fake animation, so "stuck at 40%" is actually diagnostic information (discovery is slow or wedged) rather than decoration.

Wrapping Up

Every one of those decisions maps back to a constraint. The canonical format is how Blast Radius supports multiple IaC tools without the engine ever knowing which one produced the change. Step Functions is how a 30-second workflow runs asynchronously without a zombie analysis in sight. Serverless primitives are how it costs nothing when nobody's opening a PR. And the transparent three-factor formula is how a risk score stays something you can argue with instead of something you have to take on faith.

Next in this series, we get into the build itself:

Article 4: 349 Tests, Zero Mocks — Building Blast Radius in TypeScript: the engineering story. Property-based testing with fast-check, dependency injection over module mocking, the adapter pattern in practice, and an honest retrospective on what I'd do differently.

Stop Deploying Blind: Add a Blast Radius Gate to Your CI/CD Pipeline

Scott Burgholzer — Thu, 09 Jul 2026 03:10:20 +0000

Series: Introducing Blast Radius — See What Breaks Before You Deploy

What We Are Building

This article shows you how to use Blast Radius in your own CI/CD pipeline. By the end, you'll have a deployment gate that automatically analyzes infrastructure changes, scores downstream risk, and blocks merges that exceed your threshold.

Blast Radius comments on your PR with an analysis table (Highest Score, Affected Resources, AI Recommendation, Confidence) plus an AI-generated summary.

There are currently two paths to use Blast Radius:

GitHub Action: fastest and auto-comments on PRs
Raw CLI: works in any CI system such as GitLab, Jenkins, CircleCI, or whatever you're running.

Blast Radius is meant for your infrastructure. It works on any stage: dev, testing, production, or any stages you may use. It calls live AWS APIs (Config and Resource Explorer) against your actual account. The results reflect real dependency relationships, not static analysis.

Prerequisites — Deploy the Backend

The following must be enabled in your AWS Account before deploying the backend:

AWS Config must be enabled and recording in the region you deploy to. This is where Blast Radius reads dependency relationships. Here's how to enable AWS Config.
Resource Explorer must be enabled. It's the fallback for resources Config doesn't have relationships for. Here's how to enable Resource Explorer.
CDK Bootstrap must be run via cdk bootstrap in your account and region you are deploying to.
Optional: Bedrock model access if you want AI summaries. You may choose any model via cross-region inference profile. Without enabling Bedrock model access, threshold gates will still work but the AI gate will not.

Deploy Steps:

git clone https://github.com/sburgholzer/BlastRadius.git
cd BlastRadius
npm install
npm run build
cd packages/infra
cdk deploy

This creates an API Gateway, Step Functions state machine, Lambda functions, DynamoDB tables, S3 bucket, and a CloudFront distribution for the frontend.

When the deployment finishes, grab the API URL from the CDK output. That's the only value you need for the rest of this article.

To enable AI summaries, set enableBedrockSummary in the CDK props. You can also configure resultsRetentionDays for S3 lifecycle management. More detail on these options is in the README.

GitHub Action — The Five-Minute Path

Terraform Workflow

Terraform is the simplest path. Generate the plan, convert it to JSON, and pass it to the action:

- run: terraform plan -out=plan.out
- run: terraform show -json plan.out > plan.json

- uses: sburgholzer/BlastRadius@v0.1.0
  with:
    format: terraform-plan
    input: plan.json
    threshold: 75
    ai-gate: true
    api-url: ${{ secrets.BLAST_RADIUS_URL }}

The action reads the JSON plan, runs the analysis, and comments the results on your PR.

CDK Workflow

CDK requires a few more steps. Blast Radius needs to know what CloudFormation will actually do — the changeset actions, not just what the template looks like. A cdk synth alone doesn't give you that; you have to ask CloudFormation directly.

- name: Generate CloudFormation changeset
  run: |
    npx cdk synth 2>/dev/null
    cp cdk.out/MyStack.template.json template.json
    CHANGESET_NAME="blast-radius-$(date +%s)"
    aws cloudformation create-change-set \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME \
      --template-body file://template.json \
      --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
      --change-set-type UPDATE \
      --output json
    aws cloudformation wait change-set-create-complete \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME
    aws cloudformation describe-change-set \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME \
      --output json > changeset.json
    aws cloudformation delete-change-set \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME

- name: Blast Radius Analysis
  uses: sburgholzer/BlastRadius@v0.1.0
  id: blast-radius
  with:
    format: cloudformation
    input: changeset.json
    threshold: 75
    ai-gate: true
    api-url: ${{ secrets.BLAST_RADIUS_API_URL }}

Each step has a specific job: synth produces the template, create-change-set asks CloudFormation what it would change, wait holds until it's ready, describe-change-set captures the answer as JSON, and delete-change-set cleans up so it doesn't linger between runs.

CloudFormation Workflow

Same as CDK but without the synth step — you already have a template file:

- name: Generate CloudFormation changeset
  run: |
    CHANGESET_NAME="blast-radius-$(date +%s)"
    aws cloudformation create-change-set \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME \
      --template-body file://template.json \
      --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
      --change-set-type UPDATE \
      --output json
    aws cloudformation wait change-set-create-complete \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME
    aws cloudformation describe-change-set \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME \
      --output json > changeset.json
    aws cloudformation delete-change-set \
      --stack-name MyStack \
      --change-set-name $CHANGESET_NAME

- name: Blast Radius Analysis
  uses: sburgholzer/BlastRadius@v0.1.0
  with:
    format: cloudformation
    input: changeset.json
    threshold: 75
    ai-gate: true
    api-url: ${{ secrets.BLAST_RADIUS_API_URL }}

This is essentially the same as the CDK Workflow, except we don't need to run a synth.

What the GitHub Action Does Under the Hood

Downloads the bundled CLI from the GitHub release
Runs analyze with --ci flag for JSON output
Parses the JSON into GitHub Action outputs
Comments on the PR with a formatted table + AI summary (disable with comment-pr: false)

Action inputs:

Input	Required	Default	Description
format	✅		Input format: cloudformation / terraform-plan / canonical
input	✅		Path to the input file (changeset JSON / terraform plan JSON / canonical manifest)
api-url	✅		Blast Radius API URL
threshold			Risk score threshold (0-100). Fails if any resource exceeds this.
ai-gate		false	Fail if AI recommends against deployment
no-summary		false	Skip AI summary generation
comment-pr		true	Automatically comment results on the PR
version		latest	CLI version to use

Action outputs:

Output	Description
analysis-id	The analysis ID
verdict	pass or fail
highest-score	Highest impact score (0-100)
total-affected	Total affected resources
recommend-deploy	AI deployment recommendation (true/false)
confidence	AI recommendation confidence (high/medium/low)
summary	AI-generated risk summary (markdown)
result-json	Full JSON result (for custom downstream steps)

CLI in Any CI System

The GitHub Action is a convenience wrapper. Underneath, it's the CLI. If you're on GitLab, Jenkins, CircleCI, Bitbucket Pipelines, any other tool, or want greater control than the GitHub Action, you can use the CLI directly.

It's a single bundled JavaScript file. No npm install, no dependencies beyond a Node.js runtime. Download it, run it, read the exit code.

How to get the CLI:

curl -sL https://github.com/sburgholzer/BlastRadius/releases/latest/download/blast-radius.js -o blast-radius.js
sed -i '1{/^#!/d}' blast-radius.js

The sed command strips the shebang line. Node.js can't parse #!/usr/bin/env node when you invoke it with node blast-radius.js directly (needed in CI environments that don't support executing .js files as scripts).

Environment setup:

Set BLAST_RADIUS_API_URL as an environment variable pointing to your deployed API Gateway URL. That's the only required config. Everything else goes in command flags.

GitLab CI example

blast-radius:
  image: node:20
  stage: validate
  script:
    - curl -sL https://github.com/sburgholzer/BlastRadius/releases/latest/download/blast-radius.js -o blast-radius.js
    - sed -i '1{/^#!/d}' blast-radius.js
    - node blast-radius.js analyze --format terraform-plan --input plan.json --threshold 75 --ai-gate --ci
  variables:
    BLAST_RADIUS_API_URL: $BLAST_RADIUS_URL
  artifacts:
    paths:
      - blast-radius-result.json
    when: always

Note: --ci outputs JSON to stdout. Capture it with > blast-radius-result.json and save as an artifact for downstream jobs. Exit code 1 naturally fails the GitLab job, no extra configuration needed.

Jenkins example

stage('Blast Radius') {
  environment {
    BLAST_RADIUS_API_URL = credentials('blast-radius-url')
  }
  steps {
    sh '''
      curl -sL https://github.com/sburgholzer/BlastRadius/releases/latest/download/blast-radius.js -o blast-radius.js
      sed -i '1{/^#!/d}' blast-radius.js
      node blast-radius.js analyze --format cloudformation --input changeset.json --threshold 75 --ai-gate --ci
    '''
  }
}

Store your API URL in Jenkins credentials and reference it as an environment variable. Non-zero exit fails the stage, standard Jenkins behavior.

CircleCI example

- run:
    name: Blast Radius Analysis
    command: |
      curl -sL https://github.com/sburgholzer/BlastRadius/releases/latest/download/blast-radius.js -o blast-radius.js
      sed -i '1{/^#!/d}' blast-radius.js
      node blast-radius.js analyze --format terraform-plan --input plan.json --ai-gate --ci
    environment:
      BLAST_RADIUS_API_URL: ${BLAST_RADIUS_URL}

Parsing the JSON output

With --ci, the CLI outputs a JSON object to stdout:

{
  "analysisId": "abc-123",
  "verdict": "fail",
  "exitCode": 1,
  "reason": "ai-gate",
  "recommendDeploy": false,
  "confidence": "high",
  "riskSummary": {
    "highestScore": 82,
    "totalAffected": 14,
    "critical": 2,
    "high": 5,
    "medium": 4,
    "low": 3
  },
  "naturalLanguageSummary": "## Executive Overview\n\nThis deployment presents..."
}

What you can do with this:

Pipe to jq for specific fields: node blast-radius.js analyze ... --ci | jq '.riskSummary.highestScore'
Send to Slack: extract verdict, highestScore, and naturalLanguageSummary into a webhook payload.
Build a custom PR comment in GitLab/Bitbucket using the JSON fields.
Feed into a dashboard or metrics system; track risk scores over time per team or per service.

Exit Codes

Any CI system's native "fail on non-zero" behavior works out of the box. No special error handling needed.

Code	Meaning
0	Pass - threshold OK and AI approves (or gates not enabled)
1	Fail - threshold exceeded OR AI recommends against deployment
2	Error - invalid input / pipeline failure / timeout / misconfiguration

Choosing Your Gate Strategy

Threshold only (`--threshold N`)

This is deterministic. Same input, same result, every time. It's based on the scoring formula from the previous article: depth (how far the resource is from the changed resource), criticality (how critical the resource is to your infrastructure), and change severity (how much the change affects the resource). Each factor is weighted to produce a score between 0 and 100.

Because it's a formula, there's no AI dependency. If you run Blast Radius without Bedrock, you still get a usable result for your CI/CD pipeline.

This gate is good for compliance-driven teams, environments where you need reproducible gates, or if you want to understand how the scoring system works before enabling AI.

N is your cutoff: if the highest score of any resource exceeds that value, Blast Radius fails your pipeline. Here's a general guideline:

90: very permissive. Only blocks Critical-category changes. Good for dev/staging environments.
75: moderate. Blocks Critical and most High-category hits. Good default for production.
50: conservative. Blocks anything above Medium. Good for sensitive workloads.

Start at 75 to see how it works in your environment, then fine-tune from there.

AI gate only (`--ai-gate`)

This is where judgment-based thinking comes into play. The AI gate looks at the full graph, not just the individual scores. It catches patterns like shared dependencies, fan-out risk, and cascading failure paths. It will return recommendDeploy: true/false with confidence: high/medium/low.

This is good for teams that trust AI tooling or want to experiment with it to catch systemic risks. If you use this gate, I recommend reading through the summary and doing manual investigation to verify the reasoning, and to understand what to fix when it blocks.

One caveat: --ai-gate requires Bedrock enabled on the backend. If Bedrock is disabled, the CLI exits with error code 2.

Using Both Gates Together

This is my recommended configuration. When you use both gates, Blast Radius fails your pipeline if EITHER triggers. The threshold catches obvious high-scoring resources. The AI catches non-obvious patterns below your threshold value.

Running Without AI Summary

If you run Blast Radius with --no-summary, it skips the AI-generated natural language summary but will still run the analysis. This saves a few seconds if you only care about the score.

Note: --ai-gate overrides --no-summary because the gate needs the AI to run.

Reading the Output

You've set up the gate. It ran. Now you're looking at a PR comment (or JSON output) with scores, dependency chains, and an AI recommendation. Here's how to read it all.

The PR Comment Anatomy

The GitHub Action comments on your PR with two parts:

Summary table: four key metrics at a glance:
- Highest Score: the single scariest number in the analysis (0-100)
- Affected Resources: total number of downstream resources discovered
- AI Recommendation: Deploy ✅ or Do Not Deploy ❌
- Confidence: how sure the AI is (high/medium/low)
AI-generated summary (if Bedrock is enabled): structured markdown with:
- Executive overview: one-paragraph assessment
- Key findings: the specific resources and patterns that drove the recommendation
- Cascading risks: what could go wrong if you deploy anyway
- Recommendation: the final call with reasoning

If you're using the CLI with --ci, you get the same information as JSON fields: riskSummary, recommendDeploy, confidence, and naturalLanguageSummary.

Risk Scores — What the Numbers Mean

Score	Category	Meaning
75-100	Critical (red)	Direct or near-direct impact on high-criticality resources (databases, auth systems, core networking). Stop and think.
50-74	High (orange)	Significant downstream impact. Review the dependency chain before deploying.
25-49	Medium (yellow)	Worth noting. Probably fine, but look at what's at the end of the chain.
0-24	Low (green)	Far away, low criticality, or a non-destructive change type. Safe to proceed.

How the Score is Calculated (review)

impactScore = round((depthScore × 0.30) + (criticalityScore × 0.40) + (changeTypeSeverity × 0.30))

Depth (30%) — how many hops away. Depth 1 = 100, Depth 5 = 60, Depth 10 = 10.
Criticality (40%) — how important the resource type is. Database = 100, Lambda = 75, S3 = 50, Log group = 25.
Change severity (30%) — how dangerous the action is. Remove = 100, Replace = 80, Modify = 50, Add = 30.

Criticality is weighted highest because what's affected matters more than how far away it is. Deleting a test log group one hop away is less dangerous than modifying something three hops from a production database.

Dependency Chains — the Breadcrumb Trail

Every scored resource includes a dependencyChain: the ordered path showing exactly how risk flows from your change to that resource.

Example: sg-abc123 → ec2-instance-1 → rds-prod

Read left to right: your changed resource → intermediate resources → the thing at risk.

Longer chains mean lower depth scores (the resource is further away).
But a long chain ending at a Critical-class resource (like a database) can still score high because criticality carries 40% of the weight.
Short chains ending at low-criticality resources score low even though they're close.

In the frontend graph view, the dependency chain is the highlighted path when you click a node. In the PR comment, it appears in the detail expansion for each resource.

AI Confidence Levels

When using the AI gate, the model returns a confidence alongside its recommendation:

High: clear signal. The graph strongly supports the recommendation. Trust it.
Medium: mixed signals. Some risk factors present, some mitigating. Worth human review before overriding.
Low: AI isn't sure. Limited data, ambiguous patterns, or a very small graph. Don't gate on this alone — treat it as advisory.

When the AI says "don't deploy" but scores are below threshold:

This is the AI gate earning its keep. It's seeing a pattern that individual scores don't capture:

Fan-out risk: many resources all depending on one thing you're changing.
Single points of failure: a resource that's the only path between your change and critical infrastructure.
Cascading depth: the graph is deep and converges on something important at the far end.

Check the AI summary for the specific reasoning. It will explain what pattern it detected and why it recommends against deployment.

When the AI says "deploy" but you're nervous:

The AI can be wrong. If your gut says something's off:

Look at the dependency chain for the highest-scored resource. Does the path make sense?
Check whether the graph is missing resources (AWS Config relationships aren't always complete).
Use the interactive frontend to explore the full graph visually.
When in doubt, deploy to a non-production stage first.

Local Development and Testing

You don't have to go straight to CI/CD pipeline. The CLI has commands for generating, inspecting, and exploring results locally. The interactive frontend also gives you a visual way to understand your infrastructure's dependency landscape.

`blast-radius generate` — Create Input Files without Submitting

The generate command produces the same input file that analyze would create and submit, but stops there. No analysis is run, no API is called.

# CDK: synthesizes and creates a changeset, saves to disk
blast-radius generate --format cdk --stack MyStack --output changeset.json

# Terraform: runs terraform plan + show, saves the JSON
blast-radius generate --format terraform-plan --output plan.json

# CloudFormation: creates changeset from template, saves it
blast-radius generate --format cloudformation --stack MyStack --template cfn.json --output changeset.json

Why this is useful:

Verify your CI workflow produces valid input before enabling the gate
Inspect exactly what Blast Radius will see — review the changeset JSON to understand the resources and change types
Build a library of test inputs for different scenarios
Share with teammates: "here's what the analysis would run against"

`--save` flag — save AND submit

If you want to both inspect the input and run the analysis in one shot:

blast-radius analyze --format cdk --stack MyStack --save changeset.json --ai-gate

This saves the generated input to disk, then submits it. When a result comes back surprising ("why did my security group change score 82?"), you can open changeset.json and see exactly what was sent: which resources, which change types, which properties.

The Interactive Frontend

After deploying the backend, the CloudFront URL serves a React SPA where you can explore results visually.

Analysis list (/analyses): shows all past analyses sorted by date. Click any row to drill in.
Dependency graph: Cytoscape.js interactive graph. Your changed resources appear as solid blue nodes. Downstream dependencies fan out, colored by risk category (red/orange/yellow/green). Click any node for a detail panel: resource ID, type, score, risk category, and full dependency chain.
Filters: filter by risk category, resource type, or toggle direct changes on/off. Filters apply as intersection (resource must match all active filters).
Table view: sortable alternative to the graph. Sorted by impact score (highest first) by default. Paginated at 50 rows.
Export: download the full analysis as JSON for archiving or feeding into other tools.
AI Summary: rendered as formatted markdown below the graph (if Bedrock was enabled for the analysis).

The frontend is useful for exploring results visually after CI runs, understanding dependency patterns in your account before they cause problems, demoing Blast Radius to stakeholders, and investigating why the AI gate blocked a deployment.

Running against the demo examples

The repo includes examples/cdk-demo/ with a two-step demo that doesn't require your real production infrastructure:

01-baseline/: deploys a realistic infrastructure: VPC, ECS Fargate service, Aurora PostgreSQL cluster, ALB, Lambda function, S3 bucket.
02-risky-change/: modifies the security group (restricts from public to internal-only) and resizes the database instance.

# Deploy baseline
cd examples/cdk-demo/01-baseline
npm install && npx cdk deploy

# Run Blast Radius against the risky change
cd ../02-risky-change
npm install
BLAST_RADIUS_API_URL=<your-url> blast-radius analyze --format cdk --stack BlastRadiusDemoBaseline --ai-gate

This produces a real analysis showing 7 affected resources cascading from the security group and database changes, ECS service, Lambda, ingress/egress rules, scored and visualized.

Cost note: The demo creates real AWS resources (~$0.45/hr). Run cdk destroy when you're done. Don't do what I did and forget to run the destroy!

Other useful commands

# Check status of a running analysis
blast-radius status --analysis-id abc-123

# Fetch completed results
blast-radius export --analysis-id abc-123 --format json

What's Next?

You now have a working deployment gate. Every infrastructure PR gets analyzed for downstream risk before it can merge. Whether you're using the GitHub Action, the CLI in GitLab, or exploring results in the frontend, the workflow is the same: generate, analyze, gate, decide.

Next in this series, we go under the hood:

Article 3: Serverless IaC Risk Analysis — The Architecture Behind Blast Radius: How the pipeline is designed. Why Step Functions. How the canonical format abstraction makes multi-IaC support possible without touching the analysis engine.
Article 4: 349 Tests, Zero Mocks — Building Blast Radius in TypeScript: Engineering decisions, property-based testing with fast-check, dependency injection over module mocking, and the Lambda runtime gotchas that wasted a day.

These articles are coming in the next few weeks. I'll update this post with links as each one publishes.

Stop Taking Down Production Systems. Use "Blast Radius" To Help You.

Scott Burgholzer — Sun, 28 Jun 2026 19:59:06 +0000

Series: Introducing Blast Radius — See What Breaks Before You Deploy

“It Was Just a Security Group Change”

A developer modifies an ingress rule on a security group. The pull request looks clean, and cdk diff shows that only one resource is changing. The PR is approved, merged, and deployed.

Then the alerts start flowing in. Ten EC2 instances lose connectivity. Three RDS databases become unreachable. The production app goes down.

The change was correct in isolation. The problem was everything downstream of that change, and nothing in the IaC diff revealed it.

This isn’t a fictional horror story. It is a category of incident that happens because IaC tools are blind to runtime dependency relationships.

Terraform Plan Shows Your Change — Not Its Consequences.

IaC tools tell us what we are changing, but they don’t tell us what else is affected and will break.

terraform plan shows 1 resource modified. In reality, 28 downstream resources are affected.

cdk diff shows a property update. In reality, there is a cascading dependency chain through Config relationships.

CloudFormation change sets list actions on declared resources. Undeclared runtime dependencies are invisible.

Manual review doesn’t scale. You’d need to trace relationships across AWS Config, Resource Explorer, and tribal knowledge, and still probably miss something. The other option is to deploy to a dev environment and see what breaks.

The information exists in AWS. Config tracks relationships. Resource Explorer indexes resources. It’s just not connected to your deployment workflow.

See the Blast Radius Before You Deploy.

Blast Radius connects the data AWS already has to your deployment workflow. It discovers downstream dependencies from your infrastructure change, scores each one for risk, and optionally asks AI whether you should deploy.

It works with CDK, CloudFormation, and Terraform out of the box. You don’t need to change your IaC tool.

The dependency graph makes the cascade visible: your changed resource highlighted in blue, everything downstream fanning out and color-coded by risk score. Click any node for details. There’s a table view too.

Frontend Dependency Graph Example

The score isn’t a mystery: (depth × 0.30) + (criticality × 0.40) + (change severity × 0.30). It is explainable, auditable, and tunable.

The output lands in your PR as a comment (GitHub Action), in your terminal (CLI), or in an interactive graph (frontend).

From IaC Diff to Risk Score in 30 Seconds

You push a PR with an infrastructure change.

Blast Radius auto-generates the changeset (runs cdk synth, terraform plan, or reads your CloudFormation change set).

An adapter normalizes the changeset into a single canonical format. CDK, CloudFormation, and Terraform all describe the same change in different ways. The canonical format unifies them.

AWS Config queries discover real, live dependency relationships. Not what’s in the IaC, what’s actually wired together in your account.

Each affected resource is scored for how far away it is (depth), how important it is (criticality), and how dangerous the change type is (severity).

Results: a risk summary, scored resources, dependency graph, and optional AI-generated deployment recommendation.

Flow Diagram of how Blast Radius Works

Total wall time: 10–30 seconds, depending on graph size.

Two Gates: Numbers and Judgment

Threshold gate (--threshold 75): If any downstream resource scores above your number, the pipeline fails. Deterministic. No AI required. Good for teams that want a hard cutoff.

AI gate (--ai-gate): An AI model analyzes the full dependency graph and returns a deploy/no-deploy recommendation with confidence. Catches systemic risks that individually score below the threshold but are dangerous collectively.

You modify a security group attached to a shared RDS Proxy. Eight Lambda functions score 62. Two ECS services score 68. All below your threshold of 75. But every one of them routes database traffic through that proxy. Take it down and you’ve killed every service that touches your database. The AI sees the shared dependency. The threshold just sees ten numbers under 75.

You can use either of them or both together. If using both, it fails if EITHER triggers. This gives you defense in depth.

Exit codes are CI-friendly: 0 = pass, 1 = fail, 2 = error

Add It to Your Pipeline in Five Minutes

First, deploy the backend to your own AWS account. One stack, one command:

git clone https://github.com/sburgholzer/BlastRadius.git && cd BlastRadius
npm install && npm run build && cd packages/infra && cdk deploy

One requirement before you deploy: AWS Config and Resource Explorer must be enabled in your account. That’s where Blast Radius reads live dependency relationships.

Then add it to your pipeline. The fastest path is the GitHub Action — it auto-comments on your PR with the full analysis:

- uses: sburgholzer/BlastRadius@v0.1.0
  with:
    format: terraform-plan
    input: plan.json
    ai-gate: true
    api-url: ${{ secrets.BLAST_RADIUS_URL }}

For CDK, you’ll need to generate a CloudFormation changeset first, then pass it to the action. The full setup is in Article 2.

Or skip the GitHub Action entirely and run it from the CLI in any CI system:

curl -sL https://github.com/sburgholzer/BlastRadius/releases/latest/download/blast-radius.js -o blast-radius.js
node blast-radius.js analyze --format cdk --stack MyStack --ai-gate

Blast Radius is open source. You can find the repo here.

Closing Thoughts

Infrastructure changes will always carry risk. The goal isn’t to eliminate that risk; it’s to see it clearly before you deploy. Blast Radius gives you that visibility in the time it takes to review a PR.

Next In This Series

Article 2: Stop Deploying Blind: Add a Blast Radius Gate to Your CI/CD Pipeline: Step-by-step setup for GitHub Actions, GitLab, and Jenkins. Choosing between threshold and AI gates, tuning your cutoff, and reading the output like a pro.
Article 3: Serverless IaC Risk Analysis: The Architecture Behind Blast Radius: How the pipeline is designed. Why Step Functions. How the canonical format abstraction makes multi-IaC support possible without touching the analysis engine.
Article 4: 349 Tests, Zero Mocks: Building Blast Radius in TypeScript: Engineering decisions, property-based testing with fast-check, dependency injection over module mocking, and the Lambda runtime gotchas that wasted a day.

These articles are coming in the next few weeks. I’ll update this post with links as each one publishes.

Title help from Aaron Hunter!

The InvalidCiphertextException Mystery: Decrypting Cognito's Encrypted OTP Codes

Scott Burgholzer — Thu, 01 Jan 2026 05:05:01 +0000

The Problem

You're building a custom email sender for Cognito because the default emails are pretty basic. In this case you want branded HTML emails for a One Time Password code that actually explain what the code is for and when it expires. Sounds straightforward, right?

Then you hit the encryption wall. Cognito encrypts those OTP codes for security (which is great), but when you try to decrypt them in your Lambda function using standard KMS operations, you get this error:

InvalidCiphertextException: An error occurred (InvalidCiphertextException) when calling the Decrypt operation:

That's it. No helpful details, no explanation of what went wrong. The error message makes it seem like there's something fundamentally wrong with the ciphertext, but even after triple-checking your KMS permissions, it still doesn't work. Here's why, and more importantly, how to fix it.

TL;DR - The Solution

Cognito doesn't use regular KMS encryption. It uses the AWS Encryption SDK, which creates a completely different data structure. You need to use the same AWS Encryption SDK (v4 with Material Providers Library) to decrypt the codes. Jump to the working code if you just want the fix.

What Everyone Tries First, Including Myself (And Why It Fails)

When you think AWS encryption, you think KMS. So naturally, you try the standard approaches:

Attempt 1: Basic KMS Decryption

# This seems logical but doesn't work
kms_client = boto3.client('kms')
decrypt_response = kms_client.decrypt(CiphertextBlob=encrypted_blob)

Result: InvalidCiphertextException

Attempt 2: Adding Encryption Context

Maybe it needs the user pool ID as context?

# Still doesn't work
decrypt_response = kms_client.decrypt(
    CiphertextBlob=encrypted_blob,
    EncryptionContext={"userpool-id": event.get('userPoolId', '')}
)

Result: Same error

Attempt 3: AWS-Prefixed Context

Perhaps it needs the AWS service prefix?

# Nope, still fails
decrypt_response = kms_client.decrypt(
    CiphertextBlob=encrypted_blob,
    EncryptionContext={"aws:cognito:userpool-id": event.get('userPoolId', '')}
)

Result: Still the same error

At this point, you start questioning everything. Your KMS permissions look right, the key exists, but nothing works.

The Real Issue: It's Not Actually KMS Ciphertext

Here's the key insight that changes everything: Cognito doesn't use direct KMS encryption. Instead, it uses something called the AWS Encryption SDK, which creates a completely different type of encrypted data.

What's the Difference?

Think of it this way:

Regular KMS encryption = A locked box
AWS Encryption SDK = A locked box inside a shipping container with labels, tracking info, and handling instructions

When you try to use KMS to "unlock" the shipping container, KMS says "I don't know what this is - this isn't a box I locked!"

The Technical Details

When Cognito encrypts an OTP code, here's what actually happens:

Cognito uses the AWS Encryption SDK (not direct KMS)
The SDK creates an "envelope" containing:
- Algorithm information
- An encrypted data key (this part uses KMS)
- The actual encrypted OTP code
- Integrity checks and metadata
This entire envelope gets passed to your Lambda function

The encrypted_blob you receive isn't simple KMS ciphertext - it's this complex envelope structure. That's why KMS can't decrypt it directly.

Why the Error Message is Confusing

The InvalidCiphertextException error just says:

An error occurred (InvalidCiphertextException) when calling the Decrypt operation:

That's it. No details, no explanation. This generic message makes you think the ciphertext is corrupted or you have permission issues, but the real problem is that KMS is saying "I can't even parse this data structure."

It's like trying to open a ZIP file with a text editor - the format is just wrong, but the error message doesn't tell you that.

Solution: AWS Encryption SDK Implementation

Once you understand the problem, the solution becomes clear. You need to use the same AWS Encryption SDK that Cognito uses to create the encrypted data.

What You Need

AWS Encryption SDK v4 - The encryption library
Material Providers Library (MPL) - Required for v4
Proper KMS permissions - Your Lambda still needs to access the KMS key
The right Python packages - Install them as a Lambda layer

The Working Code

Here's the code that actually works:

import os
import boto3
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput

def decrypt_cognito_code(encrypted_blob):
    # Set up the encryption client
    client = aws_encryption_sdk.EncryptionSDKClient(
        commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
    )

    # Create the material providers
    mat_prov = AwsCryptographicMaterialProviders(
        config=MaterialProvidersConfig()
    )

    # Set up the KMS keyring
    kms_key_id = os.environ.get('KMS_KEY_ID')
    keyring_input = CreateAwsKmsKeyringInput(
        kms_key_id=kms_key_id,
        kms_client=boto3.client('kms')
    )

    kms_keyring = mat_prov.create_aws_kms_keyring(input=keyring_input)

    # Now this actually works!
    plaintext_bytes, decryption_header = client.decrypt(
        source=encrypted_blob,
        keyring=kms_keyring
    )

    # Convert to string and return
    return plaintext_bytes.decode('utf-8')

Setting It Up

1. Install the packages:
Create a Lambda layer with these dependencies:

pip install "aws-encryption-sdk[MPL]">=4.0.0

2. Set your environment variable:

KMS_KEY_ID=your-kms-key-id-here

3. Update your IAM role:
Your Lambda execution role needs kms:Decrypt permission for your KMS key:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "arn:aws:kms:region:account:key/your-key-id"
        }
    ]
}

Why This Matters Beyond Cognito

This isn't just a Cognito quirk. Other AWS services also use the AWS Encryption SDK instead of direct KMS encryption:

Systems Manager Parameter Store (SecureString parameters)
Some S3 client-side encryption scenarios
Custom applications that need to encrypt large amounts of data

The pattern is becoming more common because the AWS Encryption SDK offers benefits that direct KMS doesn't:

No size limits (KMS is limited to 4KB)
Better performance for large data
Additional security features like key commitment

The Key Takeaway

When you see an AWS service that says it "uses KMS encryption," don't assume it's using direct KMS calls. It might be using the AWS Encryption SDK under the hood, which changes everything about how you decrypt the data.

Troubleshooting Tips

If you're still getting errors:

Check your Lambda layer - Make sure you have the right packages installed
Verify your KMS key ID - It should be the same one configured in your Cognito user pool
Test your IAM permissions - Try a simple KMS decrypt operation to verify access
Check the commitment policy - Use REQUIRE_ENCRYPT_ALLOW_DECRYPT for compatibility

Common mistakes:

Using the wrong version of the AWS Encryption SDK (you need v4)
Forgetting to install the Material Providers Library
Using the wrong KMS key (it must match what Cognito is configured to use)

Error message reference:

InvalidCiphertextException with no details = You're trying to decrypt AWS Encryption SDK data with direct KMS
IncorrectKeyException = You're using the wrong KMS key for real KMS ciphertext
AccessDeniedException = Actual permissions problem

Final Thoughts

This problem can stump a lot of developers because the error message is so generic and unhelpful. When you see InvalidCiphertextException with no details, it's usually a sign that you're trying to decrypt AWS Encryption SDK data with direct KMS calls.

Once you understand that Cognito uses the AWS Encryption SDK instead of direct KMS, everything clicks into place. The extra complexity is worth it - you get better security, no size limits, and future-proof encryption. Plus, now you know how to handle this pattern when you encounter it in other AWS services.

References

Understanding Amazon CloudFront's New Flat-Rate Pricing

Scott Burgholzer — Thu, 27 Nov 2025 00:45:35 +0000

On November 18th, AWS introduced new flat‑rate pricing plans for Amazon CloudFront designed to make content delivery and security costs more predictable for teams of all sizes. These plans sit alongside the existing pay‑as‑you‑go model and bundle multiple services into a single monthly price per distribution.

Why Flat-Rate Pricing Matters

Traditionally, CloudFront has used pay‑as‑you‑go pricing, which is great for starting at $0, scaling with actual usage, and only paying for what you consume. The tradeoff is that estimating costs can be difficult, especially when you also depend on AWS WAF, DDoS protection, Route 53, CloudWatch Logs, and S3 for a single application. You end up stitching together multiple pricing pages and trying to map them to your traffic patterns just to get a reasonable forecast of your monthly bill.

The new flat‑rate plans aim to simplify this. Instead of tracking every request, rule, and log line, you choose a plan tier per distribution and pay a fixed monthly fee that includes a defined bundle of features and usage allowances.

What's Included in the New Plans

Each flat‑rate plan bundles the following into one monthly price per CloudFront distribution:

Amazon CloudFront CDN
AWS WAF and DDoS protection
Bot management and analytics
Amazon Route 53 DNS
Amazon CloudWatch Logs ingestion
Serverless edge compute (via CloudFront Functions)
Monthly Amazon S3 storage credits

Because everything is packaged together, you get a predictable bill for that distribution with no overage charges. There are no surprises at the end of the month.

A few structural details to keep in mind:

Plans are per distribution. If you put two distributions on the Business plan at $200 each, you will pay $400 per month for those two.
You can upgrade at any time, but downgrades/cancellations or a move back to pay‑as‑you‑go only take effect at the start of the next billing cycle.
There is a limit of three free plans per AWS account and a limit of 100 total plans per account, which matters if you run many environments or tenants.

Handling Attacks and Traffic Spikes

One of the more reassuring aspects of these plans is how they treat malicious traffic. DDoS attacks do not count against your usage allowance, and traffic blocked by AWS WAF or bot protections also does not consume your plan quota. That means an attack should not cause you to exceed your allowance.

You will receive email notifications when you hit 50%, 80%, and 100% of your usage allowance for the month. If you exceed the allowance, AWS will not tack on overage fees, but you may experience reduced performance. That performance reduction is at AWS's discretion and depends on overall network conditions and other factors, so consistently bumping into your limits is a good signal that it is time to move to a higher‑tier plan.

Edge Compute: CloudFront Functions vs. Lambda@Edge

All of the flat‑rate plans include CloudFront Functions, which are ideal for lightweight JavaScript logic at the edge such as header manipulation, redirects, and simple request or response normalization. For many use cases, this will cover the bulk of what you might previously have used Lambda@Edge for.

However, Lambda@Edge is not supported on the flat‑rate plans. If your distribution relies on Lambda@Edge, such as more complex request processing, integrations, or heavy transformations, you must keep that distribution on the pay‑as‑you‑go pricing model. This is an important constraint to verify before flipping an existing production distribution over to a flat‑rate plan.

Pay-As-You-Go Is Still Available

All of this arrives in addition to, not instead of, the existing pay‑as‑you‑go model. The traditional CloudFront pricing structure remains available with its free tier, which is still a solid option for:

Very low‑traffic or experimental workloads
Architectures that depend on Lambda@Edge or other features not supported in flat‑rate plans
Teams that prefer pure usage‑based billing and are comfortable modeling and monitoring their costs

In practice, many organizations will likely end up with a mix: flat‑rate plans for high‑volume, business‑critical sites where predictability matters, and pay‑as‑you‑go for specialized or experimental distributions.

What is AWS Device Farm and Using it to Test a Simple Android App

Scott Burgholzer — Sat, 23 Nov 2024 04:37:15 +0000

Introduction

As I have been busy with my classes for my doctorate and work, I haven’t had much time to write articles like I had hoped. I was hoping to have a project done that I could discuss how I created a Web App using multiple AWS services for others to learn how they all can interact. As that project is still ongoing, I decided to focus on something else.

I choose AWS Device Farm because eventually I would need to test that web app on mobile devices and on desktop browsers. Device Farm allows us to use physical devices to test our apps. Not only can we test web apps, we can also test Android and iOS apps on physical devices. There is a lot to learn for Device Farm, so I started very basic with using it, and hence this article was born. I hope, while this article just uses a simple app and the defaults, it can expose more people to this AWS service and see if it’ll work in their use cases.

View this article as a “I’ve never heard or seen AWS Device Farm, so I want to start from the basics and work my way up” as that is exactly what I’m doing with you!

What is AWS Device Farm?

AWS Device farm is a cloud-based testing platform that allows developers to test their mobile and web apps on physical devices instead of simulators. There are two main ways of using Device Farm: automated testing of apps and remote access of devices [1].

Automated app testing

AWS Device Farm allows developers the ability to upload their own tests or to use built-in and script-free compatibility. AWS Device Farm performs testing in parallel, tests on multiple devices begin in minutes. As these tests are completed, a report is generated that contains high-level results, low-level logs, pixel-to-pixel screenshots and performance data. Device Farm supports the testing of native and hybrid Android and iOS Apps. Some frameworks that work with Device Farm are PhoneGap, Titanium, Xamarin, Unity, and others. You also get remote access of Android and iOS apps for interactive testing.

Remote access interaction

This allows you to swipe, gesture and interact with a device through your web browser in real time. An example of where this is beneficial is a customer service rep can guide customers through the use or setup of their device. You have the ability to install apps on a device running in a remote access session and reproduce bugs or other issues. While the session is live, Device Farm will collect details about the actions that are completed on the device. Logs with those details and a video capture of the session are available at the end of the session [1].

Note about regions: Per the documentation, Device Farm is only available in the us-west-2 (Oregon) region [1].

Walk-through

I’m going to skip over the setting up section. If you wish to go through it in detail (signing up for an account, create or use an IAM user) you may read that here. Below is an example IAM policy [1] to allow full access to Device Farm. For this walk-through, this is fine, but if you are going to implement this service, you are going to want to restrict it as much as you can to the least privilege access.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "devicefarm:*"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

Device Farm Console

Step 1: Create a project

Go to Device Farm in the console
Expand the left hand navigation if necessary
Click on Projects underneath Mobile Device Testing
Click on Create mobile project
Enter a project name and assign any tags you wish the project to have
Click Create

Step 2: Create and start a run

You will need an app in order to start the run. I have created a very simple Android App on my GitHub. Go ahead and download that if you do not have your own Android or Apple App (note in order to get an .ipa file for iOS you will need to have an Apple Developer Account.
Stay on the Automated tests page and click on Create Run
Device Farm uses the app name as the default run name, feel free to choose your own name! Click Next
You’ll be taken to a configure page to setup your test framework. You have the ability to choose one of the testing frameworks provided or built-in test suites. Since we are not worrying about our own tests for this example, we can use the Built-In: Fuzz for our case (can keep all the defaults). When you start writing your own test packages, you can choose the corresponding testing framework and upload the file with your tests. This is not applicable in our example. Click Next
For our example, we will use the Top Devices Device pool. You do have the ability to create your own device pools, but for our simple app, Top Devices is just fine. Click Next
We are going to keep the next page as is. You can read more about the options in the Developer Guide, which you can find at the end of this article tagged [1]. Click Next
We will leave the execution timeout to the default value provided and will then click Confirm and start run. This can take a while, so wait patiently.

Run Results

Step 3: View the run’s results

— When the run is done, you will see the results of the runs. In my case 3 tests were ran and all passed.

— The unique problems would list any problems that were discovered. A video can be downloaded to view the recording of the test that had the problem. There are additional data provided that I won’t get into detail in this article.

— Screenshots will display any screenshots Device Farm took during the run.

Where to go from here?

The next thing I personally would suggest, and plan on doing, is to learn more about test packages. There are frameworks that work with both iOS and Android, and some that only work for only Android or only iOS. This is where you are able to specify your tests the way you want them instead of using just the built-in tests AWS provides. This gives you complete control over how you want the tests done and what you want tested. This is where the real power of AWS Device Farm comes into play.

The other thing to look into is the Desktop Browser Testing for any web apps. Personally for me, my project is going to start as just a web app, so Desktop Browser Testing is of personal importance. As always, you need to figure out your use cases and determine what your needs are.

There is so much more to learn about AWS Device Farm, and I will continue posting about it as I go through it and learn it myself. For now, happy developing and testing!

[1] AWS Device Farm Developer Guide

Launching a simple EC2 Instance with Apache Web Server — Part 1

Scott Burgholzer — Mon, 11 Mar 2024 02:06:15 +0000

Little backstory: I’ve had this in my drafts for a while, wanting to do it all as one article. I’ve decided that is not the best way of presenting this information. As a newer content creator, I’ve been playing with how I want my pages to look like, and have decided to go with how it looks right now.

Introduction

In this article, I will be doing what some call “click-ops” in AWS console as that is the easiest way to get started. If you want more challenges, I will also be posting on how to use AWS CLI (an article post on this will come at a later date, when completed, I will be updating this with a link to it!) to do the same thing. I will also show how to use a Cloud Development Kit (CDK). I will be using Python in my CDK examples. I will also use AWS CloudFormation. Finally, for an even more advanced challenge, I will be creating this process again using Terraform. If you are new, the console way will be the easiest, but I also want to introduce you to the CLI, CDK, CloudFormation and Terraform as these are advanced tools used!

Scope of this tutorial

In this multi-part tutorial, we are wanting to set up an EC2 instance, configure security group(s), create a key-pair SSH Key to remote into the instance, and install Apache Web Server.

Method 1: Using AWS Console (without using userdata)

There are actually two ways we can use the AWS console to create the EC2 instance, and install Apache and run it and create the test HTML file. This method will require us to use SSH to remote into our EC2 instance to preform some steps.

Step 1: When you are logged into the AWS Console, search for EC2 in the search bar.

Step 2: Click on Launch Instance

Step 3: Configure your instance and install Apache and test web page

Give the instance a name, I called mine “Web Server Test” * Keep the application and OS Images as is
Keep the instance type as t2.micro
Click on new key par and give it a name, then click on Create key pair. It’ll download a file, move it to a safe location so you don’t loose it!

Under Network settings we will be keeping the selection Create Security Group. Allow SSH traffic from should be checked, and you’ll also want to check the Allow HTTP traffic from the internet. Next to SSH there is a dropdown menu that you can say any IP can connect to the instance, a custom IP or range, or your IP only. For this example, I’m keeping it as anywhere

We will leave everything else as default
Click on Launch Instance

Click on the instance ID shown in the green success box

Click the checkbox next to the instance, then go to actions and click on Connect

You’ll see there are four options of connecting. The only two that will work with our instance, due to the way we set it up, is EC2 Instance Connect and SSH client. If on Mac or Linux you can use command line to SSH into the instance’s command line, on Windows it is easiest to use a tool such as Putty.

We will be using EC2 Instance connect in our case, so click on that tab, then click on connect
After waiting a few moments, you’ll see a command line terminal for our instance.

We now want to install Apache and start the service. Run the following commands in the command prompt.

sudo yum update -y # We are asking the packacge manager to install any updates
sudo yum install httpd -y # We are asking the package manager to install Apache
sudo systemctl enable httpd # We are telling the server to automatically start Apache upon start up
sudo systemctl start httpd # we are telling the server to start the Apache Server
sudo systemctl status httpd # we are telling the server to tell us the status of the Apache Server

We are going to create a simple HTML file, run the below command to open a new file using a command line text editor

sudo nano /var/www/html/index.html

Put the following code into the text editor

<!DOCTYPE html>
<html>
  <head>
    <title>Test Web Page</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
    <p>I love AWS</p>
  </body>
</html>

When you are done with the file, press ctl and x, it’ll prompt you if you want to save, type Y, press enter, then press enter again.
Go back to the EC2 Instances page, click on your instance, then click on open address under the Public IPv4 address, change the HTTPS to HTTP

If you see your test page, you were successful!

Step 4: Clean Up

Close all windows except for the Instances window.
Select it, then click on Instance state then click on Terminate instance so you don’t use up your free trial credits or get charged!

Congrats! You have just launched a simple EC2 Web server!

Launching a simple EC2 Instance with Apache Web Server — Part 1 (AWS Console)

Launching a simple EC2 Instance with Apache Web Server — Part 2 (AWS Console with Userdata) (Coming Soon)

Launching a simple EC2 Instance with Apache Web Server — Part 3 (AWS CLI with user data) (Coming Soon)

Launching a simple EC2 Instance with Apache Web Server — Part 4 (Terraform with user data) (Coming Soon)

DEV Community: Scott Burgholzer

Serverless IaC Risk Analysis: The Architecture Behind Blast Radius

Four Constraints That Shaped Everything

The Canonical Format — The One Decision That Matters Most

Why Step Functions Orchestrates the Pipeline

State preservation with resultPath

No zombie analyses

Dependency Discovery — Reading the Real Graph, Not the Code

The Risk Formula — Deliberately Simple

The AI Layer — Advisory, Structured, and Optional

Frontend and API — Where the Shapes Meet

Lessons Learned

Wrapping Up

Stop Deploying Blind: Add a Blast Radius Gate to Your CI/CD Pipeline

What We Are Building

Prerequisites — Deploy the Backend

GitHub Action — The Five-Minute Path

Terraform Workflow

CDK Workflow

CloudFormation Workflow

What the GitHub Action Does Under the Hood

CLI in Any CI System

GitLab CI example

Jenkins example

CircleCI example

Parsing the JSON output

Exit Codes

Choosing Your Gate Strategy

Threshold only (--threshold N)

AI gate only (--ai-gate)

Using Both Gates Together

Running Without AI Summary

Reading the Output

The PR Comment Anatomy

Risk Scores — What the Numbers Mean

How the Score is Calculated (review)

Dependency Chains — the Breadcrumb Trail

AI Confidence Levels

Local Development and Testing

blast-radius generate — Create Input Files without Submitting

--save flag — save AND submit

The Interactive Frontend

Running against the demo examples

Other useful commands

What's Next?

Stop Taking Down Production Systems. Use "Blast Radius" To Help You.

“It Was Just a Security Group Change”

Terraform Plan Shows Your Change — Not Its Consequences.

See the Blast Radius Before You Deploy.

From IaC Diff to Risk Score in 30 Seconds

Two Gates: Numbers and Judgment

Add It to Your Pipeline in Five Minutes

Closing Thoughts

Next In This Series

The InvalidCiphertextException Mystery: Decrypting Cognito's Encrypted OTP Codes

The Problem

TL;DR - The Solution

What Everyone Tries First, Including Myself (And Why It Fails)

Attempt 1: Basic KMS Decryption

Attempt 2: Adding Encryption Context

Attempt 3: AWS-Prefixed Context

The Real Issue: It's Not Actually KMS Ciphertext

What's the Difference?

The Technical Details

Why the Error Message is Confusing

Solution: AWS Encryption SDK Implementation

What You Need

The Working Code

Setting It Up

Why This Matters Beyond Cognito

The Key Takeaway

Troubleshooting Tips

Final Thoughts

References

Understanding Amazon CloudFront's New Flat-Rate Pricing

Why Flat-Rate Pricing Matters

What's Included in the New Plans

Handling Attacks and Traffic Spikes

Edge Compute: CloudFront Functions vs. Lambda@Edge

Pay-As-You-Go Is Still Available

State preservation with `resultPath`

Threshold only (`--threshold N`)

AI gate only (`--ai-gate`)

`blast-radius generate` — Create Input Files without Submitting

`--save` flag — save AND submit