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
Enter the appropriate AWS API Endpoint for your region in the Location field: for example, to retrieve results from the
us-east-1region, you would supplyhttps://securityhub.us-east-1.amazonaws.comEnter a valid AWS Access Key in the Access Key field.
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
Enter Burp’s root URL in the Location field: this is the URL where you access the Burp tool.
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.
Checkmarx ONE
DefectDojo's Checkmarx ONE connector calls the Checkmarx API to fetch data.
Connector Mappings
Enter your Tenant Name in the Checkmarx Tenant field. This name should be visible on the Checkmarx ONE login page in the top-right hand corner:
" Tenant: <your tenant name> "
Enter a valid API key. You may need to generate a new one: see Checkmarx API Documentation for details.
Enter your tenant location in the Location field. This URL is formatted as follows:
https://<your-region>.ast.checkmarx.net/. Your Region can be found at the beginning of your Checkmarx URL when using the Checkmarx app. https://ast.checkmarx.net is the primary US server (which has no region prefix).
Dependency-Track
This connector fetches data from a on-premise Dependency-Track instance, via REST API.
Connector Mappings
Enter your local Dependency-Track server URL in the Location field.
Enter a valid API key in the Secret field.
To generate a Dependency-Track API key:
Access Management: Navigate to Administration > Access Management > Teams in the Dependency-Track interface.
Teams Setup: You can either create a new team or select an existing one. Teams allow you to manage API access based on group membership.
Generate API Key: In the selected team's details page, find the "API Keys" section. Click the + button to generate a new API key.
Assign Permissions: In the "Permissions" section of the team's page, click the + button to open the permissions selector. Choose VIEW_PORTFOLIO and VIEW_VULNERABILITY permissions to enable API access to project portfolios and vulnerability details.
Click "Select" to confirm and save these permissions.
For more information, see Dependency-Track Documentation.
Probely
This connector uses the Probely REST API to fetch data.
Connector Mappings
Enter the appropriate API server address in the Location field. (either https://api.us.probely.com/ or https://api.eu.probely.com/ )
Enter a valid API key in the Secret field.
You can find an API key under the User > API Keys menu in Probely.
See Probely documentation for more info.
SemGrep
This connector uses the SemGrep REST API to fetch data.
Connector Mappings
Enter https://semgrep.dev/api/v1/ in the Location field.
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.
SonarQube
The SonarQube Connector can fetch data from either a SonarCloud account or from a local SonarQube instance.
For SonarCloud users:
Enter https://sonarcloud.io/ in the Location field.
Enter a valid API key in the Secret field.
For SonarQube (on-premise) users:
Enter the base url of your SonarQube instance in the Location field: for example
https://my.sonarqube.com/Enter a valid API key in the Secret field. This will need to be a User API Token Type.
API tokens can be found and generated via My Account -> Security -> Generate Token in the SonarQube app. For more information, see SonarQube documentation.
Snyk
The Snyk connector uses the Snyk REST API to fetch data.
Connector Mappings
Enter https://api.snyk.io/rest or https://api.eu.snyk.io/rest (for a regional EU deployment) in the Location field.
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.
Tenable
The Tenable connector uses the Tenable.io REST API to fetch data.
On-premise Tenable Connectors are not available at this time.
Connector Mappings
Enter https://cloud.tenable.com in the Location field.
Enter a valid API key in the Secret field.
See Tenable's API Documentation for more info.