Cloudsplaining Integration with DefectDojo

Cloudsplaining Integration with DefectDojo

Cloudsplaining is an open source AWS IAM assessment tool published by Salesforce. It reads the account authorization details that AWS returns for an account (users, groups, roles, customer managed policies, and AWS managed policies) and flags policies that violate least privilege, sorting risky actions into categories such as privilege escalation, data exfiltration, resource exposure, credentials exposure, and infrastructure modification. A scan produces an HTML report and a raw JSON results file, and the JSON file is what DefectDojo imports.

Cloudsplaining Integration with DefectDojo

We run Cloudsplaining against each AWS account because IAM sprawl is the cloud risk that never shows up in a vulnerability scanner, and we import the results into DefectDojo so the policy owners actually get the work. The HTML report is good for a one-time review. DefectDojo is where each risky policy becomes a Finding on the account's Asset, gets a severity based on what kind of access it grants, and stays open until a rescan shows the policy has been tightened.

Why Cloudsplaining Matters

IAM policies accumulate. A wildcard added during an incident or a managed policy attached for convenience can give a role far more reach than it needs, and nobody notices until that role is misused.

• It reviews every policy in an account in one pass, using a single read-only API export rather than live calls per resource.
• It groups risky actions by what an attacker could do with them, which is easier to prioritize than a raw list of permissions.
• It supports an exclusions file, so policies that are permissive by design can be marked as intended.
• It covers customer managed, inline, and AWS managed policies.
• Its own output has no memory between runs. Without a tracking system, there is no way to tell whether a policy was fixed or just dropped out of someone's attention.

Advantages of This Integration

What changes when Cloudsplaining results go through DefectDojo:

• Findings at a workable size. A broad policy can flag thousands of actions. DefectDojo raises one Finding per policy and risk category, listing the actions in the description, so the Test stays readable.
• Severity that reflects risk. Privilege escalation imports as Critical; data exfiltration, resource exposure, and credentials exposure as High; service wildcards as Medium; infrastructure modification as Low. SLAs follow from that.
• Stable deduplication. Findings are hashed on the risk category and the policy name, so the same problem in the same policy is recognized across scans.
• Exclusions stay out of the queue. Policies Cloudsplaining marks as excluded are skipped on import, so intended access does not come back as work.
• Tracked remediation. Reimporting into the same Test mitigates findings for policies that were narrowed, and adds anything newly risky.
• Ownership and reporting. Each account maps to an Asset, so findings can be assigned, risk-accepted with an expiration date, pushed to Jira, and reported next to other cloud and application findings.

How This Integration Works

DefectDojo imports Cloudsplaining output with the Cloudsplaining Scan scan type.

1. Export account authorization details and scan them. With read-only IAM access to the account:

aws iam get-account-authorization-details > account.json
cloudsplaining scan --input-file account.json --output ./cloudsplaining-results/

Add --exclusions-file exclusions.yml to apply your exclusions. Alongside the HTML report (iam-report-account.html), Cloudsplaining writes two JSON data files named after the input file: iam-results-account.json and iam-findings-account.json. Import the iam-results file. The parser reads its customer_managed_policies, inline_policies, and aws_managed_policies sections.

2. Import the JSON. In the UI, open the Engagement, choose Import Scan Results, select Cloudsplaining Scan, and upload the file. To automate it, use the import 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=Cloudsplaining Scan" 
  -F "file=@iam-results-account.json" 
  -F "product_name=aws-prod-account" 
  -F "engagement_name=IAM Review" 
  -F "auto_create_context=true"

DefectDojo Pro users can do the same from a scheduled job with Universal Importer:

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

3. Reimport on a schedule. Run the export and scan weekly or after IAM changes, and send each result to /api/v2/reimport-scan/ against the same Test so the history of each policy stays in one place.

Data Granularity: What Gets Imported

The parser does not create Findings for IAM principals (users, groups, roles) separately. Risk is attached to the policy, which is where the fix is made.

Use Cases

Quarterly access review: A security team scans every account before an access review and imports each into its own Asset. Reviewers start from a list of Critical privilege escalation findings rather than reading policies one by one.

After an acquisition or account merge: A newly onboarded AWS account is scanned and imported on day one. The findings show which inherited policies grant broad access, and the account owners get assigned work with SLAs from the start.

Validating least-privilege projects: A platform team replaces broad managed policies with scoped ones. Reimporting after each change shows findings being mitigated, which gives the project a measurable result.

Documenting accepted access: Break-glass roles and administrator policies are permissive on purpose. Adding them to the Cloudsplaining exclusions file keeps them out of imports, while risk acceptance in DefectDojo records any remaining exceptions with a reason and an expiration date.

Operational Tips

• Import the iam-results JSON, not the HTML report. The parser expects the policy sections of the results file.
• Keep one Asset per AWS account and one Test per account scan stream, and reimport into it so policy fixes close findings automatically.
• Policy names are the component and part of the dedupe hash. Renaming a policy will look like a fix plus a new finding.
• Maintain the exclusions file in source control. Anything excluded there never reaches DefectDojo, so review it as carefully as the policies themselves.
• Use minimum_severity=Medium on import if infrastructure modification findings are too noisy for your first rollout.
• Tag imports with the account ID or environment (for example tags=prod,123456789012) to filter IAM findings across many accounts.