PMapper Integration with DefectDojo

PMapper Integration with DefectDojo

PMapper (Principal Mapper) is an open source tool from NCC Group for analyzing AWS Identity and Access Management. It collects the IAM users, roles, groups, and policies in an AWS account, builds a graph of which principals can act as or gain access to which others, and reports risks found in that graph, such as principals that can escalate to administrator. Its analysis command can write the results as JSON, which DefectDojo imports.

PMapper Integration with DefectDojo

IAM policies are easy to read one at a time and hard to reason about together. A build user that can update a Lambda function running as a deploy role is effectively that deploy role, and no single policy says so. We run PMapper because it follows those chains for us. Importing its analysis into DefectDojo turns each escalation path into a Finding on the account's Asset, with PMapper's impact and recommendation attached, an owner, an SLA, and a status that changes when the next analysis shows the path is gone.

Why PMapper Matters

Effective access in AWS is often broader than what anyone wrote down or intended. PMapper looks for that gap between intended and effective access.

• It models transitive access, such as passing a role to a service or modifying a resource that runs with a more privileged role.
• It identifies principals with administrator-equivalent access, including ones that get there indirectly.
• It runs offline against a stored graph once the graph is built, so analysis is repeatable and fast.
• Its findings explain the impact and recommend a fix, which shortens the conversation with the account owner.
• PMapper reports a moment in time. Without tracking, nobody knows whether last quarter's escalation path was ever closed.

Advantages of This Integration

What changed when PMapper results went into DefectDojo:

• Findings stay tied to the account. The analysed account ID becomes the component and is appended to the title, so findings from several accounts stay distinguishable on one Asset.
• Impact and mitigation are kept separate. PMapper's impact and recommendation map to the Finding's Impact and Mitigation fields rather than being buried in the description.
• PMapper's own severity is respected. Critical, High, Medium, Low, and Info are mapped directly; an unrecognized severity falls back to Medium so it is neither hidden nor inflated.
• Rescans close what was fixed. Deduplication uses the finding title and the account, so reimporting a fresh analysis into the same Test mitigates escalation paths that disappeared and adds new ones.
• A record for auditors. Each escalation path keeps its discovery date, owner, notes, and closure date, which is the evidence an access review or audit asks for.
• IAM risk in the same queue as everything else. Findings can be assigned to the account owner, risk-accepted with an expiry for approved exceptions, or pushed to Jira.

How This Integration Works

DefectDojo imports PMapper output with the PMapper Scan scan type.

1. Build the graph and run the analysis. With AWS credentials for the target account available to PMapper:

pmapper --account 111122223333 graph create
pmapper --account 111122223333 analysis --output-type json > pmapper.json

The parser accepts a single report object, with the account, the analysis time, the source, and a list of findings, or a JSON array of such reports. That means a team that analyses several accounts can combine the reports into one array and import them in a single file, with each finding still carrying its own account ID. Most teams still prefer one file per account so each account maps cleanly to its own Asset.

2. Import the file. In the UI, open the Engagement, choose Import Scan Results, select PMapper Scan, and upload the file. Through the API, available in Community Edition and DefectDojo Pro:

curl "https://YOUR_INSTANCE/api/v2/import-scan/" 
  -H "Authorization: Token $DD_API_TOKEN" 
  -F "scan_type=PMapper Scan" 
  -F "file=@pmapper.json" 
  -F "product_name=aws-prod-account" 
  -F "engagement_name=IAM Review" 
  -F "auto_create_context=true"

DefectDojo Pro users can run the same import with Universal Importer:

universal-importer import 
  --defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" 
  --scan-type "PMapper Scan" 
  --report-path "./pmapper.json" 
  --product-name "aws-prod-account" 
  --engagement-name "IAM Review" 
  --auto-create-context

3. Rebuild and reimport on a schedule. IAM changes constantly, so recreate the graph before each analysis and send the result to /api/v2/reimport-scan/ for the same Test.

Data Granularity: What Gets Imported

Use Cases

For quarterly access reviews: A cloud security team rebuilds PMapper graphs for every production account, reimports each analysis, and hands account owners a DefectDojo report of open escalation paths with PMapper's recommendation on each one.

After an IAM refactor: A platform team splits an overprivileged deploy role into narrower roles, reruns the analysis, and reimports. The privilege escalation Finding for the old path is mitigated, which documents that the change worked.

Across an AWS organization: Each account's report goes to its own Asset under one Organization, so leadership sees which accounts carry administrator-equivalent paths and how that changes over time.

During incident response: When a credential is suspected to be compromised, responders check that principal's open PMapper findings in DefectDojo to see what else it could reach.

Operational Tips

• Recreate the graph before every analysis. PMapper analyses the stored graph, so an old graph produces an old answer.
• Use one Asset per AWS account, or at least one Test per account. The account is part of the hash, but separate Tests keep reimport results easy to read.
• A PMapper finding can name several principals. Because only the title and account are hashed, a change in the principals listed does not create a new Finding, so read the description after each reimport.
• Risk-accept intended administrator access, such as a break-glass role, with a reason and an expiration date so it is reviewed again.
• Use SLA configuration to set deadlines by severity, then push High findings to Jira for the team that owns the account.
• Tag findings with the account alias or environment (for example tags=prod,payments) to filter across accounts in metrics.