Skip to content

docs(connectors): DefectDojo source connector page and both migration paths - #16502

Draft
svader0 wants to merge 56 commits into
devfrom
docs/sc-15202-defectdojo-connector
Draft

svader0 wants to merge 56 commits into
devfrom
docs/sc-15202-defectdojo-connector

Conversation

@svader0

@svader0 svader0 commented Oct 22, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Two docs pages for the Source DefectDojo connector. The connector pulls an open source DefectDojo instance into DefectDojo Pro over the export API, from the Connectors UI. You can run it as many times as you need until cutover (story sc-15202, Phase 1).

  • docs/content/connectors/toolreference/defectdojo.md (new). The connector reference page:
    • What the source needs: DefectDojo 3.4.300 or later, HTTPS, and a superuser API key, with the reason for the superuser.
    • The form fields by their UI labels, with defaults.
    • Why to use Auto-Mapping. Mapping a record by hand cannot create a product.
    • The preflight report that Discover stores, section by section: Source, Token, Warnings, Counts, To Be Created, Not Migrated and Estimated Duration. Unknown scan types land in a test of type DefectDojo - Connectors Import.
    • What crosses and what does not. Owners become product members. Migrated users are inactive, have no usable password, are never superusers, and use no license seat until activated or logged in. Secrets, settings, history and files over the size limit do not cross. For a Pro source, the Pro data does not cross.
    • How re-runs behave. A finding removed at the source is closed (mitigated), not deleted.
    • A known limit: a Sync shows Success before a large product's findings finish importing, so check the finding count.
  • docs/content/get_started/pro/onprem/migrating_from_open_source.md (rewritten). The page now has two paths. Path 1 is the database dump, with every existing step kept. Path 2 is the connector, with its own before-you-start list, five steps and a checklist. A "Which path" table at the top compares the two.
    • Both paths now use read-only mode to freeze the source before the final dump or the final Sync. The steps are the same as in feat(system_settings): add a read-only mode #16386: System Settings, then Celery Status and celery inspect active. Path 1 also clears the setting in the restored database.

The connector is not in a Pro release yet, so both pages say it ships in a coming release. The translated siblings of the migration guide are generated, so only the English page changes here.

Related PRs

Checks

  • hugo --minify --gc --config config/production/hugo.toml builds the site with no warning about these pages.
  • I checked every internal link and anchor on the two built pages (299 links). All resolve.

Update (2026-10-26): the connector page and the migration page now say that the connector opens on One-Time, that it can delete its connection after the Sync, that it turns read-only mode on at the source during each Sync and off at the end, that the file cap is in MB, and that the preflight card shows a summary with View More. The cutover steps changed to match: an optional manual lock first, the last Sync, then read-only mode on again.

Update (2026-10-28): with One-Time, Discover starts right after Submit and the records page opens. In View More, each source Product has an Include box. During a Sync the card shows Migrating: X of Y Findings, then Migration Complete or Migration Failed, and Connection Deleted when the connection deletes itself. One notification sums up the migration and stays after the delete.

Update (2026-10-28, later): the connector is now named DefectDojo Migration on its tile, in the connector list and on both pages. The migration page also says that the connector turns read-only mode on at the source for each Sync.

Update (2026-10-28, migration page): the connection now opens on its own migration page. The report sections, the Include boxes, Sync and the run history are on that page, and the tile's card and Manage Configuration menu open it with Open Migration. The View More window is gone.

Update (2026-10-28, tile): Open Migration is now a button on the connector's tile, above Manage Configuration, and a save on Edit Configuration opens the migration page.

Update (2026-10-28, labels): the button on the migration page is Begin Migration, the delete box is Delete the Connection After the Migration, a progress bar shows the import, and a stalled import is described with what to do.

Update (2026-10-28, Auto-Mapping): Auto-Mapping is always on for this connector, so the form no longer offers it. Both pages drop the step that turned it on, and the reference says how to map a source Product to a Product with another name before the migration begins.

Update (2026-10-29): this connector has no records page now, so the reference drops the Edit Record step for a Product with another name, and the gear menu on the migration page holds Discover and Edit Configuration. The checklist asks to clear Include on each Product to leave behind. Frequency now offers One-Time, Daily, Weekly (on a chosen weekday) and Monthly (on the first day of each month). The Estimated Duration counts only the findings in the included Products.

Update (2026-11-04): the reference lists more that crosses. Technologies and languages per Product, tool settings per Product, and the CI/CD fields of an engagement cross. A source whose export sends them also gives the requester and report type of an engagement, its check list, the announcement and the login banner. The source's own deduplication rules per scan type cross too, before the first finding imports. A rule edited in Pro stays. Duplicate deletion, its maximum and retroactive false positive history copy only into a Pro with no findings. Only questionnaires, benchmarks and tracking files stay on the source.

Update (2026-11-04): dev is merged in. The read-only section of the migration page is now the one #16386 merged. Read-only mode ships in DefectDojo 3.5.100, not 3.5.0, so the connector page and the migration page say 3.5.100.

Update (2026-11-05):

  • Not Migrated is now a short list of what stays on the source, as the page shows it.
  • The file size field is in MiB, and the empty migration page says that no report exists yet.
  • Begin Migration waits for a working mail server when users migrate, because each migrated user gets a set-password link by email. Both pages say this, and that SSO or LDAP sign-in, or DefectDojo Pro cloud, needs no mail server here. Path 2's before-you-start list gains an Email item.
  • The production Hugo build passes with these pages, and the gate sentence renders.

Update (2026-11-09):

  • Both pages say the DefectDojo Migration is a beta feature behind its own flag, off by default, and link the Feature Flags page. The production Hugo build passes, and the link resolves.

Update (2026-11-09, scan types):

  • Both pages say that each migrated test keeps its source test type and scan type, and that each finding keeps the test types that found it.
  • A test type that DefectDojo Pro lacks is created with the source settings and takes the deduplication rule of its first test. A test type DefectDojo Pro already has keeps its own, and the Warnings list names those whose settings differ.
  • To Be Created lists Test Types, and the Unknown Scan Types warning is gone. "DefectDojo - Connectors Import" is used only for a source test with no test type.
  • The migration page counts the findings whose hash differs from the source.
  • The production Hugo build passes.

Update (2026-11-09, second review):

  • Activate and Invite mails a set-password link only to a migrated user. A user that no migration created is activated with no link. If SSO or LDAP sign-in is on, no user gets a link, and the user signs in with SSO or LDAP. Both pages and the connector page say this.
  • Activate and Invite skips a user that is already active. So the steps for a new link, or for a user activated with the Active box, now say to deactivate the user with Deactivate Users first.
  • The production Hugo build passes.

Update (2026-11-11, history):

  • Import history and audit history now cross for the objects that the migration creates. Both pages say what crosses and name the two new fields, Migrate Import History and Migrate Audit History. Both are on by default.
  • All Audit Logs shows the last 31 days by default. The pages say that older migrated events show on each object's history page, or with a date filter.
  • The pages say that the audit flush runs at a retention of 0 or above, and that it keeps the older audit log entries. The preflight warns when the flush will delete migrated events.
  • The pages say that history adds Sync time and needs temp disk on the connectors service. History needs a source on DefectDojo 3.5.200 or later.
  • The export, the connectors service and DefectDojo Pro ship the history in one release.
  • The production Hugo build passes.

Update (2026-11-14, more data):

  • Both pages say that endpoints with no finding, endpoint and location metadata, questionnaires, benchmarks and tracking files now cross. They need a source on DefectDojo 3.5.200 or later.
  • These items move from What does not cross to What crosses. The new system settings, the preflight totals and the Not Migrated rows change to match.
  • A risk acceptance keeps every engagement link. A Product Type with no Product crosses with the source type's Authorized Users.
  • The Re-runs list says that a run updates answers and benchmark notes, and removes the ones that the source removed.
  • It also says that risk acceptance links follow the source within each Product. A run only adds endpoint tags, and tracking file tags follow the source.
  • The connector page says which mode each side uses. In Locations mode, a source location that is not a URL becomes a URL location. The connector skips an unparsable URI, such as a pkg: URI.
  • The production Hugo build passes.

Update (2026-11-16, Jira):

  • Both pages say that Jira instances, Jira projects and Jira issue links now cross. They need a source on DefectDojo 3.5.200 or later.
  • An instance crosses with no API token, and a project crosses turned off. A link crosses only onto a migrated project of its own Product or engagement.
  • The Sync warnings count every link that does not cross. No Sync calls Jira.
  • Five Jira settings cross, named by their labels in DefectDojo Pro.
  • A new section gives two cutover paths. Classic Jira: add the token, turn Jira on, then turn on each project. Downstream Connectors: turn on the right projects through the API, run the conversion, then add the token.
  • The connector page says that endpoint statuses follow the Locations migration rule.
  • The production Hugo build passes.

Update (2026-11-17, six more items):

  • Threat model files now cross. DefectDojo Pro stores each file where it stores its own threat models, and the source path never crosses.
  • An SLA configuration with the same name, such as Default, takes the source values on the first Sync. This happens only when no DefectDojo Pro Product outside the migration uses it.
  • Configuration permissions cross as a global role on each new user, with the permissions of its groups. A source staff user that is not a superuser gets DefectDojo Migration: Source Staff.
  • GitHub configurations and projects cross with no API key. GitHub and SonarQube issue links cross too. They need a source on DefectDojo 3.5.200 or later.
  • No Sync calls GitHub or SonarQube. DefectDojo Pro does not reach SonarQube for a migrated link until a person adds credentials to the tool configuration.
  • A new section, Turn on GitHub after the migration, gives the cutover steps. The cutover list on the migration page gains a GitHub step.
  • On each later run, finding tags follow the source, and a tag that a person added stays. A Product that the source moves to another Product Type moves in DefectDojo Pro too.
  • The docs build passes.

… paths

Add the tool reference page for the DefectDojo Upstream Connector, which pulls an
open source DefectDojo instance into DefectDojo Pro over the export API. Rewrite
the self-hosted migration guide so it presents the database dump and the connector
as two paths, with a comparison table. The dump steps stay as they were.

Refs sc-15202. Depends on #16448 for the export API page the two pages link to.
@svader0 svader0 added this to the 3.4.300 milestone Oct 22, 2026
@github-actions github-actions Bot added the docs label Oct 22, 2026
@Maffooch Maffooch modified the milestones: 3.4.300, 3.5.0 Oct 23, 2026
#16386 is milestoned for 3.5.0. A 3.4.300 source has
the export API but no read-only mode, so the connector path now says how to
stop writes by hand.
…d the MB file cap

The Source DefectDojo connector now opens on One-Time, can delete its
connection after the Sync, turns read-only mode on at the source during
each Sync, and takes the file cap in MB. The preflight card shows a
summary with View More.
Also say that the connector turns read-only mode on at the source for each
Sync, instead of saying that it changes nothing there.
…ration page

The report, the Include boxes, Sync and the run history are now on the
connection's migration page instead of a View More window and the records
page. Open Migration on the tile's card or in its Manage Configuration
menu opens it.
…ons, note history and endpoint tags the migration now brings

The preflight report also warns about same-name reference rows with other values, and the Not Migrated list names groups, the audit trail and Jira issue links.
…ccess rules

Activate and Invite skips a user that signed in before and has no password,
and the Users bulk page now describes the action. The connector page says a
Product Type membership needs every Product of the type mapped, and that a
removed membership stays removed. The migration guide says each new user,
gives the reset timeout in seconds, and splits two long sentences.
@svader0
svader0 marked this pull request as draft November 2, 2026 17:55
…te deletion copies into an empty Pro

The rules a customer set on the source for a scan type cross: the
deduplication algorithm and the hash fields. They apply before the first
finding imports, and a rule edited in DefectDojo Pro stays. Duplicate
deletion with its maximum and retroactive false positive history copy
only into a DefectDojo Pro with no findings yet.
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Conflicts have been resolved. A maintainer will review the pull request shortly.

A test keeps its source test type and scan type. A test type the migration creates takes the source flags and rule, and a type DefectDojo Pro has keeps its own. The preflight lists the test types to create and names those that differ, and the migration page counts findings whose hash differs.
@defectdojo-release-tracker defectdojo-release-tracker Bot modified the milestones: 3.5.100, 3.5.200 Nov 9, 2026
…none with SSO or LDAP sign-in

A user that no migration created is activated with no link. If SSO or LDAP sign-in is on,
no user gets a link. Activate and Invite skips a user that is already active, so a new link
needs Deactivate Users first.
The DefectDojo Migration connector now copies import history and audit
history. Describe the two new fields, which objects keep their history,
the preflight totals and warning, the 31-day default of All Audit Logs,
and the audit retention flush. Remove the old "history does not cross"
statements.
Split the sentences over 20 words, name the event type in plain words,
and say that the retention warning also fires on legacy audit entries.
Tell the reader how to keep older migrated events, move the export
version note next to the audit history bullet, and say history crosses
by default.
The audit flush runs when the retention period is 0 or above, and a
period of 0 deletes every event. It deletes audit events only and keeps
legacy audit entries, so the preflight warns when audit events cross and
not for legacy entries alone. Fix both pages to say so.
The page now says that history adds time to each Sync and needs temporary disk space on the connectors service of about twice its size, that a source needs DefectDojo 3.5.200 or later for history, and that a Product's lifecycle, platform and origin stay empty in its migrated events. The note about the export moves below the list of what crosses, the re-run bullet says the history is what the source made since the last run, and the warnings row names the warning for missing history counts.
…tracking files migrate

- The DefectDojo Migration connector now copies endpoints with no finding, endpoint metadata,
  questionnaires, benchmarks and tracking files. The source must run 3.5.200 or later.
- It keeps every engagement link of a risk acceptance and copies a Product Type with no Product.
  That type takes the source type's Authorized Users.
- These items move from What does not cross to What crosses. The preflight and Not Migrated rows
  and the new system settings change to match.
- The Re-runs list says how a run treats answers, benchmark notes, acceptance links and tags.
- The connector page says which mode each side uses. It also says that the connector skips an
  unparsable URI, such as a pkg: URI, in both modes.
Jira instances, projects and issue links now cross. The docs name the five settings, the two cutover paths and the endpoint status rule.
Use the labels of the Pro System Settings page, drop mitigated_by from the small fields, and describe the Jira warning in the report table.
…which Jira links cross

The conversion sets up automatic pushes only for a project that is on and pushes all issues, so the steps now keep Jira off, turn on those projects, run the conversion, then add the token. A Jira link crosses only when its Jira project crosses. The Warnings, Products and Not Migrated rows now name the Jira warning, the Jira Projects total and an older source's Jira.
The Downstream Connectors cutover keeps Jira off in System Settings. The forms that turn a Jira project on show only while Jira is on. So the step now turns each project on with PATCH /api/v2/jira_projects/<id>/.

The pages also say that a Jira link crosses only onto a project of its own Product or engagement. Two long sentences in the Warnings row are split.
The GET that lists projects to turn on now filters by the migrated Jira instance. The turn-on step also starts with Through the API.
@defectdojo-release-tracker defectdojo-release-tracker Bot modified the milestones: 3.5.200, 3.5.300 Nov 17, 2026
… configuration roles and later Syncs

The connector reference says that threat model files, the GitHub and SonarQube links and the configuration permissions cross. It explains when the Default SLA takes the source values, how finding tags and Product Type moves follow the source on later Syncs, and how to turn on GitHub after the migration. The migration guide adds the GitHub cutover step and drops the line that no global role crosses.
…nd newer-source links

Pro reaches SonarQube for a migrated link only after a person adds credentials to its tool configuration. Configuration permissions include the ones a user gets through its groups. The SLA warning reads the mappings at Discover. Not Migrated names GitHub and SonarQube links for an older source. The GitHub cutover says to keep each Product's migrated GitHub project.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants