Tool-Specific API Reference

Our list of supported Connector tools, and how to set them up with DefectDojo

Updated over a week ago

When setting up a Connector for a supported tool, you'll need to give DefectDojo specific information related to the tool's API. At a base level, you'll need:

  • Location - a field which generally refers to your tool's URL in your network,

  • Secret - generally an API key.

Some tools will require additional API-related fields beyond Location and Secret. They may also require you to make changes on their side to accommodate an incoming Connector from DefectDojo.

Each tool has different API requirements, and this guide is intended to help you set up the tool's API so that DefectDojo can connect.

Whenever possible, we recommend creating a new 'DefectDojo Bot' account within your Security Tool which will only be used by the Connector. This will help you better differentiate between actions manually taken by your team, and automated actions taken by the Connector.

Supported Connectors

AWS Security Hub

The AWS Security Hub connector uses an AWS access key to interact with the Security Hub APIs.

Prerequisites

Rather than use the AWS access key from a team member, we recommend creating an IAM User in your AWS account specifically for DefectDojo, with that user's permissions limited to those necessary for interacting with Security Hub.

AWS's "AWSSecurityHubReadOnlyAccess policy" provides the required level of access for a connector. If you would like to write a custom policy for a Connector, you will need to include the following permissions:

A working policy definition might look like the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AWSSecurityHubConnectorPerms",
"Effect": "Allow",
"Action": [
"securityhub:DescribeHub",
"securityhub:GetFindingAggregator",
"securityhub:GetFindings",
"securityhub:ListFindingAggregators"
],
"Resource": "*"
}
]
}

Please note: we may need to use additional API actions in the future to provide the best possible experience, which will require updates to this policy.

Once you have created your IAM user and assigned it the necessary permissions using an appropriate policy/role, you will need to generate an access key, which you can then use to create a Connector.

Connector Mappings

  1. Enter the appropriate AWS API Endpoint for your region in the Location field: for example, to retrieve results from the us-east-1 region, you would supply

    https://securityhub.us-east-1.amazonaws.com

  2. Enter a valid AWS Access Key in the Access Key field.

  3. Enter a matching Secret Key in the Secret Key field.

DefectDojo can pull Findings from more than one region using Security Hub's cross-region aggregation feature. If cross-region aggregation is enabled, you should supply the API endpoint for your "Aggregation Region". Additional linked regions will have ProductRecords created for them in DefectDojo based on your AWS account ID and the region name.

BurpSuite

DefectDojo’s Burp connector calls Burp’s GraphQL API to fetch data.

Prerequisites

Before you can set up this connector, you will need an API key from a Burp Service Account. Burp user accounts don’t have API keys by default, so you may need to create a new user specifically for this purpose.

See Burp Documentation for a guide on setting up a Service Account user with an API key.

Connector Mappings

  1. Enter Burp’s root URL in the Location field: this is the URL where you access the Burp tool.

  2. Enter a valid API Key in the Secret field. This is the API key associated with your Burp Service account.

See the official Burp documentation for more information on the Burp API.

SemGrep

This connector uses the SemGrep REST API to fetch data.

Connector Mappings

Enter https://semgrep.dev/api/v1/ in the Location field.

  1. Enter a valid API key in the Secret field. You can find this on the Tokens page:

    "Settings" in the left navbar > Tokens > Create new token (https://semgrep.dev/orgs/-/settings/tokens)

See SemGrep documentation for more info.

Snyk

The Snyk connector uses the Snyk REST API to fetch data.

Connector Mappings

  1. Enter https://api.snyk.io/rest or https://api.eu.snyk.io/rest (for a regional EU deployment) in the Location field.

  2. Enter a valid API key in the Secret field. API Tokens are found on a user's Account Settings page in Snyk.

See the Snyk API documentation for more info.

Did this answer your question?