Skip to content

13-aws-audit-assistant

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

13-aws-audit-assistant

README.md

AWS Audit Assistant: Automated Resource Compliance Checker

⚠️ Important Security Notice

This tool executes scripts that may affect your AWS environment. Always run it from a sandbox environment with read-only permissions. A Terraform script is provided in the sandbox folder to create an EC2 instance with the appropriate read-only IAM role for safe auditing.

🎯 Overview

AWS Audit Assistant is your AI-powered partner for ensuring AWS resource compliance with best practices. It provides intelligent insights and recommendations for security and efficiency improvements.

Architecture Diagram

🏗️ Architecture

Components

  • Multi-Agent System: Coordinated agents working together for comprehensive auditing
  • Documentation Retriever: Fetches and analyzes AWS best practices documentation
  • Boto3 Code Assistant: Generates and executes AWS API calls safely
  • Resource Auditor: Evaluates resources against compliance standards

Technical Stack

Component Description
Model Provider Amazon Bedrock (Claude 3.5 Sonnet)
Native Tools boto3, file_read, shell, python_repl
Custom Agents Documentation Retriever, Boto3 Code Assistant, Resource Auditor

📋 Prerequisites

  1. AWS Account with appropriate permissions

    Required Permissions:

    • Create EC2 instances
    • Create IAM roles
    • Create Security Groups

    Additional Resources:

  2. Python 3.11 or higher

  3. uv package manager

  4. AWS credentials configured locally or appropriate IAM role

  5. Terraform (for sandbox environment)

🚀 Installation & Setup

Option 1: Local Installation (Development Only)

⚠️ IMPORTANT: This option is strictly for development and testing purposes only. DO NOT use this installation method in any production environment as it may not have the necessary security controls and could potentially impact your AWS resources. For production use, always use Option 2 (Sandbox Environment) which provides proper isolation and read-only permissions.

# Install dependencies using uv
uv pip install -r requirements.txt

# Run the assistant
uv run ai_assistant.py

Option 2: Sandbox Environment (Recommended)

The sandbox environment provides a secure way to run the AWS Audit Assistant with appropriate read-only permissions. It includes Terraform configurations to create an EC2 instance with the necessary IAM roles and security settings.

1. Deploy Infrastructure

# Navigate to sandbox directory
cd sandbox

# Initialize Terraform
terraform init

# Review the deployment plan
terraform plan

# Deploy the resources
terraform apply

Learn more:

2. Copy Required Files

After the infrastructure is deployed, copy the necessary files to the EC2 instance:

scp -i ./audit-assistant-key.pem \
    ../ai_assistant.py \
    ../aws_document_agent.py \
    ../strands_boto_agent.py \
    ../requirements.txt \
    ec2-user@<instance-public-ip>:/home/ec2-user/

Learn more:

3. Install Dependencies

SSH into the EC2 instance and install the required packages:

# Connect to the instance
ssh -i ./audit-assistant-key.pem ec2-user@<instance-public-ip>

# Install dependencies
pip3 install -r requirements.txt

Learn more:

4. Run the Assistant

python3 ai_assistant.py

Security Features

  • EC2 instance is configured with read-only IAM role
  • Security group limits inbound access
  • All operations are performed with least-privilege permissions
  • Terraform-managed infrastructure for consistency

Learn more:

Cleanup

When you're done using the sandbox environment, destroy the resources to avoid unnecessary charges:

terraform destroy

Learn more:

💡 Usage Examples

The AWS Audit Assistant accepts natural language queries about your AWS resources. Here are some example commands:

> Check if my S3 bucket 'my-bucket' follows security best practices
> Audit EC2 instance 'i-1234567890abcdef0' in us-west-2 for security compliance
> Verify if my IAM policies follow the principle of least privilege
> Evaluate RDS database 'my-database' configuration against AWS recommendations

🔍 Features

  • Comprehensive Auditing: Evaluates resources against AWS best practices
  • Natural Language Interface: Simple English commands to perform complex audits
  • Safe Execution: Read-only operations by default
  • Detailed Reports: Clear findings and recommendations
  • Multi-Resource Support: Covers S3, EC2, IAM, RDS, and more
  • Best Practice Updates: Stays current with AWS recommendations

🛡️ Security Best Practices

  1. Always use the sandbox environment for production audits
  2. Review generated scripts before execution
  3. Use read-only IAM roles when possible
  4. Monitor AWS CloudTrail for audit activities
  5. Regularly update dependencies for security patches

❗ Troubleshooting

EC2 Connection Issues

If you can't connect to the EC2 instance:

  • Verify your security group allows SSH access from your IP
  • Ensure you're using the correct key pair
  • Check that the instance is running

Resources:

Dependency Installation

If dependencies fail to install:

  • Verify Python version (3.11+ required)
  • Check internet connectivity
  • Ensure pip is up to date

Resources:

Assistant Runtime Issues

If the assistant fails to run:

  • Verify all required files were copied correctly
  • Check AWS credentials are properly configured
  • Review EC2 instance role permissions

Resources:

📚 Additional Resources

🆘 Support

For issues or questions:

  1. Review the troubleshooting section above
  2. Check AWS Documentation
  3. Visit the AWS Support Center
  4. Submit issues through the project's issue tracker

⚖️ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.