-
Notifications
You must be signed in to change notification settings - Fork 175
Core Concepts
Principal Mapper creates a model of the different IAM Users/Roles (principals) in an AWS account. This model is a directed graph where different principals are represented as vertices/nodes (we say Nodes) and the different pivots where one principal can access and authenticate as another principal are represented as Edges.
A Graph is a collection of Nodes and Edges, stored as a Graph object. We create one Graph per AWS account. Graphs also store data on IAM Groups and IAM Policies within their respective accounts. When PMapper creates a Graph, all of that data is stored on-disk and is available later for querying/analysis/etc.
A Node represents a single IAM User or Role in an AWS account, and is stored as a Node object. We store information on that user's inline and attached IAM Policies, existence of access keys, existence of password, permission boundary, MFA status, tags, IDs, ARN, and more. When you run a query, it finds the corresponding Node(s) and runs authorization checks while accounting for all the above information.
Nodes can be marked as an "admin". PMapper considers an IAM User/Role to be an "admin" if its own effective permissions grant it access to every action and every resource. This is the access granted by the AdministratorAccess managed policy. PMapper also checks for instances where principals can self-assign policies (such as with the IAMFullAccess managed policy), which catches IAM Users/Roles that can grant themselves administrative permissions if they don't have them already.
An Edge represents a way for a Node to authenticate as another Node. These are stored as Edge objects. For example, an IAM User can authenticate as an IAM Role if that role is attached to an EC2 instance profile and that instance profile is attached to a launched EC2 instance. This depends on factors such as whether or not that IAM User is authorized to run EC2 instances, if they can pass the role, and if the role is configured to allow ec2.amazonaws.com to assume it.
PMapper identifies all of these Edges during the Graph-creation process. When you run a query and the current Node is not authorized for the request being queried, PMapper will spider out to other Nodes it can reach with Edges (breadth-first search) to see if the current Node can pivot to other Nodes and make the request.
IAM Groups are stored as Group objects, and Nodes have references to Groups to represent memberships. The permissions granted by Groups are accounted for during querying/etc.
IAM Policies are stored as Policy objects which include a policy name and an ARN. The ARN can be either the ARN of the managed policy that the Policy object represents, or the ARN that the Policy is supposed to be directly attached to (inline policies or resource policies). Note that PMapper only stores policies it sees that are attached to resources or principals, it does not store all managed policies in the account.
AWS Organizations are stored as OrganizationTree objects. As the name implies, PMapper models an organization as a tree. The nodes of this tree are OrganizationNode objects which represent an OU or root OU in the organization. OrganizationNode objects contain a collection of OrganizationAccount objects. Both the OrganizationNode and OrganizationAccount objects have collections of Policy objects representing service control policies (SCPs) which can be accounted for during querying.