-
Notifications
You must be signed in to change notification settings - Fork 172
Getting Started
On a host with Python 3 and pip
installed, you can install PMapper with the following shell command:
pip install principalmapper
You will also need to install Graphviz, available for Windows/MacOS/Linux (https://graphviz.org/download/).
To perform analysis with Principal Mapper, we need to create a Graph that represents an AWS account. This requires credentials. For PMapper, this should work similarly if not the same as using the AWS CLI. For example, I've used aws --profile skywalker configure
to set up a profile with access keys for an IAM User. When calling PMapper, all I have to do is use the --profile skywalker
argument.
Note that whichever IAM Role/User you use will need broad read-access to the account. The ReadOnlyAccess
managed policy will suffice.
Once I have my credentials set up, I can use the graph
subcommand which has yet another subcommand, create
, to actually create the Graph.
$ pmapper --profile skywalker graph create
2021-01-27 13:20:26-0800 | Obtaining IAM Users/Roles/Groups/Policies in the account.
2021-01-27 13:20:40-0800 | Sorting users, roles, groups, policies, and their relationships.
2021-01-27 13:20:40-0800 | Obtaining Access Keys data for IAM users
2021-01-27 13:20:45-0800 | Gathering MFA virtual device information
2021-01-27 13:20:45-0800 | Gathering MFA physical device information
2021-01-27 13:20:50-0800 | Determining which principals have administrative privileges
2021-01-27 13:20:52-0800 | Initiating edge checks.
[... Several instances of new edges found]
2021-01-27 13:21:51-0800 | Caching policy for arn:aws:s3:::670903390496-logs
2021-01-27 13:21:51-0800 | Caching policy for arn:aws:s3:::670903390496-secrets
2021-01-27 13:21:52-0800 | Caching policy for arn:aws:s3:::670903390496-source
[...]
Graph Data for Account: 670903390496
# of Nodes: 57 (6 admins)
# of Edges: 52
# of Groups: 2
# of (tracked) Policies: 48
Once the command completes, the Graph data is stored locally on-disk. This data is used for other commands such as query
, analysis
, and visualize
.
With this data, we can run queries to see who has access to what. For example, knowing that there's an object named flag.txt
in the S3 bucket named 670903390496-secrets
, we can run a query to see who in the account can access that object:
$ pmapper --account 670903390496 query --with-resource-policy --resource-owner 670903390496 'who can do s3:GetObject with arn:aws:s3:::670903390496-secrets/flag.txt'
[...]
user/JumpUser CAN call action s3:GetObject for resource arn:aws:s3:::670903390496-secrets THRU role/AssumableReadOnlyRole
user/JumpUser can access via sts:AssumeRole role/AssumableReadOnlyRole
role/AssumableReadOnlyRole IS authorized to call action s3:GetObject for resource arn:aws:s3:::670903390496-secrets/flag.txt
[...]
(Note: We are using --account 670903390496
instead of --profile skywalker
. The difference is that PMapper will just load that account's Graph via the account ID instead of pulling that information by making an API call. It's faster.)
In this query, we see who can call s3:GetObject
for that specific object. The flag --with-resource-policy
tells PMapper to include the S3 bucket policy, and --resource-owner
specifies which account owns that S3 object (necessary for S3 where object ARNs don't have account IDs).
The output of the query tells us that an IAM User named JumpUser
can make that API call. But, it has to assume the role named AssumableReadOnlyRole
in order to do so. You can also follow up with queries for s3:GetObject*
and s3:PutBucketPolicy
to get even better information about resource isolation.
This is how Principal Mapper gives you a more complete picture about AWS IAM configuration. These pivot points between different principals are accounted for when using query
or argquery
.
One more query we'll point out here is a preset query called privesc
:
$ pmapper --account 670903390496 query -s 'preset privesc *'
user/EC2Manager can escalate privileges by accessing the administrative principal role/EC2Role-Admin:
user/EC2Manager can use EC2 to run an instance with an existing instance profile to access role/EC2-Fleet-Manager
role/EC2-Fleet-Manager can use EC2 to run an instance with an existing instance profile to access role/EC2Role-Admin
This query lists all IAM Users/Roles that can gain "admin" privileges, which we define as a principal that can call any action for any resource (as in the AdministratorAccess
managed policy) OR give themselves permission to do so (for example by modifying their own inline policies).
The output of this query is telling us that the user named EC2Manager
can escalate privileges by pivoting to EC2-Fleet-Manager
and then EC2Role-Admin
.
Finally, we can generate an image of the Graph that shows us:
- Which principals are admins (represented with light-blue nodes)
- Which principals can escalate privileges to admin (represented with light-red nodes)
- Other principals (white nodes)
- Which principals can access each other (shown with arrows as in a directed graph)
PMapper uses graphviz
to generate the file, and this visualization feature can be used like so:
$ pmapper --account 670903390496 visualize --filetype svg