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

# AWS

> Connect your AWS accounts to Kestrel for resource inventory, security monitoring, and VPC Flow Logs analysis

Connect your AWS accounts to Kestrel using cross-account IAM roles for secure, credential-free access to your cloud resources. Kestrel discovers and inventories AWS resources, detects security misconfigurations, and collects VPC Flow Logs for network traffic analysis.

## Prerequisites

* **Organization Admin** role in Kestrel
* AWS account with permissions to create IAM roles and policies
* AWS CLI or access to the AWS Console

## Setup

**1. Start the connection**

1. Navigate to **Integrations → Cloud** in your Kestrel dashboard
2. Click **Connect AWS Account**
3. Select your AWS region
4. Select the connection purpose:

| Purpose | Description |
| - | - |
| **EKS** | Kubernetes cluster discovery and monitoring |
| **VPC Flow Logs** | VPC Flow Log collection and analysis |
| **Cloud Ingestion** | Full cloud resource inventory and security monitoring |

5. Click **Generate CloudFormation Template**

**2. Deploy the CloudFormation stack**

Kestrel generates a CloudFormation template that creates a cross-account IAM role with minimum required permissions.

**Option A: AWS Console (One-Click)**

Click the **Launch Stack** link provided in the setup dialog. Review the parameters and click **Create Stack**.

**Option B: AWS CLI**

```bash theme={null}
aws cloudformation create-stack \
  --stack-name kestrel-ai-integration \
  --template-url <provided-url> \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters ParameterKey=ExternalId,ParameterValue=<your-external-id>
```

**3. Verify the connection**

1. Once the stack reaches `CREATE_COMPLETE`, copy the **Role ARN** from the stack outputs
2. Paste the Role ARN into the Kestrel verification dialog
3. Click **Verify Connection**

Kestrel assumes the role and validates permissions. On success, your account appears as **Connected**.

> [!NOTE]
>
> You can create multiple connections to the same AWS account with different purposes, or use a single **Cloud Ingestion** connection for comprehensive coverage.

### VPC Flow Logs

After connecting with VPC Flow Logs capability:

1. Navigate to the connected account in the Cloud Integrations page
2. Expand the **VPC Flow Logs** section
3. Click **Enable** to start collecting flow logs across your VPCs
4. Kestrel creates the necessary log groups and flow log configurations automatically

You can enable/disable flow logs on individual VPCs.

## How It's Used

### In Workflows

**Trigger blocks:**

* **IAM Security Event** — fires on IAM role, policy, or user changes detected via CloudTrail
* **Root Account Activity** — fires when the AWS root account is used
* **KMS Key Change** — fires on KMS key creation, deletion, or policy changes
* **Secrets Manager Event** — fires on secret creation, rotation, or deletion in Secrets Manager
* **Security Hub Finding** — fires when AWS Security Hub reports a new finding
* **S3 Bucket Change** — fires on S3 bucket policy, ACL, or public access changes
* **EC2 Instance Issue** — fires on EC2 instance state changes, status check failures, or termination
* **Lambda Function Issue** — fires on Lambda invocation errors, throttles, or configuration changes
* **ECS/EKS Container Issue** — fires on ECS task failures or EKS cluster events
* **RDS Database Issue** — fires on RDS instance failures, failovers, or storage issues
* **DynamoDB Issue** — fires on DynamoDB table throttles, capacity changes, or errors
* **VPC/Network Change** — fires on VPC, security group, NACL, or route table modifications
* **CloudWatch Alarm** — fires when a CloudWatch alarm transitions to ALARM state
* **Application Log Errors** — fires when application log error patterns exceed a threshold
* **Config Rule Non-Compliant** — fires when an AWS Config rule evaluates a resource as non-compliant
* **AWS Service Health Event** — fires on AWS Health Dashboard service disruptions affecting your account
* **Any AWS Cloud Incident** — fires on any AWS cloud incident detected by Kestrel
* **Cost Anomaly Detected** — fires when AWS Cost Anomaly Detection identifies unusual spend
* **Budget Threshold Exceeded** — fires when an AWS Budget threshold is breached
* **Forecast Exceeds Budget** — fires when the Cost Explorer forecast projects a budget overrun before it happens
* **Spend Spike Detected** — fires when day-over-day spend rises beyond a configurable percentage threshold
* **Idle Resource Detected** — fires when a daily scan finds idle resources (unattached EBS volumes, unassociated Elastic IPs, low-CPU instances, old snapshots)

**Cost optimization action blocks:**

Connected accounts unlock the Cloud Cost action blocks in workflows:

* *Insights (read-only)*: Query Cost Explorer, Get Cost Anomalies, Get Cost Forecast, Get Budget Status, Get Rightsizing Recommendations, Get Savings Plans Recommendations, Get Reservation Recommendations, Get Commitment Utilization, Compare Cost Periods, Find Idle Resources, Get Compute Optimizer Recommendations, Get Trusted Advisor Cost Checks
* *Remediation (mutates infrastructure — place behind an Approval block)*: Stop EC2 Instances, Delete Unattached EBS Volumes, Release Elastic IPs, Delete Old Snapshots. Resources tagged `kestrel:protected` are always skipped.

Cloud operations (querying resources, describing instances, checking security groups, generating Terraform fixes, creating IaC remediation PRs) are provided by Kestrel's built-in action blocks and are available in any workflow alongside these triggers.

Example: A workflow triggers on a Security Hub finding, queries the affected resource details, generates a Terraform fix, and opens a pull request in the connected IaC repository.

### In Incident Response

* **Cloud security monitoring** — detects misconfigurations across EC2, S3, RDS, IAM, and other services
* **Terraform fix generation** — when a misconfiguration is found, Kestrel generates a Terraform fix targeting the exact IaC file in your connected repository
* **VPC Flow Log analysis** — analyzes traffic patterns to identify anomalous network behavior

### In Cloud AI Copilot

* Ask questions about your AWS resources: `What S3 buckets have public access?`
* Investigate security findings: `Show me all EC2 instances with open SSH access`
* Query costs and resource utilization across accounts

## IAM Permissions

The CloudFormation-created IAM role includes **read-only** access to:

* EC2 (instances, security groups, VPCs, subnets, flow logs)
* S3 (bucket policies, public access settings)
* RDS (instances, clusters, security)
* IAM (roles, policies, users — metadata only)
* CloudTrail (event history)
* EKS (clusters, node groups)
* Lambda, ECS, and other compute services
* Cost Explorer, Budgets, Compute Optimizer, and Trusted Advisor (cost and usage data, recommendations)

Write permissions are limited to VPC Flow Log management (creating/deleting flow log configurations) and the cost-remediation actions (`ec2:StopInstances`, `ec2:DeleteVolume`, `ec2:ReleaseAddress`, `ec2:DeleteSnapshot`, plus `ec2:CreateSnapshot` for pre-deletion safety snapshots) used by the Cloud Cost remediation workflow blocks.

> [!NOTE]
>
> If you connected your account before the cost-optimization blocks were released, update your CloudFormation stack to the latest template to grant the new Cost Explorer, Budgets, Compute Optimizer, and remediation permissions. Blocks that lack permissions fail with an actionable error pointing at the stack update.

## Managing Connections

* **Refresh**: Re-sync connection status and resource inventory
* **Delete**: Removes the connection from Kestrel. Clean up the CloudFormation stack in AWS separately.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.