# Principal Mapper
Principal Mapper (PMapper) is a script and library for identifying risks in the configuration of AWS Identity and
Access Management (IAM) for an AWS account or an AWS organization. It models the different IAM Users and Roles in an
account as a directed graph, which enables checks for privilege escalation and for alternate paths an attacker could
take to gain access to a resource or action in AWS.
PMapper includes a querying mechanism that uses a local simulation of AWS's authorization behavior.
When running a query to determine if a principal has access to a certain action/resource, PMapper also checks if the
user or role could access other users or roles that have access to that action/resource. This catches scenarios such as
when a user doesn't have permission to read an S3 object, but could launch an EC2 instance that can read the S3 object.
Additional information can be found in [the project wiki](https://github.com/nccgroup/PMapper/wiki).
# Installation
## Requirements
Principal Mapper is built using the `botocore` library and Python 3.5+. Principal Mapper
also requires `pydot` (available on `pip`), and `graphviz` (available on Windows, macOS, and Linux from
https://graphviz.org/ ).
## Installation from Pip
~~~bash
pip install principalmapper
~~~
## Installation From Source Code
Clone the repository:
~~~bash
git clone git@github.com:nccgroup/PMapper.git
~~~
Then install with Pip:
~~~bash
cd PMapper
pip install .
~~~
## Using Docker
_(After cloning from source)_
~~~bash
cd PMapper
docker build -t $TAG .
docker run -it $TAG
~~~
You can use `-e|--env` or `--env-file` to pass the `AWS_*` environment variables for credentials when calling
`docker run ...`, or use `-v` to mount your `~/.aws/` directory and use the `AWS_CONFIG_FILE` and `AWS_SHARED_CREDENTIALS_FILE` environment variables.
The current Dockerfile should put you into a shell with `pmapper -h` ready to go as well as
`graphviz` already installed.
# Usage
See the [Getting Started Page](https://github.com/nccgroup/PMapper/wiki/Getting-Started) in the wiki for more information
on how to use PMapper via command-line. There are also pages with full details on all command-line functions and
the library code.
Here's a quick example:
```bash
# Create a graph for the account, accessed through AWS CLI profile "skywalker"
pmapper --profile skywalker graph create
# [... graph-creation output goes here ...]
# Run a query to see who can make IAM Users
$ pmapper --profile skywalker query 'who can do iam:CreateUser'
# [... query output goes here ...]
# Run a query to see who can launch a big expensive EC2 instance, aside from "admin" users
$ pmapper --account 000000000000 argquery -s --action 'ec2:RunInstances' --condition 'ec2:InstanceType=c6gd.16xlarge'
# [... query output goes here ...]
# Run the privilege escalation preset query, skip reporting current "admin" users
$ pmapper --account 000000000000 query -s 'preset privesc *'
# [... privesc report goes here ...]
# Create an SVG representation of the admins/privescs/inter-principal access
$ pmapper --account 000000000000 visualize --filetype svg
# [... information output goes here, file created ...]
```
Note the use of `--profile`, which should behave the same as the AWS CLI. Also, later calls with
`query`/`argquery`/`visualize` use an `--account` arg which just shortcuts around checking which account to work
with (otherwise PMapper makes an API call to determine that).
Here's an example of the visualization:
And again when using `--only-privesc`:
# Contributions
100% welcome and appreciated. Please coordinate through [issues](https://github.com/nccgroup/PMapper/issues) before
starting and target pull-requests at the current development branch (typically of the form `vX.Y.Z-dev`).
# License
Copyright (c) NCC Group and Erik Steringer 2019. This file is part of Principal Mapper.
Principal Mapper is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Principal Mapper is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with Principal Mapper. If not, see <https://www.gnu.org/licenses/>.
Raw data
{
"_id": null,
"home_page": "https://github.com/0ca/PMapper",
"name": "principalmapper-0ca",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.5",
"maintainer_email": null,
"keywords": "AWS, IAM, Security, PMapper, principalmapper, Principal Mapper, NCC Group",
"author": "Erik Steringer",
"author_email": "erik.steringer@nccgroup.com",
"download_url": "https://files.pythonhosted.org/packages/46/78/773da68e634b1b4d44d529590ccd0f0466e1ec979ec199d9b929b4046836/principalmapper_0ca-1.1.5.tar.gz",
"platform": null,
"description": "# Principal Mapper\n\nPrincipal Mapper (PMapper) is a script and library for identifying risks in the configuration of AWS Identity and \nAccess Management (IAM) for an AWS account or an AWS organization. It models the different IAM Users and Roles in an \naccount as a directed graph, which enables checks for privilege escalation and for alternate paths an attacker could \ntake to gain access to a resource or action in AWS.\n\nPMapper includes a querying mechanism that uses a local simulation of AWS's authorization behavior. \nWhen running a query to determine if a principal has access to a certain action/resource, PMapper also checks if the \nuser or role could access other users or roles that have access to that action/resource. This catches scenarios such as \nwhen a user doesn't have permission to read an S3 object, but could launch an EC2 instance that can read the S3 object.\n\nAdditional information can be found in [the project wiki](https://github.com/nccgroup/PMapper/wiki).\n\n# Installation\n\n## Requirements\n\nPrincipal Mapper is built using the `botocore` library and Python 3.5+. Principal Mapper \nalso requires `pydot` (available on `pip`), and `graphviz` (available on Windows, macOS, and Linux from \nhttps://graphviz.org/ ).\n\n## Installation from Pip\n\n~~~bash\npip install principalmapper\n~~~\n\n## Installation From Source Code\n\nClone the repository:\n\n~~~bash\ngit clone git@github.com:nccgroup/PMapper.git\n~~~\n\nThen install with Pip:\n\n~~~bash\ncd PMapper\npip install .\n~~~\n\n## Using Docker\n\n_(After cloning from source)_\n\n~~~bash\ncd PMapper\ndocker build -t $TAG .\ndocker run -it $TAG\n~~~\n\nYou can use `-e|--env` or `--env-file` to pass the `AWS_*` environment variables for credentials when calling\n`docker run ...`, or use `-v` to mount your `~/.aws/` directory and use the `AWS_CONFIG_FILE` and `AWS_SHARED_CREDENTIALS_FILE` environment variables.\nThe current Dockerfile should put you into a shell with `pmapper -h` ready to go as well as \n`graphviz` already installed. \n\n# Usage\n\nSee the [Getting Started Page](https://github.com/nccgroup/PMapper/wiki/Getting-Started) in the wiki for more information \non how to use PMapper via command-line. There are also pages with full details on all command-line functions and \nthe library code. \n\nHere's a quick example:\n\n```bash\n# Create a graph for the account, accessed through AWS CLI profile \"skywalker\"\npmapper --profile skywalker graph create\n# [... graph-creation output goes here ...]\n\n# Run a query to see who can make IAM Users\n$ pmapper --profile skywalker query 'who can do iam:CreateUser'\n# [... query output goes here ...]\n\n# Run a query to see who can launch a big expensive EC2 instance, aside from \"admin\" users\n$ pmapper --account 000000000000 argquery -s --action 'ec2:RunInstances' --condition 'ec2:InstanceType=c6gd.16xlarge'\n# [... query output goes here ...]\n\n# Run the privilege escalation preset query, skip reporting current \"admin\" users\n$ pmapper --account 000000000000 query -s 'preset privesc *'\n# [... privesc report goes here ...]\n\n# Create an SVG representation of the admins/privescs/inter-principal access\n$ pmapper --account 000000000000 visualize --filetype svg\n# [... information output goes here, file created ...]\n```\n\nNote the use of `--profile`, which should behave the same as the AWS CLI. Also, later calls with \n`query`/`argquery`/`visualize` use an `--account` arg which just shortcuts around checking which account to work \nwith (otherwise PMapper makes an API call to determine that).\n\nHere's an example of the visualization:\n\n\n\nAnd again when using `--only-privesc`:\n\n\n\n# Contributions\n\n100% welcome and appreciated. Please coordinate through [issues](https://github.com/nccgroup/PMapper/issues) before \nstarting and target pull-requests at the current development branch (typically of the form `vX.Y.Z-dev`).\n\n# License\n\n Copyright (c) NCC Group and Erik Steringer 2019. This file is part of Principal Mapper.\n\n Principal Mapper is free software: you can redistribute it and/or modify\n it under the terms of the GNU Affero General Public License as published by\n the Free Software Foundation, either version 3 of the License, or\n (at your option) any later version.\n\n Principal Mapper is distributed in the hope that it will be useful,\n but WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n GNU Affero General Public License for more details.\n\n You should have received a copy of the GNU Affero General Public License\n along with Principal Mapper. If not, see <https://www.gnu.org/licenses/>.\n\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "A patched version of pmapper that runs faster.",
"version": "1.1.5",
"project_urls": {
"Homepage": "https://github.com/0ca/PMapper"
},
"split_keywords": [
"aws",
" iam",
" security",
" pmapper",
" principalmapper",
" principal mapper",
" ncc group"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "288427539979acaa9c90c1e5ac063139d6f0a2f17f4476bfe221599309e6a2fe",
"md5": "4212bfc07638e46e7a68da01a449decd",
"sha256": "066e25b609e5122388eb215ca303f3c70abae10f0ec48bd222617c304199f7c6"
},
"downloads": -1,
"filename": "principalmapper_0ca-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4212bfc07638e46e7a68da01a449decd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.5",
"size": 145565,
"upload_time": "2024-05-31T19:32:13",
"upload_time_iso_8601": "2024-05-31T19:32:13.370092Z",
"url": "https://files.pythonhosted.org/packages/28/84/27539979acaa9c90c1e5ac063139d6f0a2f17f4476bfe221599309e6a2fe/principalmapper_0ca-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4678773da68e634b1b4d44d529590ccd0f0466e1ec979ec199d9b929b4046836",
"md5": "4e532a272345e2687857b57a9acc00bd",
"sha256": "578b463ee4b9ee99be189013a53768e17d5f8aa106a760af1eeb6fb10b4d1883"
},
"downloads": -1,
"filename": "principalmapper_0ca-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "4e532a272345e2687857b57a9acc00bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.5",
"size": 412114,
"upload_time": "2024-05-31T19:32:15",
"upload_time_iso_8601": "2024-05-31T19:32:15.412830Z",
"url": "https://files.pythonhosted.org/packages/46/78/773da68e634b1b4d44d529590ccd0f0466e1ec979ec199d9b929b4046836/principalmapper_0ca-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-31 19:32:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "0ca",
"github_project": "PMapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "principalmapper-0ca"
}
JSON
