Introducing DefectDojo Connectors

The DefectDojo team is always evolving the platform to support the needs of enterprise security professionals. Security vulnerability data ingestion is one of the key requirements that DefectDojo aims to solve. Connectors are the latest way your vulnerability data can be imported into DefectDojo.

What are DefectDojo Connectors?

Connectors allow DefectDojo to interact directly with third-party security tools’ APIs to retrieve information about “vendor-equivalent products” - the vendor resource closest in nature to a DefectDojo Product - so that their findings can be imported automatically to DefectDojo. By setting a schedule for “Discover” (collecting VEPs) and “Synchronize” (collecting and importing Findings) operations, you can ensure that DefectDojo stays up to date with the latest scans from these tools.

How to configure a DefectDojo Connector

The following fields are required when configuring a new Connector for a given vendor tool:

Location: An accessible URL for the tool’s API
Secret: The secret key or token used to authenticate a user to the tool
Label: A human readable label to be associated with this configuration
Discovery schedule: The scheduled time (daily) that discovery should occur
Synchronization schedule: The scheduled time (daily) that synchronization should occur
Auto-mapping: When enabled, new products will be created and mapped automatically. See How does auto-mapping work? below for more details

How do DefectDojo Connectors work?

During “Discover” operations, Connectors create Records that contain the details about vendor-equivalent products, including their names and unique identifiers. Associating these Records with DefectDojo resources is called “mapping”. You can do this manually to ensure that Products are created in a way that’s meaningful to you, or you can enable auto-mapping to have Products created automatically when new Records are created (see the “How does auto-mapping work?” section below for more details).

After Records have been mapped to DefectDojo resources, you can run a “Synchronize” operation to collect Findings from the vendor tool for all mapped Records and [re-]import them into the relevant Test under those Products. As Findings come and go from the vendor tool, their status will be accurately reflected in DefectDojo (for example, if a Finding disappears from the vendor tool, it will be marked inactive in DefectDojo).

How does auto-mapping work?

When auto-mapping is enabled, DefectDojo will automatically create Products based on the name of VEPs contained in new Records. For example, if you have a Product called ProductA in your third-party tool, a Discover operation will create a new Record in DefectDojo containing its metadata, and will automatically create a DefectDojo Product named ProductA, with a Product Type of [Vendor] Connector. It will associate the created Product with the resource ID from the vendor tool in a Mapping so that future Sync operations will know to retrieve Findings for this VEP and where to import them.

About permissions

Users must have the global Maintainer role to:

Create new Connector configurations
View the details of existing Connector configurations
Create new mappings for Records
Otherwise modify the state of Records

Users with the global Reader, Writer, and Maintainer roles can:

See existing Records and their associated DefectDojo Products
See the status of operations (Discover / Synchronize)

Glossary

Concepts

Vendor-equivalent product (VEP)
Description: A resource contained in a vendor tool (might be called something like “application”, “project”, “product”, etc) that maps conceptually to a DefectDojo product.
Record
Description: Metadata about a VEP that is used by Connectors to e.g. determine whether to sync findings, and that a user can use to determine how vendor resources should be managed in DefectDojo. Records contain unique identifiers for VEPs so we can always ensure we are referencing the same underlying resource in the vendor tool.
Mapping
Description: Metadata about the DefectDojo resources with which a Record is associated.

Operations

Discover
Description: Collect information about VEPs from the vendor tool and create Records for them so they can be mapped to DefectDojo resources.
Map
Description: Associate VEPs codified in Records with DefectDojo Products, Engagements, and Tests. When auto-mapping is enabled, Django creates these resources automatically based on the VEP name. When auto-mapping is disabled, the user can create new Products or point to existing ones, with Django creating special Connectors Engagements and Tests where Findings will be imported during Sync operations.
Sync
Description: Collect Findings from the vendor tool for all mapped (GOOD) Records, translate them into DefectDojo format, and re-import them into the relevant Test codified in the Record’s mapping.

Product record states

Unknown("")
- Description: Indicates that nothing was set for the state (empty string). This should not happen, but if it does, it indicates an invalid Record.
Error(ERROR)
- Description: Indicates that there is something wrong with the record itself. This should only be assigned to a record if it is in a state we haven’t accounted for and there is no better existing state to represent it.
New(NEW)
- Description: The state when a vendor-equivalent Product is first identified in the vendor tool but does not have a mapping yet.
Missing(MISSING)
- Description: The state when a mapping exists but the vendor Product with the ID contained in the mapping is not found in the vendor tool
Stale(STALE)
- Description: The state when a mapping exists but the DefectDojo Product/Engagement/Test with the ID contained in the mapping no longer exists
Ignored(IGNORED)
- Description: The state when the user has explicitly chosen not to map this record. It will persist so that it doesn’t get brought in again by future calls to Discover.
Good(GOOD)
- Description: The state when a mapping exists, and the resources in both the vendor tool and DefectDojo exist and are valid

Future Connectors

We are excited to introduce Connectors for Snyk and Semgrep and we are working on adding more to the list. For now, we are prioritizing tools our current customers use and in time we hope to have a large list of Connectors for the more popular security tools in use.

Keep following us to get the latest news on where Connectors are headed!