> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Infrastructure Investigator

> Traces an AWS incident through CloudTrail, CloudWatch and IAM, and returns findings that cite the evidence behind each one.

Deploy this agent when an incident is in AWS and the answer is somewhere in the control plane —
a permission that changed, a resource that was modified, a dependency that went away. It reads AWS
directly and returns structured findings with the evidence attached. This page covers what it
reaches, what to connect first, and where it stops.

## What it does

You give it an incident description and the questions you want answered. It traces root causes
through configuration changes, access-control layers and resource dependencies, then returns
findings that cite the CloudTrail event, metric or policy behind each claim.

Findings come back structured, so an orchestrator can synthesize them with other specialists' work
rather than re-reading prose. Run it on its own and you get the same report in the run's output.

## What it reads

All of it read-only. The investigator has no mutating tool, in any deployment.

| Source        | What it uses it for                                                 |
| ------------- | ------------------------------------------------------------------- |
| CloudTrail    | Who changed what, and when — the change timeline behind an incident |
| CloudWatch    | Metrics and alarms around the incident window                       |
| IAM           | Policies, roles and trust relationships, when access is the suspect |
| Resource APIs | The dependencies between resources, and their current configuration |

## Before you deploy

| Requirement  | Detail                                                 | Where to set it up                                                       |
| ------------ | ------------------------------------------------------ | ------------------------------------------------------------------------ |
| Model access | The managed model gateway, or your own Claude API key  | [Credentials & secrets](/manage-your-agents/build/credentials-secrets)   |
| AWS access   | A connection, unless the pod supplies its own identity | [Built-in integrations](/manage-your-agents/build/built-in-integrations) |

The AWS connection offers two authentication modes, and which ones you see depends on where the
agent runs:

| Mode                   | How it works                                                                                                                                                         | Offered for   |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Cross-account IAM role | Komodor assumes a read-only role in your account per run, from a CloudFormation stack you deploy. No long-lived keys are stored. You supply the 12-digit account ID. | Komodor cloud |
| IRSA                   | The pod inherits AWS access from its Kubernetes ServiceAccount's IAM role, so there is no connection to bind. You supply the role ARN.                               | Self-hosted   |

<Note>
  The AWS connection is listed as optional because IRSA replaces it. If you deploy self-hosted with a
  ServiceAccount that already carries the role, the agent needs no connection at all.
</Note>

<Warning>
  A connection is validated as configuration, not as working AWS access. A well-formed role ARN with
  insufficient permissions deploys cleanly and fails on the first run, so read that run rather than
  treating a successful deploy as proof.
</Warning>

## Ask it for

In chat, or as a run's prompt:

```text theme={null}
Checkout-api started returning 5xx at 14:10 UTC today. Nothing deployed in that
window. Tell me what changed in AWS in the two hours before, and whether any of it
touches checkout-api's dependencies. Cite the evidence.
```

When a workflow drives it instead of a person, it takes a structured envelope:

| Field                  | What it is                                                                |
| ---------------------- | ------------------------------------------------------------------------- |
| `incident_description` | What is happening, in a sentence or two                                   |
| `questions`            | The specific questions to answer — the agent scopes its work to these     |
| `affected_services`    | Service names, to narrow the search                                       |
| `investigation_start`  | An ISO-8601 timestamp; it looks no further back. Defaults to 24 hours ago |
| `context`              | Enrichment already gathered — alerts, errors, deploys                     |
| `budget_seconds`       | A shorter or longer wall-clock budget for this run                        |

## Defaults and limits

|             |                                        |
| ----------- | -------------------------------------- |
| Catalog ID  | `aws-investigator`                     |
| Model       | `claude-sonnet-4-6`                    |
| Time budget | 300 seconds, adjustable 60–900 per run |
| Deployment  | Komodor cloud or self-hosted           |
| Chat        | Yes                                    |

The time budget degrades rather than fails. At 70% the agent is told how long is left and nudged to
close the chain it is on instead of opening another. At 100% further tool calls are refused and it
reports what it has — so a long investigation returns a partial report rather than nothing.

## In a workflow

This is a specialist, not a lead. In an incident workflow it takes a scoped sub-task from an
orchestrator, investigates the AWS slice of the problem, and hands its findings back to be
synthesized with the other specialists' work. Add a second investigator for another system when an
incident spans both — they run independently and their findings are combined.

See [Orchestration](/manage-your-agents/run/orchestration) for how a step delivers work to it, and
[Incidents](/modules-and-workflows/sre/incidents) for the module that drives it.

## What it will not do

It never changes anything in AWS. There is no mutating tool in its surface, in either deployment
mode, so it cannot stop an instance, edit a policy or roll back a change — it can only tell you
which one it thinks is responsible. Turning a finding into an action is [Remediation
Executor](/manage-your-agents/build/catalog/remediation-executor)'s job.

It also sees only what its credentials reach. An investigation scoped to one account cannot observe
a cause that lives in another, and it reports the gap rather than inferring across it.

## Next steps

<CardGroup cols={2}>
  <Card title="Use specialized agents" href="/manage-your-agents/build/use-specialized-agents">
    Browse the catalog and walk the deploy wizard.
  </Card>

  <Card title="AWS Cost Analyzer" href="/manage-your-agents/build/catalog/aws-cost-analyzer">
    The same account, read for waste rather than incidents.
  </Card>

  <Card title="Runs & evidence" href="/manage-your-agents/run/runs-evidence">
    Read the tool calls behind a finding.
  </Card>

  <Card title="Agent catalog" href="/manage-your-agents/build/catalog/overview">
    Every catalog agent, side by side.
  </Card>
</CardGroup>


## Related topics

- [Azure Investigator](/manage-your-agents/build/catalog/azure-investigator.md)
- [Google Cloud Investigator](/manage-your-agents/build/catalog/gcp-investigator.md)
- [AWS Cost Analyzer](/manage-your-agents/build/catalog/aws-cost-analyzer.md)
- [Agent catalog](/manage-your-agents/build/catalog/overview.md)
- [Orchestration](/manage-your-agents/run/orchestration.md)