Building a CLI for AWS Privileged Actions with Centralized Root Access

July 15, 2025

When managing AWS Organizations, there are rare but critical moments when you need to perform privileged actions on member accounts—actions that traditionally required root access. With AWS's introduction of Centralized Root Access Management, these operations can now be performed securely through privileged root task policies. However, the current tooling leaves much to be desired for day-to-day operations.

That's why I built the AWS Privileged Actions CLI: a Python-based tool that wraps AWS's assume-root capability, making it fast, safe, and operator-friendly for the rare moments when you need root-level access.

The Problem: ClickOps and Complex Commands

Before diving into the solution, let's understand the challenges operators face:

Limited AWS Tooling

AWS doesn't provide an API to list available root task policies. Operators must memorize policy names and ARNs or constantly reference documentation. When you're responding to an incident at 2 AM, this friction matters.

Complex AWS CLI Syntax

The native AWS CLI command for assuming root privileges is powerful but verbose and error-prone:

aws sts assume-root \
  --target-principal arn:aws:iam::123456789012:root \
  --task-policy-arn arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials \
  --duration-seconds 900 \
  --region us-east-1

There is a lot of room for error here:

  • The regional endpoint requirement is easy to miss
  • The listing of policies is not dynamic, and cannot be retrieved from the AWS API
  • The command is verbose and error-prone

ClickOps Limitations

Most enterprise organizations disable or heavily restrict console access for security reasons. Even when available, the AWS console for root actions involves multiple navigation steps and doesn't provide the automation capabilities needed for operational workflows.

The Solution: A Purpose-Built CLI

I designed the AWS Privileged Actions CLI with three core principles:

  1. Simplicity: Minimal commands with smart defaults
  2. Safety: Built-in validation and best practices
  3. Speed: Interactive prompts when needed, scriptable when not

Key Features

1. Policy Discovery

Since AWS doesn't provide an API for listing root task policies, the CLI includes them as a curated list:

aws-priv-actions list-policies

In the future, I plan on updating this hard-coded list to dynamically fetch the policies from AWS.

This displays a formatted table of all available policies with descriptions, eliminating guesswork.

2. Smart Interactive Mode

When you omit required parameters, the CLI switches to interactive mode:

aws-priv-actions assume-root
# Prompts for:
# - Target principal (with validation)
# - Task policy (numbered menu)
# - AWS region (with smart defaults)
# - Duration (optional)

3. Regional Endpoint Enforcement

One critical requirement AWS imposes is using regional STS endpoints for root operations. The CLI enforces this automatically.

Real-World Usage

Emergency Scenarios

When a critical S3 bucket policy is blocking legitimate access:

aws-priv-actions assume-root arn:aws:iam::123456789012:root S3UnlockBucketPolicy --region us-east-1

The CLI handles:

  • Policy ARN construction
  • Regional endpoint selection
  • Credential management
  • Error reporting

Scripted Operations

For repeatable operations, the CLI works in non-interactive mode:

#!/bin/bash
ACCOUNT_ID="123456789012"
REGION="us-east-1"

# Audit root credentials across multiple accounts
for account in $(cat accounts.txt); do
  aws-priv-actions assume-root \
    "arn:aws:iam::${account}:root" \
    IAMAuditRootUserCredentials \
    --region $REGION \
    --duration-seconds 300
done

Future Enhancements

As AWS continues to evolve their privileged access features, the CLI can grow with them:

  • New Policy Support: Easy addition of new root task policies as AWS releases them
  • Policy Simulation: Dry-run mode to validate operations without execution

Check it out!

The CLI is available on PyPI and can be installed with modern Python package managers:

# Using pip
pip install aws-priv-actions

# Using uv (recommended for speed)
uv add aws-priv-actions

Basic usage:

# List available policies
aws-priv-actions list-policies

# Interactive mode
aws-priv-actions assume-root

# Direct command
aws-priv-actions assume-root \
  arn:aws:iam::123456789012:root \
  IAMAuditRootUserCredentials \
  --region us-east-1

Have you built tools to simplify complex AWS operations? I'd love to hear about your approach to operator-friendly tooling. Reach out on LinkedIn.