GitHub Issues Integration with DefectDojo

GitHub Issues Integration with DefectDojo

GitHub Issues is the issue tracker built into every GitHub repository, and GitHub Projects is GitHub's planning tool that organizes issues from one or more repositories into boards and tables with custom fields such as Priority and Status. Both belong to a GitHub organization or a personal account. Issues and project items are created and updated through GitHub's APIs, which is how DefectDojo Pro sends Findings to them.

GitHub Issues Integration with DefectDojo

Our developers plan their work in GitHub, so a security finding that lives only in DefectDojo is a finding they won't see until someone forwards it. The DefectDojo Pro GitHub integration adds Findings to a GitHub Project, which opens an Issue in the repository that owns the code. DefectDojo's severity sets the item's Priority field and its status drives the Status column, so when a Finding is mitigated in DefectDojo the item moves to Done. Security keeps deduplication, SLAs, and reporting in DefectDojo. Developers get an issue in the place they already work.

Why GitHub Issues Matters

Fixes happen in code, and code lives in repositories. The shorter the distance between a finding and the repository, the faster it gets fixed.

• Developers triage and plan from GitHub Issues and Projects, so security work there competes fairly with feature work.
• Issues link naturally to the pull requests that fix them, which keeps the history of a fix in one place.
• Project fields such as Priority let teams sort security issues with everything else on their board.
• Copying findings into issues by hand is slow, and nobody closes the issue when the finding is retested, so the two lists drift.

Advantages of This Integration

What we gained by pushing DefectDojo findings to GitHub:

• Issues created for us. An Issue Tracker Assignment on an Asset or Engagement can push every new Finding automatically, update linked issues when Findings change, or both.
• Only what matters gets pushed. Push filters limit automatic creation to a minimum severity and to active Findings, so developers don't receive Info findings or items that are already closed.
• Status that follows the Finding. DefectDojo status maps to the Project's Status field, so mitigated, false positive, and risk-accepted Findings move to the mapped column.
• One ticket per fix. Finding Groups can be pushed as one item when a single change, such as a dependency upgrade, resolves several Findings.
• Traceability. Linked tickets show in the Integrator Tickets column with the ticket ID, a direct link, and a changelog of when DefectDojo last changed the ticket.
• Visible errors. Each Issue Tracker Mapping lists failed pushes with the time, reason, and Finding.

How This Integration Works

GitHub Issues is a DefectDojo Pro Downstream Connector. Downstream Connectors are on for every DefectDojo Pro instance, Cloud and On-Premise. The DefectDojo docs list Jira as the issue-tracking integration available in Community Edition.

1. Prepare the GitHub Project. The integration adds items to a GitHub Project, which also opens Issues in an associated repository. The Project must have a single-select custom field for Priority, with an option for each value you map severities to (DefectDojo suggests P0 through P4). Without that field, severity won't map and Issues won't push. New Projects include "In Progress" and "Done" statuses. Add more Status options, such as False Positive or Risk Accepted, if you want those states visible.

2. Create a token. Create a GitHub personal access token at https://github.com/settings/tokens with Repo and Project scopes.

3. Create the Integration Instance. Under Connect > Downstream, add GitHub and enter:

• Label: a name for this integration.
• Location: the GitHub organization or user URL where issues should be created, for example https://github.com/your-organization.
• Token: the personal access token.

4. Create an Issue Tracker Mapping. Give it a label, then enter the Project Number (from the Project URL, such as https://github.com/orgs/your-org/projects/7) and the Repository Name to open Issues in. Review the severity and status mappings.

5. Assign Assets or Engagements. An Issue Tracker Assignment links an Asset or Engagement to the Mapping and chooses the push mode: explicit only, link new Findings automatically, update existing links on edit, or link new and update existing. Create one Assignment per Asset or Engagement, and a separate Mapping when an Asset's code lives in a different repository.

6. Push. Findings in an assigned Asset or Engagement get a Push to Integrator action for manual pushes. Automatic pushes follow the Assignment.

Data Granularity: What Gets Sent

Severity and status mappings are editable on the Issue Tracker Mapping, and each mapped value must exist as an option on the Project field.

Use Cases

SAST and SCA findings to the owning repo: Each service's Asset is mapped to its repository. New High and Critical code and dependency findings open Issues automatically on the team's Project board, where they are planned in the next sprint like any other work.

Dependency upgrades as one task: Findings grouped by component are pushed as a Finding Group, so the team gets one issue to upgrade a library instead of a dozen CVE issues for the same package.

Closing the loop after a fix: A developer merges the fix, the next scan no longer reports the Finding, and the reimport mitigates it. With updates on edit enabled, the Project item moves to Done without anyone touching it.

Pentest findings for developers: Manually reviewed pentest findings are pushed one by one with Push to Integrator, so only validated issues reach the development board.

Operational Tips

• Check the default Priority mapping against your team's convention. It maps Critical to P4 and Info to P0, so if your team treats P0 as most urgent, reverse it in the Mapping.
• Create the Priority field and all mapped options before the first push. A missing field or option stops Issues from pushing.
• Set a minimum severity and active-only filter on automatic Assignments. Updates to already-linked issues are always sent, so closures still reach GitHub.
• Use a token owned by a dedicated service account and note when it expires, so pushes don't stop silently.
• If you want Findings in DefectDojo created from issues developers file by hand, that is the opposite direction. The DefectDojo Pro GitHub Advanced Security connector can import labeled GitHub Issues as Findings of the GitHub:Issues type.
• Review the Mapping's error table after setup. Permission and field-mapping problems show up there first.