CloudFormation Guard Integration with DefectDojo

CloudFormation Guard Integration with DefectDojo

AWS CloudFormation Guard (cfn-guard) is an open source policy-as-code tool from AWS. It evaluates CloudFormation templates, Kubernetes manifests, and other structured JSON or YAML files against rules written in its own domain-specific language, and reports which rules each file passed, failed, or did not apply to. Results can be written as JSON with --output-format json, which is the format DefectDojo imports.

CloudFormation Guard Integration with DefectDojo

We write cfn-guard rules for the things our cloud standards say every template must do, and we import the results into DefectDojo so a failed rule becomes a tracked Finding rather than a red line in a build log. Each failure lands on the Asset that owns the template, carries the rule name, the resource path, and the template line, and stays open until a later scan shows the template now complies. That gives our platform team a running record of which stacks still break which rules, and which teams fixed them.

Why CloudFormation Guard Matters

Infrastructure as code is where cloud misconfigurations are cheapest to fix, because nothing has been deployed yet. cfn-guard checks templates at that point.

• Rules are written by your own team, so they encode your organization's actual standards (encryption required, no open ingress, mandatory tags) rather than a vendor's defaults.
• It distinguishes existence checks (a property must be present) from comparisons (a value must not equal something), and reports the value it actually found.
• It runs locally or in CI against the same files that get deployed, with no cloud credentials needed.
• It reports positions inside the template, so a failure points at the property to change.
• By itself it gives a pass or fail per run. There is no history of which failures are new and which have been ignored for months.

Advantages of This Integration

What running cfn-guard through DefectDojo adds:

• One Finding per failing clause. The parser reads both Unary (existence) and Binary (comparison) checks, so a report that mixes them is imported in full.
• Precise location. The template name becomes the file path, the failing resource path becomes the component, and the line number is recovered from the position cfn-guard embeds in its messages.
• Stable deduplication. Findings are hashed on rule name, template file, and resource path, so the same rule failing on the same resource is recognized as one Finding across repeated scans.
• A remediation lifecycle. Reimporting a new report into the same Test closes findings for templates that now comply and adds any new failures.
• Your own grading. cfn-guard has no severity, so DefectDojo imports every failure as Medium. DefectDojo Pro's Rules Engine can then key off the rule name to raise or lower severity based on what each rule protects.
• Same workflow as other findings. Policy failures can be assigned, risk-accepted with an expiration date, pushed to Jira, and reported alongside SAST and cloud posture results for the same Asset.

How This Integration Works

DefectDojo imports cfn-guard results with the CloudFormation Guard Scan scan type. It accepts a single JSON report or a JSON array of reports (one per validated file).

1. Produce a JSON report. Run cfn-guard against your template and rules:

cfn-guard validate --data template.yaml --rules rules.guard --output-format json > cfn-guard-report.json

Only rules listed under not_compliant become Findings. The compliant and not_applicable lists are ignored. A failing rule that carries no clause detail is still imported as a single Finding.

2. Import it. In the UI, open the Engagement, choose Import Scan Results, select CloudFormation Guard Scan, and upload the file. For automation, 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=CloudFormation Guard Scan" 
  -F "file=@cfn-guard-report.json" 
  -F "product_name=network-stack" 
  -F "engagement_name=IaC Policy" 
  -F "auto_create_context=true"

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

universal-importer import 
  --defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" 
  --scan-type "CloudFormation Guard Scan" 
  --report-path "./cfn-guard-report.json" 
  --product-name "network-stack" 
  --engagement-name "IaC Policy" 
  --auto-create-context

3. Reimport on each change. Send later reports to /api/v2/reimport-scan/ for the same Test so templates that were fixed have their findings mitigated, and the Test always reflects the current state of the repository.

Data Granularity: What Gets Imported

The description keeps the value cfn-guard actually found on the resource, so a reviewer can see the offending setting without opening the template.

Use Cases

In a pull request pipeline: A pipeline runs cfn-guard on every changed template and reimports the report into a Test per repository. Reviewers see which rules the change broke, and a merge gate can check the DefectDojo API for new open findings on that Test.

Rolling out a new standard: A platform team adds a rule requiring encryption on every storage resource. Importing the first scan across all repositories shows how many templates fail it and which teams own them, and later reimports show the backlog shrinking.

Tracking exceptions: Some resources legitimately break a rule, such as a bucket that hosts a public website. Risk-accepting that Finding with a reason and an expiration date records the exception in one place and brings it back for review later.

Reporting to auditors: Policy-as-code failures carry discovery dates and remediation history in DefectDojo, so a team can show when a control was introduced and how quickly templates were brought into line.

Operational Tips

• Give rules descriptive, stable names. The rule name is the vulnerability ID from the tool and part of the dedupe hash, so renaming a rule makes old and new findings look different.
• Write a custom_message for each rule. It is the first line of the Finding description and the clearest explanation an engineer will see.
• Because every finding arrives as Medium, plan severity in DefectDojo. In DefectDojo Pro, use the Rules Engine to match on rule name; in Community Edition, adjust severity on the Finding or group rules into separate Tests.
• Validate one template per report, or use consistent report names, since the report name becomes the file path used in deduplication.
• Use one Test per repository or stack and reimport into it, so fixed templates are mitigated instead of piling up as duplicate Tests.
• Tag imports with the branch or stack name (for example tags=main,network) to filter policy failures by environment.