Install principalmapper with Homebrew

Project links

• Homepage
• Package manager page

Commands and aliases

• pmapper

Project history

Principal Mapper was developed by Erik Steringer at NCC Group to identify risks in AWS IAM configurations. It models users and roles as a directed graph, allowing an analyst to detect indirect paths in which one principal can reach another principal that holds the desired permission.

The 1.0 redesign introduced local policy simulation, a new graph-storage format, an interactive query interface and an analysis command while dropping Python 2 and AWS IAM’s remote simulation APIs. Later development added AWS Organizations data, service control policies, permission boundaries, session and resource policies, GraphML output and configurable graph storage.

Adoption history

Principal Mapper is installable as the `principalmapper` Python package, while Homebrew exposes the same project as `principalmapper`. Its workflow fits cloud-security assessments because AWS account data can be gathered once, stored locally and repeatedly queried without making a live policy-simulation call for every question.

The project’s documentation also supports Docker operation and Graphviz-based visualization, broadening its use from an interactive security script to repeatable analysis and reporting workflows.

How it is used

An analyst first creates a graph from an AWS account or organization using AWS-compatible credentials. The stored graph can then be queried for effective access and privilege-escalation paths, analyzed for predefined risks or visualized through Graphviz. Read-only credentials are sufficient for the documented collection workflow.

Why package nerds care

PMapper is notable for turning AWS IAM authorization and privilege-escalation analysis into a local graph problem. Package users get a compact CLI that can gather an account, run path-aware queries, produce machine-readable findings and render privilege relationships without assembling those components manually.

Timeline

• 2019: Principal Mapper originated as an NCC Group cloud-security project by Erik Steringer.
• Version 1.0.0: The project adopted local policy simulation, new graph storage, a REPL and a dedicated analysis module.
• Version 1.1.0: Support expanded to AWS Organizations, SCPs, permission boundaries, session policies, resource policies and GraphML output.

Related projects

• AWS CLI profiles supply credentials using the same profile-oriented workflow recognized by Principal Mapper.
• Graphviz renders PMapper’s IAM and privilege-escalation graphs.

Sources

• https://github.com/nccgroup/PMapper#readme
• https://github.com/nccgroup/PMapper/blob/master/CHANGELOG.md
• https://github.com/nccgroup/PMapper/wiki/Core-Concepts