Shortcut Integration with DefectDojo

Shortcut Integration with DefectDojo

Shortcut is a project management platform for software teams, known as Clubhouse until its 2021 rename. Work in Shortcut is tracked as Stories, typed as features, bugs, or chores, and organized by Teams, Epics, and Iterations. Each workspace defines its own Workflows, made up of Workflow States that a Story moves through. Shortcut provides a REST API, which DefectDojo Pro uses to create and update Stories.

Shortcut Integration with DefectDojo

Our engineering teams plan every sprint in Shortcut, so we connected it to DefectDojo Pro to put security work in the same backlog as everything else. The Downstream Connector creates a Bug Story for each pushed Finding and assigns it to the Shortcut Team that owns the code. DefectDojo severity becomes a label on the Story, and the Finding's status decides which Workflow State the Story sits in. When a Finding is mitigated, accepted, or marked a false positive in DefectDojo, the Story moves to the state we mapped for it. Security keeps triage, deduplication, and SLA reporting in DefectDojo, and developers pick up the work during sprint planning like any other bug.

Why Shortcut Matters

Developers fix what is in front of them, and for teams on Shortcut that is the Story list for the current Iteration.

• Bug Stories sit next to feature work, so security fixes are planned and estimated instead of handled on the side.
• Teams in Shortcut map to the groups that own code, which gives each finding an obvious owner.
• Labels are how many Shortcut users filter and report, so a severity label makes security work easy to find on any view.
• Copying findings into Stories by hand is slow, and nobody remembers to close the Story when the finding is retested. The two lists drift.

Advantages of This Integration

What we gained by pushing DefectDojo findings to Shortcut:

• Stories created for us. An Issue Tracker Assignment on an Asset or Engagement can push new Findings automatically, update linked Stories when Findings change, or both.
• Severity as labels. Each severity maps to a label name. Labels are created in Shortcut automatically if they do not exist, and when a Finding's severity changes the old label is removed and the new one added.
• Status that follows the Finding. Active, Closed, False Positive, and Risk Accepted each map to a Workflow State ID in your workspace.
• Deleted Findings close their Stories. When a Finding is deleted in DefectDojo, its Story moves to the state mapped for Closed.
• Only what matters gets pushed. Push filters limit automatic creation to a minimum severity and to active Findings.
• Traceability. Linked Stories appear in the Integrator Tickets column with the ticket ID, a direct link, and a changelog of when DefectDojo last changed them.
• Visible errors. Each Issue Tracker Mapping lists failed pushes with the time, reason, and Finding.

How This Integration Works

Shortcut is a DefectDojo Pro Downstream Connector, configured under Connect > Downstream. It is not part of Community Edition, where the documented issue-tracking integration is Jira.

1. Create an API token. In Shortcut, open Settings, then Your Account, then API Tokens, and generate a token. A token belonging to a service account keeps Story activity easy to trace.

2. Create the Integration Instance. Add Shortcut and enter a Label, set Location to https://api.app.shortcut.com, and paste the API Token.

3. Find your Team ID and Workflow State IDs. The Team (Group) ID is the UUID of the Team that Stories will be created for. Copy it from the Team page URL in Shortcut, or list your Teams through the Shortcut API's groups endpoint. Workflow State IDs are numeric and unique to each workspace, so there are no defaults. List them through the Shortcut API's workflows endpoint, authenticating with your API token.

4. Create an Issue Tracker Mapping. Enter the Team (Group) ID. Review the severity labels, and set each status mapping to a Workflow State ID:

• Active: the state for open work, such as a Backlog or To Do state.
• Closed: a Done type state. Stories for deleted Findings also move here.
• False Positive and Risk Accepted: the states you want those Findings to show in.

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 belongs to a different Team.

6. Push. Findings in an assigned Asset or Engagement get a Push to Integrator action. Automatic pushes follow the Assignment, and DefectDojo Pro rules can push through the Triage Engine Create a Downstream Ticket node.

Data Granularity: What Gets Sent

The default label names can be kept as they are or replaced with label names your teams already use.

Use Cases

Security bugs in the sprint: Each service's Asset is mapped to the Shortcut Team that owns it. New High and Critical findings from SAST and SCA imports become Bug Stories in the Team's backlog and get pulled into the next Iteration.

Filtering by severity label: Engineering managers build a Shortcut view filtered on sev-critical and sev-high to see every open security bug across Teams without logging into DefectDojo.

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

Validated pentest findings only: Pentest findings are reviewed in DefectDojo first and pushed one at a time with Push to Integrator, so only confirmed issues reach the developers' board.

Operational Tips

• Look up Workflow State IDs before creating the Mapping. They are unique to each workspace and have no defaults, so a missing ID means statuses cannot sync.
• If your Teams use different Workflows, check that the state IDs you map exist in the Workflow those Stories use.
• Point Closed at a Done type state. Deleted Findings move their Stories there, so a non-done state would leave them looking open.
• Keep or rename the severity labels, but agree on one set across Mappings so filters work workspace-wide.
• Set a minimum severity and the active-only filter on automatic Assignments. Updates to linked Stories are always sent, so closures still reach Shortcut.
• Review the Mapping's error table after the first push. Token, Team ID, and state ID problems show up there first.