Socket Integration with DefectDojo

Socket Integration with DefectDojo

Socket (socket.dev) is a software supply chain security platform that analyzes open source dependencies for risky behavior as well as known vulnerabilities. Its alerts cover malware, typosquats, install scripts, known vulnerabilities, and dozens of other categories spanning supply chain risk, quality, maintenance, and license concerns. Socket organizes results into full scans of a repository's dependencies, which can be exported as JSON or read through the Socket API.

Socket Integration with DefectDojo

We added Socket because a CVE database only tells you about packages that someone already reported as vulnerable. The incidents that worried us were packages that were fine last week and shipped an obfuscated install script this week. Socket catches that class of problem. DefectDojo is where those alerts become tracked work: each one lands on the Asset for the repository, with the package URL, alert category, and severity, next to our SAST and SCA results. With DefectDojo Pro, the connector keeps that view current without anyone exporting files.

Why Socket Matters

Attacks on package registries target developers directly, often before any advisory exists. Behavior-based analysis closes part of that gap.

• Socket flags suspicious package behavior such as install scripts and obfuscated code, not only published CVEs.
• Typosquat detection catches dependencies whose names imitate popular packages.
• Alerts are grouped into categories (supply chain risk, quality, maintenance, vulnerability, license), which helps route them to the right reviewer.
• Each alert is tied to a specific package and version, identified by a package URL (PURL).
• Supply chain alerts compete with every other finding for attention. Putting them in the same queue, with the same SLAs, keeps them from being ignored.

Advantages of This Integration

What we gained by routing Socket alerts through DefectDojo:

• Two paths, one set of Findings. The file parser and the DefectDojo Pro connector use the same scan type, Socket - Connectors Import, and the same deduplication identity. A team that starts with file uploads and later enables the connector gets one set of Findings, not two copies.
• Deduplication on Socket's alert key. Findings are matched on the alert key Socket assigns, falling back to a hash of title, severity, and component name when no key matches.
• Useful tags out of the box. Each Finding is tagged with the alert type, category, ecosystem, and package URL, so filtering for every malware alert or every npm Finding takes one click.
• SLA tracking by severity. Socket's critical, high, middle, and low ratings map onto DefectDojo severities, so supply chain alerts fall under the same SLA rules as everything else.
• Ownership and escalation. Findings on a repository's Asset can be assigned, discussed in notes, risk-accepted, or pushed to Jira.
• Air-gapped support. The file parser exists for organizations that cannot grant Socket API credentials, so restricted environments still get the same data.

How This Integration Works

There are two supported ways to bring Socket alerts into DefectDojo.

Option 1: File import (Community Edition and DefectDojo Pro). Export the artifacts of a Socket full scan as JSON, either from the Socket UI or from the Socket API's full-scans endpoint for your organization and full scan ID, authenticated with a Socket API token. The parser accepts a bare JSON array of artifacts, an object that wraps them under artifacts or results, or a single artifact. Then import the file with the Socket - Connectors Import scan type. In the UI, open the Engagement, choose Import Scan Results, select the scan type, and upload the file. To automate it:

curl "https://YOUR_INSTANCE/api/v2/import-scan/" 
  -H "Authorization: Token $DD_API_TOKEN" 
  -F "scan_type=Socket - Connectors Import" 
  -F "file=@socket.json" 
  -F "product_name=checkout-web" 
  -F "engagement_name=Supply Chain" 
  -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 "Socket - Connectors Import" 
  --report-path "./socket.json" 
  --product-name "checkout-web" 
  --engagement-name "Supply Chain" 
  --auto-create-context

Option 2: Socket connector (DefectDojo Pro). The connector uses the Socket API to import alerts on a schedule. You need an organization API token created in the Socket dashboard under Settings, API Tokens, with the repo:list and full-scan read scopes. Then configure:

1. Location: keep the pre-filled https://api.socket.dev/v0.
2. Secret: the Socket API token. It is sent as a bearer token and never logged.
3. Minimum Severity (optional): limits which alerts are imported.

DefectDojo discovers every repository across the organizations the token can access, creates a Record for each, and imports the alerts from that repository's most recent full scan. You map each Record to a DefectDojo Asset.

Data Granularity: What Gets Imported

The table describes the file parser, which mirrors the connector's field mapping.

One Finding is created per alert, so an artifact with several alerts produces several Findings. Alerts that share a key within one file are imported once.

Use Cases

For organizations with many repositories: With DefectDojo Pro, the connector discovers every repository the token can see and keeps alerts current. Security leads get a cross-repository view of malware and typosquat alerts without asking each team to upload files.

In restricted networks: A team that cannot grant API credentials exports full scans and imports them on a schedule. If policy later allows the connector, existing Findings carry over because both paths share a scan type and alert key.

When a malicious package is reported: Filtering on the socket:malware tag shows every Asset where an affected package was flagged, along with the version and owning team, which turns an industry alert into a concrete response list.

For dependency review policy: Teams that require review of new dependencies can use Socket Findings by category, such as install scripts or license alerts, as the queue for that review.

Operational Tips

• Socket's medium rating is spelled middle in its data. The parser handles it, but keep this in mind if you read raw exports.
• Unrecognized severity values import as Info. If you see unexpected Info Findings, check the alert's severity in the raw Socket export.
• Severity is part of the fallback hash. When an alert key is present, matching uses the key, so re-rated alerts still match the existing Finding.
• Use the minimum severity setting on the connector, or minimum_severity on file import, to keep low-priority quality alerts out of the main queue.
• Build saved filters on the category tags (for example category:supplyChainRisk) so supply chain risk alerts reach the right reviewers quickly.
• Pick one primary path per repository. Findings from file imports and the connector deduplicate against each other, but the open-to-mitigated history is easier to read when one path owns each Asset.