aws-iam-security-agent 1.0.1

AWS IAM security agent with GPT-4 for key rotation & secrets management

aws-iam-agent

An AI-powered AWS IAM security agent built with LangChain and GPT-4. Query IAM state, audit security posture, simulate permissions, analyze least privilege, rotate access keys, and manage secrets — all from your terminal in plain English.

What it does

Instead of writing one-off CLI scripts or digging through the AWS console, just ask:

The agent figures out which AWS API calls to make, executes them in real time, and returns a plain English answer.

Capabilities

Read IAM state — query users, roles, policies, and access keys.

Security audit — scan all users for stale keys, missing MFA, overly permissive policies, and get a risk-scored report (CRITICAL/HIGH/MEDIUM/LOW).

Credential report — generate the AWS-native credential report for a full account health snapshot: password age, MFA status, key age, and last login for every user.

Policy simulator — test "can user X do action Y on resource Z?" using the IAM Policy Simulator API without actually making the call. Also test draft policies before attaching them.

Least privilege analysis — use Access Advisor to find which services a user or role has permissions for but has never used. Get actionable recommendations for tightening permissions.

Key rotation — create new access keys, deactivate/delete old ones, detect stale keys (>90 days). Handles the AWS 2-key limit automatically.

Secrets Manager — store rotated credentials safely, retrieve or list secrets, clean up old ones.

Atomic rotation workflow — one command to create a new key, store it in Secrets Manager, and deactivate the old key.

Tools

IAM Read

Tool	What it does
list_iam_users()	All users — UserName, UserId, ARN
list_iam_roles()	All roles and ARNs
list_iam_policies()	Customer-managed policies only
get_user_policies(username)	Attached + inline policies for a user
get_role_policies(role_name)	Attached + inline policies for a role
get_policy_document(policy_arn)	Full JSON permission document
list_access_keys(username)	Key IDs, status, creation date, age, rotation flag

Security Audit

Tool	What it does
security_audit()	Full account scan: stale keys, missing MFA, overly permissive policies, risk score
generate_credential_report()	AWS-native credential report: password, MFA, key status for all users

Policy Simulator

Tool	What it does
simulate_policy(arn, actions, resources)	Test if a user/role can perform specific actions on resources
simulate_custom_policy(policy_json, actions, resources)	Test a draft policy document before attaching it

Least Privilege Analysis

Tool	What it does
get_unused_permissions(arn)	Find services allowed but never accessed, with removal recommendations
get_last_accessed_details(arn)	Quick view of when each service was last accessed

Key Rotation

Tool	What it does
create_access_key(username)	Create a new access key pair
deactivate_access_key(username, key_id)	Deactivate a key without deleting
delete_access_key(username, key_id)	Permanently delete a key
rotate_and_store_key(username, secret_name)	Full rotation: new key, store in Secrets Manager, deactivate old

Secrets Manager

Tool	What it does
store_secret(name, value)	Create or update a secret
get_secret(name)	Retrieve a secret value
list_secrets()	List all secrets (names and ARNs)
delete_secret(name)	Delete a secret (with recovery window)

Installation

Via pip

pip3 install aws-iam-agent

Via Homebrew

brew tap sujay2306/aws-iam-agent
brew install sujay2306/aws-iam-agent/aws-iam-agent

Setup

Create a .env file in your working directory:

OPENAI_API_KEY=sk-proj-...
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

Permissions: For read-only queries and audits, IAMReadOnlyAccess is sufficient. For key rotation, add iam:CreateAccessKey, iam:UpdateAccessKey, iam:DeleteAccessKey. For Secrets Manager, add SecretsManagerReadWrite. For the policy simulator, add iam:SimulatePrincipalPolicy and iam:SimulateCustomPolicy. For Access Advisor (least privilege), add iam:GenerateServiceLastAccessedDetails and iam:GetServiceLastAccessedDetails.

Usage

aws-iam-agent

🔐 IAM Agent (GPT-4) ready. Ask anything about your AWS IAM setup.
   Now with key rotation & Secrets Manager support.

You: audit my account
Agent: Security audit complete. Risk: HIGH (7 issues found)
  CRITICAL: deploy-bot has console access but NO MFA
  CRITICAL: terraform-admin has full admin policy (Action:*, Resource:*)
  HIGH: ci-runner key AKIA...WXYZ is 127 days old — needs rotation
  ...

You: can deploy-bot do s3:GetObject on my production bucket?
Agent: Testing with IAM Policy Simulator...
  s3:GetObject → ALLOWED (matched policy: S3ReadAccess)
  deploy-bot CAN read from that S3 bucket.

You: what permissions is sujay-ks not using?
Agent: Access Advisor analysis for sujay-ks:
  42 services allowed, only 6 ever used.
  36 services have NEVER been accessed — candidates for removal:
  - AWS CloudFormation, AWS CodeDeploy, Amazon DynamoDB, ...

You: rotate deploy-bot's key and store it as prod/deploy-bot-creds
Agent: Rotation complete:
  - New key AKIA...ABCD created
  - Stored in Secrets Manager as "prod/deploy-bot-creds"
  - Old key AKIA...WXYZ deactivated

You: exit

Requirements

• Python 3.11+
• OpenAI API key
• AWS credentials with appropriate IAM and Secrets Manager permissions

Built with

• LangChain
• OpenAI GPT-4
• boto3

License

MIT