Metadata-Version: 2.4
Name: aws-ar
Version: 3.0
Summary: Command Line Utility for Configuring Assumed AWS IAM Role Credentials. Supports Endpoint Extractor and Role Chaining.
Author: Shashank Dubey
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AWS-AR (AWS Assume Role CLI Utility) 🚀

![PyPI - Version](https://img.shields.io/pypi/v/aws-ar)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aws-ar)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

**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:

```bash
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.

```bash
# 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.

```bash
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.

```bash
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):

```bash
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`!

```bash
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:
```bash
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.
