kiro on MD/Blog

HowTo give Kiro safe access to your AWS environment

Sat, 07 Mar 2026 10:20:55 +0000

Kiro is AWS’s agentic coding tool, available both as an IDE and a CLI. I’ve been using the CLI a lot lately, including for AWS work where I let it run aws commands on my behalf. It works well. But the moment you point it at a real AWS account from a laptop that already has prod credentials configured locally, there’s a gap nobody talks about.

You probably have a dozen profiles in ~/.aws/config. Setting up a dedicated IAM role for Kiro and pointing AWS_PROFILE at it doesn’t actually stop Kiro from running aws --profile prod-admin ec2 terminate-instances. The CLI reads the whole config file and that profile is right there. AWS_PROFILE only sets a default. It restricts nothing.

This post is CLI-first. The IDE works the same way for steps 1 and 2, and I’ll note the differences at the end. Production accounts only — if you’re playing in a sandbox, none of this matters much.

Step 1: A read-only IAM role for Kiro

Start from the AWS managed policy ReadOnlyAccess and strip what you don’t want the agent reading. At minimum, deny reads on Secrets Manager, SSM SecureString parameters, and anything storing customer data.

Use IAM Identity Center to access the role via SSO. No long-lived access keys. Credentials are short-lived, they expire on their own, and CloudTrail records the actual user who assumed the role.

A permission boundary on top of this role is a good idea, but out of scope for this post. The role’s permissions policy is your ceiling for now.

Step 2: Isolate Kiro’s AWS config from your shell’s

This is the part that matters.

The AWS CLI and SDK read ~/.aws/config and ~/.aws/credentials by default. Both file locations can be overridden with environment variables:

export AWS_CONFIG_FILE=~/.aws/kiro/config
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/kiro/credentials

When these are set, the SDK ignores the default files entirely. Profiles that aren’t in the file you specified simply do not exist as far as aws is concerned. This is the only mechanism that actually prevents Kiro from seeing your other profiles. Filtering file reads at the agent level (which we’ll add in step 3) is not enough on its own, because the AWS SDK reads ~/.aws/config directly without going through the agent’s fs_read tool.

Create the isolated config. Put every Kiro profile you’ll need in here. Start with read-only and add a write role for the dev account. Add a prod read-only role too if you want Kiro to be able to look at prod without being able to change it:

# ~/.aws/kiro/config
[profile kiro-readonly]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = KiroReadOnly
region = us-east-1

[profile kiro-dev-write]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = KiroDevWrite
region = us-east-1

[profile kiro-prod-readonly]
sso_session = my-sso
sso_account_id = 999999999999
sso_role_name = KiroReadOnly
region = us-east-1

[sso-session my-sso]
sso_start_url = https://my-org.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

Touch an empty credentials file alongside it so the SDK doesn’t fall back to anything else:

touch ~/.aws/kiro/credentials
chmod 600 ~/.aws/kiro/credentials

Now you need to make sure Kiro is launched with these env vars set, plus a default profile. Kiro doesn’t have a way to set env vars for its shell tool yet (kirodotdev/Kiro#40), so the vars have to be set in the parent process. The cleanest way I’ve found is a shell alias in ~/.zshrc:

alias kiro-aws='AWS_CONFIG_FILE=~/.aws/kiro/config \
  AWS_SHARED_CREDENTIALS_FILE=~/.aws/kiro/credentials \
  AWS_PROFILE=kiro-readonly \
  kiro-cli chat --agent aws-readonly'

Always launch Kiro for AWS work with kiro-aws instead of kiro-cli directly. From inside the session, ask it to run aws configure list-profiles. You should see only the kiro-* profiles. If prod-admin shows up, the isolation didn’t take.

This step alone takes Kiro from “could touch anything you have credentials for” to “physically cannot see your other accounts”.

Step 3: A custom agent and a steering document

Kiro CLI lets you define custom agents in ~/.kiro/agents/<n>.json with their own tool settings. The CLI has a dedicated use_aws tool that calls AWS APIs directly, separate from the general shell tool. Define a custom agent for AWS work:

{
  "name": "aws-readonly",
  "description": "AWS infrastructure assistant. Default read-only access via kiro-* profiles. Write operations require explicit user confirmation and a profile switch. Never attempt to use credentials outside the isolated AWS config.",
  "tools": [
    "read",
    "shell",
    "use_aws",
    "thinking",
    "grep",
    "glob",
    "delegate"
  ],
  "toolsSettings": {
    "shell": {
      "autoAllowReadonly": true
    }
  },
  "resources": [],
  "hooks": {},
  "includeMcpJson": true,
  "model": null
}

A few things going on here. The description field doubles as a system-level hint, so I put the key constraints right in there. I dropped write from the tools list — this agent is for AWS investigation, not editing your codebase. If you need file edits in the same session, add it back. delegate is included so Kiro can spin up sub-tasks for longer investigations (e.g., “check all Lambda functions in this account for public URLs”). The shell tool with autoAllowReadonly lets read-only shell commands run without prompting every time.

The isolated config from step 2 is doing the heavy lifting regardless. Since it only contains kiro-* profiles, any aws --profile something-else would just fail with “profile not found.” The whole point of isolating the config is so we don’t have to filter every shell command for safety.

The steering document lives at ~/.kiro/steering/AGENTS.md. This is where you give the agent enough context to make good decisions on its own, not just a list of don’ts:

# AWS Access Rules for Kiro

## Context

This environment uses isolated AWS credentials. The only profiles available
are in `~/.aws/kiro/config`, set via `AWS_CONFIG_FILE`. The standard
`~/.aws/config` is not visible. Do not assume other profiles exist.

## Available profiles

| Profile                | Account     | Access level | Use case                          |
|------------------------|-------------|--------------|-----------------------------------|
| `kiro-readonly`        | dev         | read-only    | Default. Inspecting resources.    |
| `kiro-dev-write`       | dev         | read-write   | Making changes in dev.            |
| `kiro-prod-readonly`   | production  | read-only    | Investigating prod issues.        |

`kiro-readonly` is the default (set via `AWS_PROFILE`). You do not need to
pass `--profile` for it.

## Rules

### Read operations
- `describe`, `get`, `list`, and similar read calls can run without asking.
- If you need to look at prod, use `--profile kiro-prod-readonly` and tell
  the user you're switching to the prod account before running the command.

### Write operations
- Any mutating call (`create`, `update`, `delete`, `put`, `modify`,
  `terminate`, `stop`, `start`, `reboot`, `invoke`) requires explicit
  user confirmation before execution.
- Before asking for confirmation, state: what you intend to do, which
  resources will be affected (ARN or name), and which profile you'll use.
- Only use profiles ending in `-write` for mutations. Never attempt a write
  call with a read-only profile.

### Credential boundaries
- If a call returns `AccessDenied` or `UnauthorizedAccess`, stop and ask
  the user. Do not:
  - Try a different profile hoping it has more permissions
  - Look for credentials in the filesystem
  - Suggest the user re-authenticate or assume a different role
  - Attempt to modify IAM policies to grant yourself access
- The permissions you have are intentional. Treat access errors as a signal
  to check with the user, not a problem to solve.

### General behavior
- When running multiple AWS commands in sequence, prefer combining related
  reads into a single investigation before presenting findings.
- If a task requires both read and write operations, do all the reads first
  with the read-only profile, present your plan, then switch to the write
  profile only after the user confirms.
- Always include `--output json` for programmatic parsing. Use `--output
  table` only when the user asks for a summary view.

The “credential boundaries” section is what prevents the drift behavior. Without it, when Kiro hits an AccessDenied it will try to find another way around it. The agent is helpful to a fault.

Step 4: Verify activity in CloudTrail

Every API call the agent makes shows up in CloudTrail, tied to the SSO user who assumed the role. The role session name looks something like KiroReadOnly/your_user or KiroDevWrite/your_user, so you can tell at a glance which role was used and by whom.

You can filter for this in the CloudTrail console under Event history by searching for the username KiroReadOnly (or whatever your role is named). No extra setup required — standard CloudTrail covers this.

If you have CloudTrail Lake set up, a saved query makes this even faster:

SELECT eventTime, eventName, requestParameters
FROM <your_event_data_store>
WHERE userIdentity.sessionContext.sessionIssuer.userName LIKE 'Kiro%'
  AND eventTime > current_timestamp - interval '24' hour
ORDER BY eventTime DESC

Either way, when something looks off in the account, you want CloudTrail to answer “what did the agent do” without having to ask the agent itself.

Working with write access

When you actually need Kiro to make changes, just tell it to use the write profile:

Use --profile kiro-dev-write to update the IAM policy attached to the lambda role.

The steering doc kicks in. Kiro asks for confirmation, explains what it’s about to do, and only then runs the command. The IAM role enforces what kiro-dev-write can actually touch, so even if the agent misreads your prompt the blast radius is bounded by the role’s permissions.

For prod writes, the same pattern. Make a KiroProdWrite IAM role with very narrow permissions, add a kiro-prod-write profile to the isolated config, and ask Kiro to use it explicitly when you need it. Roles are cheap. Blast radius is not.

A note on the IDE

The Kiro IDE doesn’t have a use_aws tool. All AWS commands go through the shell tool, which means the config isolation from step 2 and the steering document are your primary guardrails. Steps 1 and 2 apply identically: create the role, isolate the config, then launch the IDE from a terminal where the env vars are already exported so the IDE’s agent inherits them. Step 3’s custom agent JSON is CLI-only, but the steering doc at ~/.kiro/steering/AGENTS.md is read by both.

That’s it

The IAM role gets all the airtime, but the config isolation in step 2 is what actually keeps Kiro from drifting into the wrong account when you’re moving fast.

HowTo use Kiro hooks to enforce IaC standards

Sun, 12 Oct 2025 10:20:55 +0000

Kiro hooks are actions that trigger at specific points in the agent’s lifecycle: before or after a tool call, when a file is saved, when the agent stops, or when you manually fire them. A hook can either run a shell command or send a prompt back to the agent. They’re how you get the agent to actually follow your team’s rules, not just write code that compiles.

When Kiro writes Terraform, the default loop is: agent writes the .tf, you eyeball it, you push, CI complains, you go back to the agent. Hooks shorten that loop by running validators during the agent’s own turn. Bad code never makes it to the PR.

This post shows how to wire up four checks for Terraform work and back them with a steering document. The setup assumes apply happens in CI (Atlantis or similar). Hooks are about the local feedback loop, not gating production.

The four checks:

terraform validate — catches invalid HCL and schema errors
terraform fmt — small formatting issues, auto-fix
tflint — bigger linter issues (provider-specific best practices, deprecations)
trivy — security misconfigurations (which absorbed tfsec)

Step 1: Where things live

Kiro hooks are .kiro.hook files that live in .kiro/hooks/ inside your workspace (or ~/.kiro/hooks/ for user-level hooks that apply everywhere). Each hook is its own file with a when/then structure — what event triggers it, and what action to take.

There are two action types: runCommand executes a shell command, and askAgent sends a prompt back to the agent so it can act on the result. Some checks work better as agent prompts than shell scripts — more on that below.

Steering documents go in .kiro/steering/. We’ll create one of those too.

Here’s what we’re building:

.kiro/
├── hooks/
│   ├── terraform-fmt-validate.kiro.hook
│   ├── terraform-lint-scan.kiro.hook
│   ├── terraform-lint-scan.sh
│   └── block-terraform-apply.kiro.hook
└── steering/
    └── terraform.md

Step 2: Auto-format and validate on save

The first hook fires whenever you save a .tf file. It uses askAgent to tell the agent to run terraform fmt and terraform validate and surface any errors.

.kiro/hooks/terraform-fmt-validate.kiro.hook:

{
  "enabled": true,
  "name": "Validate",
  "description": "Runs terraform fmt to format and terraform validate to check syntax whenever a .tf file is saved.",
  "version": "1",
  "when": {
    "type": "fileEdited",
    "patterns": ["**/*.tf"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "A .tf file was saved. Run 'terraform fmt' on the saved file, then run 'terraform validate' in its parent directory. Surface any errors."
  }
}

Why askAgent and not runCommand? A shell script would just print errors. I like using askAgent here because the agent can read the output and fix issues in the same turn, which is the whole point. The enabled flag also lets you toggle hooks on and off without deleting them.

Step 3: Lint and security scan at end of turn

Running tflint and trivy after every single file save is overkill — they’re slower and the agent often writes multiple files in a turn. Better to run them once when the agent finishes using the agentStop event, which fires at the end of every agent response.

This hook uses askAgent to check whether any .tf files were touched, and if so, calls a shell script that runs both linters. The script lives alongside the hook files.

.kiro/hooks/terraform-lint-scan.sh:

#!/usr/bin/env bash
set -euo pipefail

# Find all directories containing .tf files
tf_dirs=$(find . -name '*.tf' -not -path '*/.terraform/*' -exec dirname {} \; | sort -u)

if [ -z "$tf_dirs" ]; then
  echo "No .tf files found, skipping."
  exit 0
fi

for dir in $tf_dirs; do
  echo "==> Running tflint in $dir"
  tflint --chdir="$dir"

  echo "==> Running trivy config scan on $dir"
  trivy config "$dir"
done

And the hook definition at .kiro/hooks/terraform-lint-scan.kiro.hook:

{
  "enabled": true,
  "name": "Terraform Lint & Scan",
  "description": "Runs tflint and trivy config scan on all directories containing .tf files once the agent finishes its turn.",
  "version": "1",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "askAgent",
    "prompt": "Check if any .tf files were created or modified during this session. If yes, run: bash .kiro/hooks/terraform-lint-scan.sh and surface the findings. If no .tf files were touched, do nothing and skip silently."
  }
}

If either linter finds something, the agent surfaces the findings and can fix them in the same turn.

Very handy.

I tested this with tflint v0.55+ and trivy v0.58+. Both have to be installed locally. On macOS: brew install tflint trivy.

Step 4: Discourage local apply

Local apply skips CI, skips review, skips state locking conventions. This hook is advisory, not a hard block — see the note at the end — but it catches the common case.

It uses preToolUse on shell commands with an askAgent prompt. The agent checks the command before it runs and refuses if it’s an apply or destroy.

.kiro/hooks/block-terraform-apply.kiro.hook:

{
  "enabled": true,
  "name": "Block Terraform Apply",
  "description": "Prevents terraform apply and terraform destroy from being run locally. Push the PR and let CI handle it.",
  "version": "1",
  "when": {
    "type": "preToolUse",
    "toolTypes": ["shell"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Check if the command being executed contains 'terraform apply' or 'terraform destroy'. If it does, STOP and do NOT run the command. Instead, tell the user: 'terraform apply/destroy is blocked locally. Push the PR and let CI handle it.' If the command does not contain terraform apply or destroy, proceed normally."
  }
}

terraform plan still works, so the agent can preview changes. Hopefully Kiro will add a proper denyCommand action at some point so we don’t have to rely on the agent being well-behaved for this.

Step 5: A steering document with your team’s IaC standards

Hooks catch mechanical errors. The steering document is where you encode the things linters can’t catch — your team’s conventions, naming patterns, what modules to use. Put it at .kiro/steering/terraform.md in your workspace.

A starting point for what to put in there. Adjust to your team’s actual standards:

# Terraform standards

## File and resource conventions
- One resource per file when possible. Group tightly-related resources
  (e.g., a Lambda function and its IAM role) in the same file.
- Resource names use snake_case and start with a noun describing what
  the resource is, not what it does. `vpc_main`, not `main_vpc`.
- All variables have `type` and `description`. Sensitive variables have
  `sensitive = true`.
- Provider versions are pinned with `~>` in `versions.tf`. Never `>=`.

## Modules
- Use the company `terraform-aws-eks` module for EKS, do not declare
  raw `aws_eks_cluster` resources.
- Use the company `terraform-aws-s3-secure` module for any S3 bucket.
- Modules sourced from the internal registry, never from `github.com`
  directly.

## Required tags
- Every resource that supports tags must have: `Owner`, `Environment`,
  `ManagedBy = "terraform"`, `CostCenter`, `Repository`.
- Use the `default_tags` block in the provider when possible.

## Things to never do
- No public ACLs on S3 buckets (`acl = "public-read"` etc.).
- No `0.0.0.0/0` ingress on security groups except for resources
  explicitly tagged `Public = "true"`.
- No hardcoded AWS account IDs or ARNs. Use `data "aws_caller_identity"`
  and `data` sources for ARNs.
- No `aws_iam_policy` declared inline outside of approved modules.

## Workflow
- After modifying any .tf file, validate with `terraform validate`.
  If it fails, fix it before reporting back to the user.
- After making meaningful changes to a directory, run `tflint` and
  `trivy` on it and surface findings.
- Never run `terraform apply` or `terraform destroy` locally.
  Apply is handled in CI.

Without a steering doc the agent writes generic Terraform. With one it writes like someone who actually read your wiki.

A note on CI

Run terraform fmt, tflint, and trivy in CI as a backstop. Hooks can be bypassed: they can be disabled with the enabled flag, they only fire when changes go through Kiro’s tools or editor saves, and an agent following askAgent prompts is ultimately advisory — it’s an LLM, not a hard gate. CI is the boundary that actually has to hold.

The point of hooks isn’t to replace CI. It’s faster feedback. Catch the issue during the agent’s turn while it’s still in context, not 20 minutes later in PR review when you’ve moved on to something else.

That’s it.