GitGuardian Ggshield Integration with DefectDojo

GitGuardian Ggshield Integration with DefectDojo

GitGuardian is a secrets detection company whose platform finds credentials such as API keys, tokens, and passwords exposed in source code, Git history, and other sources. ggshield is GitGuardian's open source command-line client: it sends content to the GitGuardian detection API and reports any secrets found, and teams run it as a pre-commit or pre-push hook, in CI, or against a range of commits. ggshield can write its results as JSON, which DefectDojo imports. DefectDojo Pro can also pull open secret incidents straight from the GitGuardian platform with a connector.

GitGuardian Ggshield Integration with DefectDojo

We run ggshield in CI because a secret caught in a pipeline is a rotation, while a secret caught after a breach is an incident. ggshield is good at the catching part. What we needed was a place where each leaked credential has an owner and a deadline, next to everything else we know about the repository. Importing ggshield results into DefectDojo gives each detected secret a High severity Finding on the right Asset, with the commit, file, and author attached, and with DefectDojo Pro, the GitGuardian connector keeps that list in step with incidents resolved in GitGuardian.

Why GitGuardian Ggshield Matters

Leaked credentials are among the most direct routes into cloud accounts and internal systems, and Git history keeps them long after the line is deleted.

• ggshield scans commits, not just the current tree, so a secret removed in a later commit is still found in the history.
• It runs at several points in the workflow: on a developer machine before commit or push, in CI, or across a commit range during an investigation.
• Detection runs on GitGuardian's service, so the CLI stays light while detectors are maintained centrally.
• Its output is per scan. Knowing whether a given secret was rotated needs tracking outside the scan itself.

Advantages of This Integration

What we gained by routing ggshield results through DefectDojo:

• Every secret becomes tracked work. Each occurrence imports as a High severity finding with CWE-798 (Use of Hard-coded Credentials), so secrets fall under one SLA rule and can be assigned and pushed to Jira.
• Commit context for the investigation. The description records the commit hash, commit date, author name and email, file, and secret type, which is what the responder needs to find and rotate the credential.
• No raw secret by default. ggshield masks most of each match in its JSON, and the parser stores that masked match, so the full credential does not end up in DefectDojo.
• Within-report deduplication. Repeated occurrences with the same title, match, and lines collapse into one finding.
• Status sync with DefectDojo Pro. The GitGuardian connector imports only open incidents and mitigates findings for incidents resolved or ignored in GitGuardian on the next sync.

How This Integration Works

There are two ways to get GitGuardian results into DefectDojo.

Option 1: ggshield JSON import (Community Edition and DefectDojo Pro). DefectDojo imports ggshield output with the Ggshield Scan scan type. The parser expects the commit-based report layout: a scans list with one entry per commit, including the commit's author, email, and date. A commit-range scan produces that layout:

export GITGUARDIAN_API_KEY="$GG_TOKEN"
ggshield secret scan commit-range origin/main..HEAD --json --output ggshield-report.json

Import the file in the UI (Engagement, Import Scan Results, Ggshield Scan) or through the API:

curl "https://YOUR_INSTANCE/api/v2/import-scan/" \
  -H "Authorization: Token $DD_API_TOKEN" \
  -F "scan_type=Ggshield Scan" \
  -F "file=@ggshield-report.json" \
  -F "product_name=payments-api" \
  -F "engagement_name=Secrets" \
  -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 "Ggshield Scan" \
  --report-path "./ggshield-report.json" \
  --product-name "payments-api" \
  --engagement-name "Secrets" \
  --auto-create-context

Option 2: GitGuardian connector (DefectDojo Pro). The connector uses the GitGuardian REST API to import secret incidents from your GitGuardian workspace. Create a Service Account token in the GitGuardian dashboard under API with the incidents:read and sources:read scopes. In the connector, enter https://api.gitguardian.com (or your self-hosted instance's API URL) as the Location and the token as the Secret. DefectDojo creates a Record for each monitored source (repository or perimeter) that has open incidents and imports each open incident (status TRIGGERED or ASSIGNED) as a finding. A secret GitGuardian has confirmed as valid is imported as verified. The connector imports incident metadata only, such as detector, severity, validity, status, and a link back to GitGuardian. It never retrieves or stores the secret value.

Data Granularity: What Gets Imported

The table describes the Ggshield Scan file parser.

GitGuardian's validity result in the JSON is not mapped by the file parser. If you need validity to drive priority, the DefectDojo Pro connector carries it.

Use Cases

In a CI/CD pipeline: Each pull request runs a commit-range scan over its new commits and imports the result. A detected secret becomes a High finding with the commit and author attached, and the security team can start rotation before the branch merges.

Investigating a repository's history: When a team inherits an older repository, scanning a long commit range and importing the result gives a list of every historical secret to triage, rotate, or mark as test data.

Organization-wide incident tracking with DefectDojo Pro: Teams already using the GitGuardian platform enable the connector, so open incidents across all monitored repositories appear on their Assets and close in DefectDojo when they are resolved in GitGuardian.

Audit evidence: Each finding records when a secret was found and when it was closed, which answers an auditor's question about how quickly exposed credentials were handled.

Operational Tips

• Use a commit-based scan such as commit-range for imports. The parser reads commit details from each entry in the report's scans list.
• Don't add --show-secrets to scans you plan to import. The default masked match keeps the full credential out of DefectDojo.
• The description includes the commit author's name and email. Restrict access to the Asset accordingly if that matters in your organization.
• Severity is fixed at High. Raise confirmed production credentials to Critical during triage if your SLA policy needs a faster track for them.
• Removing the secret from the code doesn't fix it, since it stays in history. Rotate first, record it in the finding's notes, then close the finding.
• On DefectDojo Pro, prefer the connector for ongoing tracking and use file imports for one-off scans of repositories GitGuardian does not monitor.