Legitify Integration with DefectDojo

Legitify Integration with DefectDojo

Legitify is an open source command-line tool from Legit Security that detects misconfigurations and security risks in source code management platforms. It supports GitHub (cloud and Enterprise Server) and GitLab (cloud and self-managed), and it evaluates settings across namespaces such as organizations, members, repositories, and Actions against a set of security policies: branch protection, required code review, workflow permissions, two-factor enforcement, and similar controls. Legitify is licensed under Apache 2.0 and can output its results as JSON, which DefectDojo imports.

Legitify Integration with DefectDojo

Our source code platform is part of our attack surface, and Legitify is how we check it: who can approve their own pull requests, which repositories lack branch protection, whether workflows can approve merges. Running it once produces a long list. Running it through DefectDojo turns each failed policy into a Finding with the affected repositories or organizations attached, the threat explained, and Legitify's remediation steps ready to follow. The platform team gets an owner and SLA for each setting to fix, and the next scan shows which ones they fixed.

Why Legitify Matters

Software supply chain attacks often start in the SCM, not the code. A repository without required reviews or a workflow with excessive permissions can let a single compromised account push code to production.

• Legitify checks the controls that protect code before it is built: reviews, branch protection, two-factor enforcement, and Actions permissions.
• It covers both GitHub and GitLab, which matters for organizations running both.
• Each policy comes with a plain-language threat description and step-by-step remediation.
• It is free and open source, so the checks themselves can be inspected.
• These settings drift. A one-time audit fixes today's problems but says nothing about next month's new repository.

Advantages of This Integration

What we gain by sending Legitify results through DefectDojo:

• One Finding per failed policy. The parser creates a Finding only for policies with at least one failed violation, and attaches every failing entity's link as an endpoint.
• Ready-made remediation. Legitify's remediation steps become the Finding's mitigation and its threat text becomes the impact, so the engineer assigned the work has instructions in hand.
• Drift detection with reimport. Reimporting into the same Test mitigates policies that now pass and adds any that newly fail.
• Severity-based SLAs. Legitify severities map to DefectDojo's scale, so a high-severity SCM misconfiguration gets the same deadline as a high-severity code flaw.
• Visibility for leadership. SCM posture findings appear in DefectDojo metrics next to application and infrastructure findings, which makes supply chain risk reportable.

How This Integration Works

DefectDojo imports Legitify results with the Legitify Scan scan type. It accepts Legitify's JSON output in the flattened scheme, which is Legitify's default.

1. Run Legitify with JSON output. Provide a token for your SCM in the SCM_TOKEN environment variable (Legitify's documentation lists the required scopes), then run:

legitify analyze --org my-org \
  --output-format json \
  --output-scheme flattened \
  --output-file legitify.json

For GitLab, add --scm gitlab. You can limit the run with --namespace, for example --namespace organization,repository.

The flattened JSON has a content object keyed by fully qualified policy name. Each entry holds the policy's metadata (policyInfo) and a list of violations, one per evaluated entity, each with a status and a link to the entity. The parser reads exactly that structure, so stick to the flattened scheme; the grouped output schemes won't map correctly.

2. Import the file. In the UI, open the Engagement, choose Import Scan Results, select Legitify Scan, and upload the JSON. From a scheduled job using the API (Community Edition and DefectDojo Pro):

curl "https://YOUR_INSTANCE/api/v2/import-scan/" \
  -H "Authorization: Token $DD_API_TOKEN" \
  -F "scan_type=Legitify Scan" \
  -F "file=@legitify.json" \
  -F "product_name=github-org" \
  -F "engagement_name=SCM Posture" \
  -F "auto_create_context=true"

DefectDojo Pro users can use Universal Importer:

universal-importer import \
  --defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
  --scan-type "Legitify Scan" \
  --report-path "./legitify.json" \
  --product-name "github-org" \
  --engagement-name "SCM Posture" \
  --auto-create-context

3. Reimport on a schedule. Run Legitify weekly or nightly and reimport into the same Test with /api/v2/reimport-scan/, so policies that start passing are closed and new failures appear.

Data Granularity: What Gets Imported

Violations with a status other than FAILED (for example, skipped or passed checks) are ignored. A policy with no failed violations produces no Finding.

Use Cases

For continuous SCM posture monitoring: A platform team runs Legitify nightly against the GitHub organization and reimports into one Test. When someone creates a repository without branch protection, a Finding appears the next morning with the repository linked and the fix described.

During a supply chain security initiative: A security lead imports the first Legitify run to baseline the organization, assigns each failed policy to an owner, and tracks closure against SLAs. Metrics show the backlog shrinking week over week.

For organizations with GitHub and GitLab: Teams run Legitify against both platforms and import each into its own Asset, so posture can be compared and reported separately while following one process.

For audits: SOC 2 or ISO 27001 reviews often ask how code changes are controlled. DefectDojo shows when a control gap was found and when it was closed, with the policy text attached.

Operational Tips

• Remember that deduplication includes endpoints. When a new repository starts failing an existing policy, the endpoint set changes and the policy shows up as a new Finding while the old one is mitigated on reimport. Expect some churn while the organization is changing quickly.
• Give each SCM organization its own Asset. Policies are per organization and mixing two in one Test makes reimport mitigate findings from whichever is missing.
• Use a dedicated token with only the scopes Legitify's documentation lists for the checks you run, and keep it in your CI secret store.
• Severity defaults to Low when Legitify gives none, so review Low findings rather than filtering them out on the first import.
• Risk-accept policies that don't apply to your workflow (for example, a review requirement on a docs-only repository) with an expiration date, instead of excluding the namespace entirely.
• Tag imports by platform (for example tags=github or tags=gitlab) so dashboards can split SCM posture by source.