Backstage Integration with DefectDojo

Backstage Integration with DefectDojo

Backstage is an open source framework for building developer portals, created at Spotify and now a Cloud Native Computing Foundation project. Its Software Catalog records the services, websites, libraries, and other software an organization runs as entities such as Systems and Components, along with the Groups and Users that own them. The DefectDojo Pro connector for Backstage is an asset connector: it pulls the catalog into DefectDojo and keeps the Asset hierarchy and team ownership in sync with it, and it does not import findings.

Backstage Integration with DefectDojo

We connected Backstage to DefectDojo because our catalog already answered the two questions every finding needs answered: what service is this, and who owns it. Before the connector, we kept a second copy of that information in DefectDojo by hand, and it drifted every time a team reorganized. Now each Backstage Component is an Asset, each System is an Organization, and the owning team is linked to the Asset as a DefectDojo Group. When scanners import findings, they land on Assets that already have owners.

Why Backstage Matters

Teams that adopt Backstage usually do it to get one trustworthy inventory of their software and who is responsible for it. A vulnerability program depends on the same thing.

• The catalog names every Component and links it to an owning Group through the ownedBy relation, which is the assignment information security teams usually chase manually.
• Systems group related Components, which is a sensible level for rolling up risk and reporting to engineering leadership.
• Lifecycle values such as experimental, production, and deprecated tell you which services deserve the strictest SLAs.
• When the catalog and the security tool disagree, findings end up on orphaned Assets nobody owns.

Advantages of This Integration

What the Backstage connector adds to DefectDojo Pro:

• Assets that match the catalog. Each Component becomes an Asset named from the entity title (or name), with the catalog description.
• Organizations from Systems. Components are grouped by System, and Components with no System go to a configurable "Backstage / Uncategorized" Organization.
• Ownership without manual setup. The owning Group becomes a DefectDojo Group linked to the Asset with the Maintainer role by default, and owner emails that match existing DefectDojo users become Asset Members.
• Lifecycle carried over. experimental becomes Construction, production becomes Production, and deprecated becomes Retirement. A lifecycle someone set by hand in DefectDojo is never overwritten.
• Renames handled in place. Records are keyed by the entity's metadata.uid, so a rename in Backstage updates the mapped Asset on the next sync instead of creating a duplicate.
• No silent deletions. Components that disappear from the catalog, or carry the backstage.io/orphan annotation, are marked MISSING. DefectDojo never deletes an Asset on its own.

How This Integration Works

The Backstage connector is configured in DefectDojo Pro under Connect > Upstream and authenticates with a static external access token against the Backstage backend.

1. Create an access token in Backstage. In your Backstage app config, define a static external access token under backend.auth.externalAccess, give it a subject such as defectdojo-connector, and (recommended) restrict it to the catalog plugin with accessRestrictions. Generate a strong random value and store it in your Backstage deployment's environment. The Backstage service-to-service auth documentation covers the details.

2. Configure the connector. Enter your Backstage backend root URL in the Location field, for example https://backstage.example.com. The connector appends /api/catalog. This must be the backend URL, not the frontend web UI. Enter the token in the Secret field.

3. Set optional filters. Namespaces and Component Types (comma-separated spec.type values such as service,website) narrow the import; blank imports everything. You can also set Page Size (1 to 500, default 250), TLS Verification, the name of the Uncategorized Organization, the Owner Group Role (default Maintainer), and Annotation Mappings, a JSON object that maps annotation keys to Record attributes or to Asset tags.

4. Discover and Sync. With Auto-Map enabled, one Discover plus one Sync builds the complete Organization, Asset, and ownership structure. With Auto-Map disabled, discovered Components appear as Records waiting for your mapping decision.

Data Granularity: What Gets Mapped

This connector maps catalog entities to DefectDojo objects. It imports no findings.

Domains and parent Group hierarchy are recorded as tags or metadata only and do not create extra hierarchy levels.

Use Cases

Onboarding a scanner fleet: Before connecting SAST, SCA, and container scanners, a team syncs Backstage so every service already exists as an Asset with an owning Group. Findings from those tools then land on Assets that have someone to assign them to.

Reorganizations: When a Component moves from one team to another in Backstage, the next sync moves the Asset's group assignment. Security doesn't have to hear about the reorg secondhand to keep assignments correct.

Lifecycle-aware SLAs: Because production Components arrive with the Production lifecycle and deprecated ones with Retirement, teams can tell which Assets need the strictest remediation targets and which are on their way out.

Catalog hygiene: MISSING Records point to Components that were removed or orphaned in Backstage. Reviewing them regularly keeps old findings from sitting on Assets for services that no longer exist.

Operational Tips

• Use the backend URL. Pointing the Location at the Backstage frontend is the most likely setup mistake.
• Restrict the access token to the catalog plugin. The connector only reads catalog data, so it doesn't need anything else.
• Rename Assets in Backstage, not in DefectDojo. The Asset name tracks the catalog, and a DefectDojo-side rename is reconciled back on the next sync unless it would collide with another Asset.
• Group membership is not synchronized. The connector creates or links the owning Group, but populating its users is left to your identity provider or administrators.
• Only Components become Assets. APIs, Resources, and Domains are not imported as Assets, so plan your catalog modeling with that in mind.
• Use Annotation Mappings to pull useful annotations, such as a source repository slug or a tier label, onto the Record or into Asset tags for filtering.