AWS Intel

AWS Intel (awsi) is a command-line utility for signing in to AWS accounts, inspecting security-group relationships, opening the AWS Management Console, and managing SSM port-forwarding sessions.

Requirements

• Python 3.10 or newer
• AWS CLI v2

Installation

Install the latest release with pipx, which keeps the application in an isolated environment while making awsi available on your PATH:

pipx install aws-intel

Alternatively, install it into the current Python environment:

python -m pip install aws-intel

Verify the installation:

awsi --version
awsi help

Every invocation performs a one-second PyPI version check. If a newer release is available, the upgrade notice is written to standard error; command output on standard output remains safe to pipe or parse. An unavailable PyPI endpoint does not prevent the command from running.

Quick start

Create example configuration files in the current directory:

awsi init

This creates .awsi/accounts.yaml and .awsi/forwards.yaml. Existing files are preserved. To replace both files with fresh examples, use:

awsi init --force

Edit the generated values, then sign in and verify the active identity:

awsi login example-chained
aws sts get-caller-identity
exit

Configuration is resolved relative to the current working directory. Run awsi from the directory containing .awsi.

Configuration

AWS accounts

.awsi/accounts.yaml defines the accounts available to awsi login. A root account authenticates directly with IAM Identity Center. A chained account names another account as its source; AWS Intel signs in through the root and assumes each configured role in order.

Complete accounts.yaml example

The two definitions below collectively demonstrate every supported option. Replace all example values with values for your AWS environment.

version: 1

accounts:
  example-source:
    account_id: "111111111111"
    role_name: ExampleSourceRole
    region: eu-west-1
    color: "#4F8EF7"
    sso_start_url: https://example.awsapps.com/start
    sso_region: eu-west-1
    elevated_access:
      provider: team
      role_name: ExampleSourceElevatedRole

  example-chained:
    account_id: "222222222222"
    role_name: ExampleChainedRole
    region: eu-central-1
    color: "#F59E0B"
    source: example-source
    session_duration_hours: 4
    elevated_access:
      provider: team
      role_name: ExampleChainedElevatedRole
      source_role: ExampleSourceElevatedRole

Account options

The root account must contain sso_start_url and sso_region. Other accounts in the chain must use source instead. Temporary credentials are placed only in the authenticated subshell environment; AWS Intel does not modify ~/.aws/config or write credentials to the repository or ~/.aws/credentials.

The supported CSS basic color names are black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, and aqua. Names are case-insensitive. Custom colors must be quoted so YAML does not interpret the leading # as a comment:

color: red
# or use a custom RGB value:
# color: "#123123"

Saved port forwards

.awsi/forwards.yaml defines reusable SSM port-forwarding connections. Each forward selects its bastion by either EC2 instance ID or exact EC2 Name tag.

Complete forwards.yaml example

The alternatives instance-id and instance-name cannot appear in the same forward, so this example includes one definition of each kind.

forwards:
  database-by-id:
    instance-id: i-0123456789abcdef0
    host: database.internal.example
    port: 5432:5432

  api-by-name:
    instance-name: public-bastion
    host: api.internal.example
    port: 8080:80

Forward options

Only EC2 instances in pending or running state are considered when resolving instance-name. awsi forward save can add or replace a definition without starting it.

Command-line usage

Commands use this structure:

awsi <utility> <options>

Discover utilities and their current options with:

awsi help
awsi help login
awsi help forward
awsi <utility> --help

Log in to an AWS account

awsi login [ACCOUNT]
awsi login --list
awsi login ACCOUNT --elevated

awsi login performs IAM Identity Center authentication, resolves the account chain, and opens a subshell containing temporary credentials. Exit that shell to return to the previous session. With no account in an interactive terminal, it prompts for a configured account and, when available, standard or TEAM elevated access. Escape, Ctrl+C, and Ctrl+D cancel a selection.

--list prints configured account names without logging in. --elevated uses the account's configured temporary TEAM role; the TEAM assignment must already be active.

Open the AWS Management Console

From a shell opened by awsi login, run:

awsi console

AWS Intel exchanges the current temporary credentials for a console sign-in URL and opens it in the default browser. The URL is never printed.

Label authenticated zsh sessions

If a zsh theme replaces the prompt set by awsi login, add this to ~/.zshrc:

eval "$(awsi shell-init zsh)"

Authenticated prompts are prefixed with the active role and account, such as [ExampleSourceRole@example-source]. Prompts outside an AWS Intel login shell are unchanged.

Inspect a security group tree

awsi security-group-tree SECURITY_GROUP_ID [SECURITY_GROUP_ID ...] [options]

Examples:

awsi security-group-tree sg-0123456789abcdef0
awsi security-group-tree sg-0123456789abcdef0 --depth 2 --inbound
awsi security-group-tree sg-0123456789abcdef0 --filter database

Options:

The command uses the active AWS CLI credentials and Region. It displays attached resources, IPv4 and IPv6 ranges, managed prefix lists, and connected security groups. For RFC 1918 IPv4 ranges, it also resolves matching network interfaces inside the security group's VPC. This discovery requires ec2:DescribeNetworkInterfaces and ec2:DescribeTags in addition to permission to describe security groups and prefix lists.

Manage SSM port forwards

Start a saved forward:

awsi forward start database-by-id

Start an explicitly described forward without saving it:

awsi forward start database \
  --instance-name public-bastion \
  --host database.internal.example \
  --port 5432:5432

Save or replace a definition without starting it:

awsi forward save database \
  --instance-id i-0123456789abcdef0 \
  --host database.internal.example \
  --port 5432:5432

List and manage forwards:

awsi forward list
awsi forward hosts
awsi forward active
awsi forward stop database
awsi forward stop 4321
awsi forward stop --all
awsi forward restart database
awsi forward restart 4321
awsi forward restart --all

Running awsi forward start without arguments interactively selects one or more saved definitions. Saved forwards that are already running remain visible in the selection overview as active, but cannot be selected again. Running awsi forward stop without a name, PID, or --all interactively selects active sessions. Active-session output is tab-separated and includes a header. AWS Intel rejects duplicate active forwards and unavailable local ports before starting a background session.

awsi forward hosts requires ssm:DescribeInstanceInformation and ec2:DescribeInstances. Starting a session requires ssm:StartSession and the associated session-channel permissions.

The legacy forms awsi forward NAME, awsi forward --list, awsi forward --kill, and awsi forward --list-hosts remain supported for backward compatibility. The action-based commands above are recommended.

Generate configuration

awsi init [--force]

This writes anonymized examples to .awsi/accounts.yaml and .awsi/forwards.yaml in the current directory. --force overwrites existing configuration files. The complete examples in the configuration section above show every supported field, including mutually exclusive alternatives.

Contributing

The project uses Poetry for development. Clone the repository, then install the package and development dependencies:

poetry install

Run the CLI and test suite:

poetry run awsi --help
poetry run pytest

Build wheel and source-distribution artifacts with:

poetry build

Keep CLI parsing and presentation separate from application logic, isolate AWS CLI calls behind integration boundaries, and add deterministic tests for behavior changes. Tests must not contact live AWS services unless explicitly marked as integration tests.