From 9e2299fa6c19e6790e16a1a504319465625d6523 Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Thu, 20 Aug 2026 16:33:00 -0600 Subject: [PATCH] docs(connectors): document GitHub issue import on the GHAS connector The GitHub Advanced Security connector can now import a repository's issue tracker as a fourth finding type, GitHub:Issues, alongside the code scanning, Dependabot and secret scanning alert families. Documents the two settings that drive it -- Issue Labels as the filter, Issue Severity Labels as the label-to-severity map, and Default Issue Severity for whatever the map does not match -- plus the token permission issues need, which is less than the alert families require and does not depend on Advanced Security being enabled at all. Adds a "what to expect" section covering the parts that surprise people: pull requests are never imported even though GitHub returns them from the issues endpoint, closing an issue closes the finding, the issue body is reproduced verbatim as the description, and these findings carry no CWE, CVE or component so they will not deduplicate against scanner findings for the same problem. English only; the translated tool references are updated by their own pass. Co-Authored-By: Claude Opus 5 --- .../connectors/upstream/toolreference.md | 36 +++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/content/connectors/upstream/toolreference.md b/docs/content/connectors/upstream/toolreference.md index 04810f4970..1c6690b8a7 100644 --- a/docs/content/connectors/upstream/toolreference.md +++ b/docs/content/connectors/upstream/toolreference.md @@ -1040,7 +1040,7 @@ Only **open** incidents (status `TRIGGERED` or `ASSIGNED`) are imported; inciden The GitHub connector is an **Asset Connector**: it enumerates the repositories your token can access and creates a DefectDojo Asset for each one, grouped into Organizations by GitHub owner (organization or user). No findings are imported. -**Please note:** this connector imports your repository **inventory** only. To import GitHub security alerts — code scanning, Dependabot, and secret scanning — as findings, use the separate **GitHub Advanced Security** connector below. The two are independent and can be run together. +**Please note:** this connector imports your repository **inventory** only. To import findings from GitHub — code scanning, Dependabot, and secret scanning alerts, or issues from the repository issue tracker — use the separate **GitHub Advanced Security** connector below. The two are independent and can be run together. #### Prerequisites @@ -1064,6 +1064,8 @@ No organization or repository list needs to be entered — DefectDojo imports ev The GitHub Advanced Security connector imports **code scanning**, **Dependabot**, and **secret scanning** alerts from GitHub, as three separate finding types (`GitHub:CodeScanning`, `GitHub:Dependabot`, and `GitHub:SecretScanning`). DefectDojo discovers every non\-archived repository in the configured organization and creates a Record for each one. +It can also import **issues** from each repository's issue tracker as a fourth finding type (`GitHub:Issues`), for teams that record vulnerabilities as ordinary GitHub Issues rather than as security alerts. Issue import is off until you configure it — see [Importing Issues](#importing-issues) below. + #### Prerequisites GitHub Advanced Security features must be enabled for the repositories you want to import. The connector authenticates with a GitHub **personal access token**: @@ -1072,14 +1074,44 @@ GitHub Advanced Security features must be enabled for the repositories you want 2. Grant it read access to the security alerts: a *fine\-grained* token needs **Read\-only** access to **Code scanning alerts**, **Dependabot alerts**, and **Secret scanning alerts** on the organization's repositories; a *classic* token needs the **`repo`** and **`security_events`** scopes. 3. Confirm the token's owner can see the repositories you intend to import — the connector only sees repositories the token can access. +If you also want to import issues, the token needs read access to them: a *fine\-grained* token needs **Read\-only** access to **Issues**, and a *classic* token already has it through the **`repo`** scope. Note that GitHub Advanced Security does **not** need to be enabled to import issues — the issue tracker is available on every repository. + #### Connector Mappings 1. Enter `https://api.github.com` in the **Location** field. For GitHub Enterprise Server, use `https:///api/v3`. 2. Enter the organization login in the **Organization** field. 3. Enter the personal access token in the **Secret** field. 4. Optionally, set a **Minimum Severity** to limit which findings are imported. +5. To import issues as well, set **Issue Labels**, and optionally **Issue Severity Labels** and **Default Issue Severity**. See [Importing Issues](#importing-issues) below. + +Each non\-archived repository becomes a Record, queried across the three alert families for open alerts, and for open issues when issue import is configured. A family that is not enabled for a repository is skipped rather than reported as resolved, so disabled features do not cause false closures. + +#### Importing Issues + +GitHub attaches no severity, CWE, or CVE to an issue — an issue is a tracker entry someone wrote, not scanner output. Two settings therefore decide what gets imported and how it is scored. Both are blank by default, and **no issues are imported until you set a label**, so an existing connector keeps importing only the three alert families. + +**Issue Labels** decides which issues qualify. Enter one or more labels, separated by commas. An issue must carry **every** label listed to be imported — GitHub combines them with AND, not OR — so a single label is the usual choice. Nothing about the label has to be security\-related: whatever you use to mark the issues you want in DefectDojo is what you enter here. + +**Issue Severity Labels** decides how each imported issue is scored, by mapping your own labels onto DefectDojo severities: + +``` +Critical=sev-1,blocker; High=sev-2,p1; Medium=sev-3; Low=sev-4; Info=chore +``` + +Each entry names a DefectDojo severity, then the labels that mean it. Several labels can map to one severity, matching ignores case, and if an issue carries two mapped labels the higher severity wins. Leave this blank if your labels are already severity names — `critical`, `high`, `medium`, `low`, `info` are then matched as they are. If you do set a map, only the labels it names are matched. + +**Default Issue Severity** is used for an issue that qualifies but carries no label the map recognizes. It defaults to **Medium**. + +An invalid map — a severity DefectDojo does not have, or a label assigned to two different severities — is rejected when you save the connector rather than part\-way through a sync. + +#### What to expect from imported issues -Each non\-archived repository becomes a Record, queried across the three alert families for open alerts. An alert family that is not enabled for a repository is skipped rather than reported as resolved, so disabled features do not cause false closures. +* **Pull requests are never imported.** GitHub returns them from the same endpoint as issues, but DefectDojo filters them out, so a pull request carrying your label will not appear as a finding. +* **Closing the issue closes the finding.** Only open issues are read, so an issue you close disappears from the next sync and DefectDojo resolves the finding it produced. Reopening it reopens the same finding rather than creating a second one. +* **The issue body becomes the finding description**, reproduced as written, along with the repository, issue number, author, and labels. Anything written in a GitHub issue therefore reaches DefectDojo. +* **The issue's labels are added to the finding as tags**, so you can filter and build rules on them. +* **These findings carry no CWE, CVE, component, or file path**, because the source has none. They will not deduplicate or correlate against scanner findings for the same vulnerability — if a problem is reported both by a scanner and by a hand\-written issue, DefectDojo holds two findings. +* **A repository with its issue tracker disabled is skipped**, not reported as empty, so turning issues off for a repository does not close the findings already imported from it. ## **GitLab**