Skip to content

Getting Started

Jump to bottom
ncc-erik-steringer edited this page Mar 29, 2021 · 3 revisions

Installation

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/).

Graphing an AWS Account

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.

Running Queries

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.

Visualizing

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
Clone this wiki locally