Bitbucket Integration with DefectDojo

Bitbucket Integration with DefectDojo

Bitbucket is Atlassian's Git hosting service. Bitbucket Cloud, at bitbucket.org, organizes repositories into workspaces and projects, and each repository can optionally enable a built-in issue tracker. DefectDojo Pro connects to Bitbucket Cloud in both directions: an Upstream asset connector that creates an Asset for each repository, and a Downstream Connector that pushes Findings and Finding Groups into a repository's issue tracker. Neither direction imports vulnerability findings from Bitbucket.

Bitbucket Integration with DefectDojo

We connected Bitbucket to DefectDojo because our repositories are the natural unit of ownership for code findings, and we wanted DefectDojo's Assets to match them exactly. The upstream connector reads the workspaces we name and creates an Asset per repository, grouped by Bitbucket project. The downstream side closes the loop: for teams that track work in Bitbucket's issue tracker rather than Jira, DefectDojo opens issues in the repository the finding belongs to and keeps their priority and state aligned with the Finding.

Why Bitbucket Matters

For teams on Bitbucket Cloud, the repository list is already the most accurate inventory of their code. It changes every time someone creates or archives a repo.

• Repositories map cleanly to the Assets that SAST, SCA, and secrets scanners report against.
• Bitbucket projects group repositories by team or product, which is a reasonable Organization boundary in DefectDojo.
• Some teams keep their backlog in the repository's own issue tracker. Security work that lives somewhere else tends to be ignored.
• Maintaining a parallel repository list in a security tool by hand means new repos go unscanned or land on the wrong Asset.

Advantages of This Integration

What both halves of the integration add to DefectDojo Pro:

• An Asset per repository. The upstream connector enumerates repositories in the workspaces you name and creates a Record for each, named after the repository.
• Organizations from projects. Repositories are grouped into Organizations by their Bitbucket project.
• Findings as Bitbucket issues. The downstream connector creates issues in a repository's issue tracker, either on demand with Push to Integrator or automatically when Findings are created or updated.
• Priority and state kept in step. DefectDojo severities map to Bitbucket priorities, and Finding status maps to issue state, so a mitigated or risk-accepted Finding is reflected on the issue.
• Push filters. Automatic creation can be limited to a Minimum Severity and to active Findings only, so low-value tickets don't flood a repository.
• Errors you can find. Each Issue Tracker Mapping keeps a table of push errors, with the time, the reason, and the Finding that failed.

How This Integration Works

Both connectors are DefectDojo Pro features and support Bitbucket Cloud (bitbucket.org) only. Bitbucket Server reached end of life in 2024, and Bitbucket Data Center is not supported by the upstream connector.

Upstream: repositories as Assets

1. Create a scoped Atlassian API token. In your Atlassian account's API token settings, choose Create API token with scopes, select the Bitbucket app, and grant read:account:bitbucket, read:workspace:bitbucket, read:repository:bitbucket, and read:project:bitbucket. Classic, unscoped tokens are rejected by Bitbucket.
2. In Connect > Upstream, add the Bitbucket connector. Enter https://bitbucket.org as the Location, the Atlassian account email the token belongs to, and the token as the Secret.
3. Enter one or more workspace slugs, comma-separated. This field is required because scoped tokens cannot list workspaces on their own.
4. Run Discover and Sync. With Auto-Map enabled, each repository becomes an Asset under its project's Organization.

Downstream: Findings to Bitbucket issues

1. Enable the issue tracker on each target repository in Bitbucket under Repository settings > Features. DefectDojo cannot create issues until it is on.
2. Create a scoped API token with permission to read repositories and to read and write issues. App passwords are deprecated by Atlassian and will not work.
3. In Connect > Downstream, create an Integration Instance with a label, https://bitbucket.org as the Location, the account email, and the API token.
4. Create an Issue Tracker Mapping with the workspace slug and the repository slug, and review the severity and status mappings.
5. Assign the mapping to an Asset or Engagement with an Issue Tracker Assignment, choosing whether Findings are pushed only explicitly, automatically on creation, automatically on edit of an existing link, or both.

Data Granularity: What Gets Synced and Sent

Valid Bitbucket states for custom mappings are new, open, resolved, on hold, invalid, duplicate, wontfix, and closed.

Use Cases

Inventory first, scanners second: A team syncs its Bitbucket workspaces before connecting code scanners, so every repository already has an Asset in the right Organization when SAST and SCA results arrive.

Teams that live in Bitbucket issues: A small product team without Jira assigns its repository's issue tracker to the Asset. New High and Critical findings open as major and critical priority issues where the developers already look, and with automatic updates enabled, closing the Finding in DefectDojo moves the issue to resolved.

Keeping new repositories covered: When someone creates a repository in a synced workspace, the next Discover adds a Record for it. Reviewing new Records is a simple way to spot repos that have not been onboarded to scanning yet.

Different routing per repository: An Issue Tracker Assignment targets one Asset or Engagement, so each repository's Asset can point at its own repository's issue tracker through its own mapping.

Operational Tips

• Use scoped API tokens for both directions. Classic tokens fail upstream with a "no Bitbucket scopes" error, and app passwords no longer work downstream.
• List every workspace you care about in Workspace Slugs. Anything not listed is not discovered.
• Turn on the repository issue tracker before creating the mapping, or pushes will fail and show up in the mapping's error table.
• Start with automatic creation filtered to High severity and active Findings, then widen it once teams are comfortable with the volume.
• Check the default severity mapping against how your teams use Bitbucket priorities. Every value must be one of trivial, minor, major, critical, or blocker.
• If you track work in Jira as well, decide per Asset which tracker owns security issues so the same Finding is not ticketed twice.