Connector Field Mappings

Note: Connectors are a DefectDojo Pro-only feature.

Each Connector decides how its tool’s data becomes a DefectDojo Finding: which value becomes the Title, which becomes the Description, and so on. Those decisions are built into the Connector, and until now disagreeing with one meant opening a support request and waiting for a release.

Connector field mappings let you make that change yourself. You define derivations that are applied to every incoming finding, for one scan type, before it becomes a Finding.

What field mappings can and cannot change#

This is the first thing to understand, because it decides whether mappings are the right tool for your problem at all.

A Connector sends DefectDojo the finding it has already assembled — Title, Description, Severity, Component Name, and the rest of the DefectDojo finding fields. It does not send the original vendor record alongside it.

So field mappings can:

• Rearrange — put a value that currently lands in one field into another.
• Combine — build one field out of several, such as a composite identifier.
• Normalise — strip a varying substring out of a field.

Field mappings cannot surface a value the Connector never sent. If the data you want is in your tool’s API response but not in any DefectDojo field, no mapping can reach it; that requires a change to the Connector itself. Contact for those.

Mappings are set per scan type#

A mapping applies to a scan type, not to an individual Connector record. Every record that imports under that scan type gets the same mappings.

This is deliberate. Deduplication settings are themselves defined per scan type, so if two records of the same scan type could carry different mappings, there would be no single answer to what that scan type’s findings are matched on.

How a mapping is written#

A mapping has three parts:

For example, this builds a composite identifier out of four fields the Connector already sends:

{
  "target_field": "unique_id_from_tool",
  "expression": "{vuln_id_from_tool}|{component_name}|{component_version}|{file_path}"
}

And this removes a scan date that the tool folds into every title, so that the same issue does not look like a new one on each sync:

{
  "target_field": "title",
  "expression": "{title}",
  "strip_pattern": " \\(scanned \\d{4}-\\d{2}-\\d{2}\\)"
}

Four behaviours are worth knowing before you write one:

• Every mapping reads the original finding, never the output of another mapping. Mappings cannot feed into each other, so the result never depends on the order they were saved in. Two mappings may not target the same field.
• A missing field becomes empty rather than an error. Connectors omit fields that have no value, and which fields are missing varies from finding to finding, so a mapping that reads an absent field produces an empty string there. It does not fail the sync.
• Fields holding several values are joined with commas — vulnerability IDs, for instance — rather than rendered as a list.
• A result is truncated at 4000 characters.

Identity-relevant edits versus presentation-only edits#

Some fields take part in matching findings against each other and some do not, so DefectDojo classifies every mapping change before applying it:

• A presentation-only change touches a field your deduplication configuration does not hash — mitigation, references, impact and similar. It applies with no further consequences.
• An identity-relevant change touches a field that is hashed, so it changes what a finding’s identity is built from. Remapping Title, Severity or Description falls here by default, as does writing unique_id_from_tool.

Which fields are identity-relevant follows your deduplication settings for that scan type under Enterprise Settings, not a fixed list, so it tracks any change you make there.

Do not map a vulnerability ID straight into unique_id_from_tool#

Some Connectors send vuln_id_from_tool but no per-finding identifier, and promoting the one to the other looks like an easy fix. It is not, and it will lose data.

vuln_id_from_tool holds the vulnerability’s identifier — a CVE or a rule ID — which is shared by every finding of that vulnerability. Using it as the finding’s unique identifier tells DefectDojo that a hundred separate occurrences are all one finding, and they will collapse into one. That is worse than having no identifier at all.

Build a composite instead, as in the example above. A vulnerability ID together with the component, its version and the file path is specific to one occurrence, which is what an identifier has to be.

Working with mappings in DefectDojo#

Mappings live under Connect > Field Mappings. The whole area requires the maintainer global role for Connectors — viewing included, because a mapping describes how your findings are identified.

The list shows every scan type that has mappings, how many it has, which fields they write, and two counters worth reading together: Revision is how many times the mappings have changed, and Identity Generation is how many of those changes moved what findings are identified by.

Add mappings to a scan type#

Choose New Field Mapping and pick a scan type. Only scan types without a configuration are offered — if the one you want is missing, it already has mappings, so edit those instead.

The configuration is created empty and opens straight into the editor. An empty configuration changes nothing about an import, so there is no identity decision to make yet.

Edit the mappings#

Each row is one mapping: the Target Field to write, the Expression to write into it, and an optional Strip Pattern. The target list is the set of finding fields DefectDojo will accept, so you cannot select one that would be rejected on save.

Fields that reach identity for this scan type are tagged identity as you select them. That tag follows your deduplication settings for the scan type, so it reflects what this instance actually hashes rather than a fixed list. Two rows may not target the same field, and the editor will say so before you continue.

Review the impact, then save#

Review Impact classifies the change without applying it, and this is the step the screen exists for. It tells you whether the edit is presentation-only or identity-relevant, which fields are moving, and how many findings are already stored under this scan type.

An identity-relevant edit cannot be saved until you tick the box confirming you understand it opens a transition window. A presentation-only edit saves without that step — the confirmation is asked for only where it means something.

If the mappings were previously changed outside DefectDojo, the review says so, and warns that findings imported before that change cannot be recovered by this edit. See Changing mappings outside the API.

Working with mappings through the API#

Everything above is also available through the API, which requires the same maintainer global role.

Create a configuration for a scan type#

POST /api/vue/connector_field_mappings/
{"scan_type": "Snyk Connectors Import", "transforms": [ ... ]}

Your mappings are checked here exactly as an edit checks them, so a transform set that the editor would refuse is refused on creation too.

No acknowledge_identity_change is needed on a create: there is no previous generation to move away from, so there is nothing to acknowledge. The first mapping set is the baseline that later edits are classified against.

Check an edit before making it#

Send your proposed mappings to the impact endpoint to see how they will be classified, without applying anything:

POST /api/vue/connector_field_mappings/{id}/impact/
{"transforms": [ ... ]}

The response tells you whether the edit is identity-relevant, which fields changed, which of those reach identity, and how many findings already exist under this scan type.

Make the edit#

PATCH /api/vue/connector_field_mappings/{id}/
{"transforms": [ ... ], "acknowledge_identity_change": true}

The full mapping set is replaced by what you send, so include the mappings you are keeping. Sending an empty list removes all of them and returns the scan type to what the Connector sends.

acknowledge_identity_change is required only for an identity-relevant edit, and the request is rejected without it. A presentation-only edit does not need it.

A create or an edit is rejected if it targets something that is not a finding field, if an expression reads a field the payload never carries, if strip_pattern is not a valid regular expression, or if two mappings target the same field.

View the history#

GET /api/vue/connector_field_mappings/{id}/revisions/

Every mapping set that has been in force is recorded, newest first, with the fields that changed, whether the edit was identity-relevant, when it happened and who made it.

A configuration cannot be deleted, because the identity generations recorded for its scan type outlive it. Emptying the mappings is the supported way back.

What happens to findings you have already imported#

An identity-relevant edit opens a transition window. While it is open, each sync works out what its findings would have been under the previous mappings as well as the current ones, and carries both identities. Findings imported before the edit are matched on the identity they were stored with, so a reimport updates them rather than closing them and adding duplicates.

Two things to know:

• Only the immediately previous identity generation is bridged. If you make two identity-relevant edits without a sync in between, findings imported before the first edit will not be matched.
• Findings already stored are not rewritten, and no recalculation is triggered. Their stored fields hold the values the old mappings produced, so recalculating would only reproduce the identity they already have. The bridge works on incoming findings, which is where the correction can actually be made.

For that reason, make an identity-relevant mapping change and then sync — the window is what carries your existing findings across, and it only helps a sync that happens while it is open.

Changing mappings outside the API#

Editing a configuration directly in the Django admin, or in a shell, bypasses all of the above: no revision is recorded, no identity generation is bumped, and no transition window opens. Findings imported before such a change become unreachable from findings imported after it. Use the Field Mappings screen or the API — the screen edits through the same API, so both record the change properly.

If it has already happened, the impact endpoint reports it, as unmanaged_identity_change. Findings imported before that change have no recorded identity for a later edit’s window to bridge from, and a later edit cannot recover them.