An AI agent just read my AWS account and told me a bucket was open to the internet, SSH was exposed to 0.0.0.0/0, GuardDuty was off, and I was burning $3.65 a month on an Elastic IP attached to nothing.
It did all of that in about two minutes. And here is the part that counts: it physically could not have changed anything even if it tried.
That last sentence is the whole point of this build. Most "give the AI access to my cloud" ideas die on one fear: what if it deletes something, or a bad prompt tricks it into running a destructive command? We remove that fear at the permission layer, not with a polite instruction. The agent runs on a read-only IAM identity. Every write call it could imagine gets rejected by AWS before it happens.
This is a walkthrough of building that agent from scratch. It is one JSON file and one Markdown checklist. By the end you will have a working AWS auditor you can point at your own account, and you will understand every field that makes it work.
You use Kiro Crew or the Amazon Q Developer CLI. You know your way around AWS enough to have an account with a few things running. You have heard "AI agent" a hundred times and you want to see what one is built from, without a framework, without a vector database, without 400 lines of Python.
If you can edit a JSON file and write a checklist in Markdown, you can build this.
Table of contents What an agent is made of (the 6 pieces) The safety foundation: read-only IAM Writing the agent config The skill: your audit checklist Wiring the AWS tools with MCP Running it, and what it produced Making it yours Why build this when Prowler and Trusted Advisor exist? What the docs do not tell you What an agent is made of
Strip away the hype and an agent is one JSON file. The filename minus .json is the agent's name. The file describes a chat session: which model to use, what tools it can call, what it is allowed to do without asking you, what extra powers it plugs in, and what knowledge it carries.
| Piece | Field | Plain meaning | |-------|-------|---------------| | Identity | name, description | What it is called | | The brain | model | Which LLM answers | | Instructions | prompt | Its personality and rules | | What it can do | tools | The toolbox | | What runs without asking | allowedTools | Pre-signed permission slips | | Extra powers | mcpServers | Plug in tool servers | | Its knowledge | resources | Attach skills and files |
tools answers "what CAN this agent use?" If a tool is not listed, it does not exist for the agent.
allowedTools answers "what runs WITHOUT stopping to ask me?" A tool that is in tools but not in allowedTools still works, it just prompts you for approval each time it fires.
Toolbox versus permission slips. Keep that image and the rest is easy. The safety foundation: read-only IAM
Before any config, we build the guardrail. This step is not optional and it is the reason the whole thing is trustworthy.
We attach two AWS-managed policies to the identity the agent uses: arn:aws:iam::aws:policy/SecurityAudit arn:aws:iam::aws:policy/job-function/ViewOnlyAccess
SecurityAudit is the policy AWS designed for exactly this job: reading security-relevant configuration across services. ViewOnlyAccess fills the cost gaps, so the agent can see Elastic IPs, volumes, snapshots, and load balancers.
Underneath, both policies are Get, List, and Describe only. There is no Create, no Delete, no Put, no Modify anywhere in them.
Why go through this instead of just telling the model "please do not change anything"?
Because a prompt is a suggestion and IAM is a wall. If the model hallucinates a fix, IAM blocks it. If someone slips a "now delete that bucket" instruction into a file the agent reads, IAM blocks it. The blast radius is zero by construction. You are separating the act of detecting problems from the act of fixing them, which is a security best practice on its own.