Pacu is an open-source AWS exploitation and post-exploitation framework developed by Rhino Security Labs. Named after the piranha-like fish, Pacu is designed to operate the way a real attacker would once they have obtained a set of AWS credentials — whether through a phishing attack, a leaked access key on GitHub, an SSRF vulnerability against an EC2 instance metadata service, or as part of an authorized penetration test where a client provides limited-privilege credentials.
Pacu is modular, similar in philosophy to the Metasploit Framework, and includes over 60 modules across several categories:
- Reconnaissance / Enumeration — discovering IAM users, roles, policies, EC2 instances, S3 buckets, Lambda functions, and more.
- Privilege Escalation — automatically testing over 20 known IAM privilege escalation paths (e.g.,
iam:CreatePolicyVersion,iam:PassRole+lambda:CreateFunction,ec2:RunInstanceswith an attached admin role). - Persistence — creating backdoor IAM users/roles, adding access keys, modifying Lambda functions for long-term access.
- Exploitation — module-specific attacks against services like Lambda, RDS, CloudFormation, and Systems Manager.
- Data Exfiltration — dumping S3 bucket contents, RDS snapshots, Secrets Manager secrets, and Systems Manager parameters.
Pacu maintains a local SQLite database to track sessions, discovered credentials, and enumerated resources, allowing an operator to build up a complete picture of an AWS account across multiple modules and sessions without needing to re-run reconnaissance every time.
Important: Because Pacu performs active, and sometimes destructive or state-changing, operations (unlike ScoutSuite or Prowler which are strictly read-only), it must only ever be run against AWS accounts you own or for which you have explicit written authorization, ideally with a clearly scoped rules of engagement document.
Installation
Method 1: APT (Kali Linux default repositories)
sudo apt update
sudo apt install pacu -y
Method 2: From source (GitHub, recommended for latest modules)
git clone https://github.com/RhinoSecurityLabs/pacu.git
cd pacu
bash install.sh
Method 3: Manual Python environment setup
git clone https://github.com/RhinoSecurityLabs/pacu.git
cd pacu
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 pacu.py
Verify installation / launch:
pacu
Expected output:
____
| _ \ __ _ ___ _ _
| |_) / _` |/ __| | | |
| __/ (_| | (__| |_| |
|_| \__,_|\___|\__,_|
Pacu (v1.5.2) - AWS exploitation framework
This is a session-based tool. Please choose or create a session:
No sessions saved yet. What would you like to name your new session?
>
Syntax
Pacu is primarily an interactive REPL/shell environment, not a single-shot CLI command. It is launched with:
pacu [options]
Once inside the interactive shell, commands follow this general syntax:
Pacu (session_name:IamUser/username) > <command> [arguments]
Common command patterns:
run <module_name> [--module-arguments]
exec <module_name> [--module-arguments]
set_keys
set_regions <region1> <region2> ...
whoami
data
services
Complete Command-Line Options Reference
Launch-time CLI Flags
pacu Launch Pacu with interactive session selection
pacu --session SESSION_NAME Launch directly into a named session
pacu --module-name MODULE Run a single module non-interactively then exit
pacu --list-modules List all available modules and exit
pacu --version Display Pacu version
pacu --help Display CLI help menu
Interactive Shell Commands
help Show general help and list of commands
help <module> Show detailed help/arguments for a specific module
list / ls List all available modules by category
search <keyword> Search modules by keyword
run <module> [args] Execute a module (alias: exec)
set_keys Add/select AWS access key credentials for the session
swap_keys Switch between saved credential sets
set_regions <region> [...] Set the AWS regions Pacu will operate in
whoami Display current IAM identity and permissions
data View all data collected so far in the session
data <service> View collected data for a specific service (e.g., data S3)
services List AWS services with data currently stored
regions List all AWS regions
proxy Enable/manage an HTTP proxy for AWS API calls
import_keys <profile> Import credentials from the local AWS CLI config
export_keys Export current session's credentials
sessions / list_sessions List all saved Pacu sessions
swap_session Switch to a different saved session
delete_session Delete the current session and its data
history Show command history for the session
exit / quit Exit the Pacu shell
Module Execution Flags (vary per module, common examples)
run iam__enum_permissions Enumerate current user/role's effective IAM permissions
run iam__enum_users_roles_policies_groups Enumerate all IAM users, roles, policies, groups
run iam__privesc_scan Scan for possible IAM privilege escalation paths
run iam__privesc_scan --offline Run privesc scan using only already-collected data
run s3__bucket_finder Enumerate S3 buckets accessible to the account
run s3__download_bucket --name BUCKET_NAME Download contents of a specified S3 bucket
run ec2__enum Enumerate EC2 instances, AMIs, snapshots
run ec2__download_userdata Retrieve EC2 instance user-data scripts (may contain secrets)
run lambda__enum Enumerate Lambda functions
run lambda__backdoor_new_roles Add a backdoor to newly created IAM roles via Lambda
run secretsmanager__enum Enumerate and dump AWS Secrets Manager secrets
run systemsmanager__download_sensitive_documents Download sensitive SSM documents/parameters
Basic Usage
Starting a new session and setting credentials:
$ pacu
No sessions saved yet. What would you like to name your new session?
> client_engagement_01
Session created: client_engagement_01
Pacu (client_engagement_01:No Keys Set) > set_keys
What would you like to name this set of keys? [default]
> pentest_creds
Key alias: pentest_creds
Access Key ID: AKIAIOSFODNN7EXAMPLE
Secret Access Key: ********************************
Session Token (leave blank if none):
Keys saved to database.
Pacu (client_engagement_01:pentest_creds) > whoami
{
"UserName": "pentest-user",
"Arn": "arn:aws:iam::123456789012:user/pentest-user",
"AccountId": "123456789012",
"Permissions": {
"Allow": ["s3:*", "ec2:Describe*", "iam:List*"],
"Deny": []
}
}
Practical Examples with Output
Example 1: Enumerate current user’s effective IAM permissions
Pacu (client_engagement_01:pentest_creds) > run iam__enum_permissions
[iam__enum_permissions] Starting module...
[iam__enum_permissions] Confirming permissions for pentest-user...
[iam__enum_permissions] -- s3:ListAllMyBuckets: Allow
[iam__enum_permissions] -- s3:GetObject: Allow
[iam__enum_permissions] -- ec2:DescribeInstances: Allow
[iam__enum_permissions] -- iam:CreatePolicyVersion: Allow <-- Potential privesc!
[iam__enum_permissions] iam__enum_permissions completed.
Example 2: Full IAM enumeration of users, roles, groups, and policies
Pacu (client_engagement_01:pentest_creds) > run iam__enum_users_roles_policies_groups
[iam__enum_users_roles_policies_groups] Enumerating IAM users...
Found 14 users
[iam__enum_users_roles_policies_groups] Enumerating IAM roles...
Found 22 roles
[iam__enum_users_roles_policies_groups] Enumerating IAM policies...
Found 41 managed policies
[iam__enum_users_roles_policies_groups] Data saved to Pacu database.
Example 3: Automated privilege escalation path scan
Pacu (client_engagement_01:pentest_creds) > run iam__privesc_scan
[iam__privesc_scan] Scanning for privilege escalation methods...
[iam__privesc_scan] CONFIRMED: CreateNewPolicyVersion -- pentest-user can escalate via iam:CreatePolicyVersion
[iam__privesc_scan] POSSIBLE: PassExistingRoleToNewLambdaThenInvoke -- requires further permission checks
[iam__privesc_scan] Scan complete. 1 confirmed, 1 possible privesc path(s) found.
[iam__privesc_scan] Run 'run iam__privesc_scan --offline' to re-analyze without new API calls.
Example 4: Enumerate accessible S3 buckets
Pacu (client_engagement_01:pentest_creds) > run s3__bucket_finder
[s3__bucket_finder] Enumerating S3 buckets in account 123456789012...
Found bucket: client-uploads-prod (Public: False)
Found bucket: client-backups-2025 (Public: True) <-- Publicly Readable!
Found bucket: internal-config-store (Public: False)
[s3__bucket_finder] 3 buckets found, 1 flagged as publicly accessible.
Example 5: Download the contents of a discovered S3 bucket
Pacu (client_engagement_01:pentest_creds) > run s3__download_bucket --name client-backups-2025
[s3__download_bucket] Downloading bucket: client-backups-2025
[s3__download_bucket] 128 objects found (14.3 MB total)
[s3__download_bucket] Downloaded to ./sessions/client_engagement_01/downloads/client-backups-2025/
[s3__download_bucket] Module complete.
Example 6: Enumerate EC2 instances and retrieve instance user-data
Pacu (client_engagement_01:pentest_creds) > run ec2__enum
[ec2__enum] Enumerating EC2 instances across 4 regions...
us-east-1: 12 instances found
eu-west-1: 3 instances found
[ec2__enum] Enumeration complete. 15 total instances found.
Pacu (client_engagement_01:pentest_creds) > run ec2__download_userdata
[ec2__download_userdata] Retrieving user-data for 15 instances...
i-0a1b2c3d4e5f: user-data retrieved (contains hardcoded DB_PASSWORD variable!)
[ec2__download_userdata] Data saved to Pacu database. Review with 'data EC2'.
Example 7: Enumerate Lambda functions
Pacu (client_engagement_01:pentest_creds) > run lambda__enum
[lambda__enum] Enumerating Lambda functions across all regions...
us-east-1: 8 functions found
- process-payments (Role: arn:aws:iam::123456789012:role/LambdaAdminRole)
[lambda__enum] Enumeration complete.
Example 8: Enumerate and attempt to dump Secrets Manager secrets
Pacu (client_engagement_01:pentest_creds) > run secretsmanager__enum
[secretsmanager__enum] Enumerating secrets in Secrets Manager...
Found secret: prod/database/credentials (retrievable: True)
Found secret: prod/api/stripe-key (retrievable: False - AccessDenied)
[secretsmanager__enum] 1 of 2 secrets successfully retrieved and stored.
Example 9: View all data collected so far in the session
Pacu (client_engagement_01:pentest_creds) > data
Session data summary for 'client_engagement_01':
IAM: 14 users, 22 roles, 41 policies
S3: 3 buckets (1 public)
EC2: 15 instances (1 with exposed credentials in user-data)
Lambda: 8 functions
Secrets Manager: 1 secret retrieved
Example 10: Switch AWS regions for subsequent modules
Pacu (client_engagement_01:pentest_creds) > set_regions us-east-1 us-west-2 ap-southeast-1
Regions set for this session: us-east-1, us-west-2, ap-southeast-1
All subsequent regional modules will only target these regions.
Example 11: Import credentials directly from the local AWS CLI configuration
Pacu (client_engagement_01:No Keys Set) > import_keys client-readonly
Importing keys from AWS CLI profile 'client-readonly'...
Keys imported and set as active for this session.
Example 12: Run a module non-interactively from the command line for scripting
pacu --session client_engagement_01 --module-name iam__enum_permissions
[+] Loaded session: client_engagement_01
[iam__enum_permissions] Starting module...
[iam__enum_permissions] Module complete. Exiting Pacu.
Common Use Cases
- Post-exploitation simulation: Demonstrating what an attacker could achieve after obtaining a leaked or phished AWS access key.
- IAM privilege escalation testing: Validating whether low-privilege credentials can be abused to gain administrative access.
- Red team engagements: Establishing persistence, enumerating sensitive data stores, and pivoting across AWS services to demonstrate business impact.
- Credential exposure assessments: Testing what a leaked key found in a public GitHub repo or a compromised CI/CD pipeline could actually access.
- Security awareness / training labs: Teaching blue teams what attacker tradecraft against AWS looks like in a controlled environment.
- Validating detective controls: Using Pacu’s actions to confirm whether GuardDuty, CloudTrail, and SIEM alerting correctly detect suspicious AWS API activity.
Automation with Bash
Automated non-interactive recon chain:
#!/bin/bash
# pacu-auto-recon.sh
# Runs a standard recon module chain against a Pacu session non-interactively
SESSION="auto_recon_$(date +%s)"
MODULES=(
"iam__enum_permissions"
"iam__enum_users_roles_policies_groups"
"iam__privesc_scan"
"s3__bucket_finder"
"ec2__enum"
"lambda__enum"
)
echo "[+] Creating Pacu session: $SESSION"
for module in "${MODULES[@]}"; do
echo "[+] Running module: $module"
pacu --session "$SESSION" --module-name "$module"
done
echo "[+] Recon chain complete. Review with: pacu --session $SESSION"
Wrapper to import client-provided keys and kick off recon automatically:
#!/bin/bash
# pacu-onboard.sh <aws_cli_profile_name>
PROFILE="$1"
SESSION="engagement_${PROFILE}"
if [ -z "$PROFILE" ]; then
echo "Usage: $0 <aws_cli_profile_name>"
exit 1
fi
echo "import_keys $PROFILE" | pacu --session "$SESSION"
echo "[+] Session '$SESSION' created and credentials imported."
echo "[+] Launch with: pacu --session $SESSION"
Tips and Best Practices
- Always confirm written scope and authorization before running any Pacu module — many modules perform write operations (e.g., creating IAM users, modifying Lambda functions) that can be considered destructive or leave artifacts.
- Start every engagement with read-only enumeration modules (
iam__enum_permissions,*__enum) before running anything that writes to the account. - Use
iam__privesc_scan --offlineafter an initial online scan to re-analyze already-collected data without generating additional (and potentially alerting) API calls. - Regularly review the
datacommand output to build a mental model of the account before deciding which exploitation modules to run next. - Use
set_regionsto scope activity to only the regions in-scope for the engagement, both for efficiency and to avoid unauthorized testing. - Clean up any persistence artifacts (backdoor users, roles, access keys) created during testing before the engagement ends, and document them thoroughly in the report.
- Keep Pacu’s module library updated (
git pullin the source directory) since Rhino Security Labs frequently adds new privilege escalation and service-specific modules.
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
An error occurred (AccessDenied) | Session lacks permission for the target API call | Note the finding — no privilege exists; try alternate modules or accept the permission boundary |
| Session data appears missing after restart | Wrong session loaded | Use list_sessions then swap_session to select the correct one |
| Module reports “No credentials set” | Keys were never added or not activated | Run set_keys or import_keys <profile> before running modules |
| Regions not being respected by a module | Module doesn’t support regional scoping / global service | Check help <module> — some modules (e.g., IAM) are inherently global |
Rate limiting / Throttling errors | Too many rapid API calls in enumeration modules | Wait and retry, or check for a --sleep/delay argument in the specific module |
ModuleNotFoundError when launching Pacu | Missing Python dependencies | Re-run pip install -r requirements.txt inside the Pacu virtual environment |
References
- Official GitHub Repository: https://github.com/RhinoSecurityLabs/pacu
- Rhino Security Labs Blog (module write-ups): https://rhinosecuritylabs.com/blog/
- Pacu Module Documentation Wiki: https://github.com/RhinoSecurityLabs/pacu/wiki
- AWS IAM Privilege Escalation Research: https://rhinosecuritylabs.com/aws/aws-privilege-escalation-methods-mitigation/
- Kali Linux Tool Listing: https://www.kali.org/tools/pacu/
