docs: add Backstage Pro connector reference (#15223)

* docs: add Backstage Pro connector reference

Document the new Backstage asset connector: what it maps (System ->
Product Type, Component -> Product, owning Group -> Product ownership,
tags/annotations), the Backstage-side static externalAccess token setup
with catalog-only accessRestrictions, the connector configuration
reference, sync semantics (uid-keyed renames in place, MISSING on
removal/orphan), v1 limitations, and a note that a Backstage frontend
plugin showing DefectDojo findings on entity pages is a deliberate
out-of-scope follow-on. Also add Backstage to the supported-tools list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: clarify that Backstage-mapped Product names track the catalog

E2E-verified behavior worth stating explicitly: the connector reconciles
the Product name to the catalog name on every sync, so renames belong in
Backstage, and custom names given at manual-mapping time do not stick.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: devGregA <greg-agent-2@defectdojo.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

docs/content/import_data/pro/connectors/about_connectors.md

@@ -29,6 +29,7 @@ We currently support Connectors for the following tools, with more on the way:
 * **Akamai API Security**
 * **Anchore**
 * **AWS Security Hub**
+* **Backstage** (asset inventory: builds Product hierarchy and team ownership from the Software Catalog)
 * **BurpSuite**
 * **Checkmarx ONE**
 * **Dependency-Track**

docs/content/import_data/pro/connectors/connectors_tool_reference.md

@@ -97,6 +97,66 @@ Once you have created your IAM user and assigned it the necessary permissions us
 
 DefectDojo can pull Findings from more than one region using Security Hub's **cross\-region aggregation** feature. If [cross\-region aggregation](https://docs.aws.amazon.com/securityhub/latest/userguide/finding-aggregation.html) is enabled, you should supply the API endpoint for your "**Aggregation Region**". Additional linked regions will have ProductRecords created for them in DefectDojo based on your AWS account ID and the region name.
 
+## **Backstage**
+
+The Backstage connector is an **asset connector**: instead of importing Findings, it pulls your [Backstage](https://backstage.io) Software Catalog into DefectDojo and keeps your Product hierarchy and team ownership in sync with it. It is designed for organizations that maintain their service inventory and org structure in Backstage and want DefectDojo to mirror that structure instead of maintaining it by hand.
+
+#### What gets mapped
+
+| Backstage | DefectDojo |
+|---|---|
+| **System** | Product Type (Components with no System are grouped under a configurable "Backstage / Uncategorized" Product Type) |
+| **Component** | Product — named from the entity `title` (falling back to `name`), with the catalog description |
+| **Owning Group** (`ownedBy` relation) | A DefectDojo Group linked to the Product (default role: Maintainer, configurable) |
+| **Owner email** (Group profile email, or a User owner's email) | A Product Member, when a DefectDojo user with that email already exists (users are never created) |
+| `metadata.tags`, `spec.type`, `spec.lifecycle`, namespace, domain | Product tags under a `backstage:` prefix |
+| `metadata.annotations` | Stored on the Record (bounded); selected annotations can be promoted to first-class attributes or tags via **Annotation Mappings** |
+
+Records are keyed by the entity's server\-assigned `metadata.uid`, so renames in Backstage update the mapped Product **in place** on the next sync — no duplicates. The Product name always tracks the catalog: to rename a Product managed by this connector, rename the Component in Backstage (a DefectDojo\-side rename, or a custom name given during manual mapping, is reconciled back to the catalog name on the next sync unless it would collide with another Product). Ownership changes move the Product's group assignment. Components that disappear from the catalog (or are flagged with the `backstage.io/orphan` annotation) are marked **MISSING** — DefectDojo never deletes a Product on its own. Domain and Group hierarchy (parent teams) are recorded as tags/metadata only; they do not create extra hierarchy levels.
+
+#### Prerequisites
+
+The connector authenticates with a **static external access token** against the Backstage backend. In your Backstage app config, define a token and (recommended) restrict it to the catalog plugin:
+
+```yaml
+backend:
+  auth:
+    externalAccess:
+      - type: static
+        options:
+          token: ${DEFECTDOJO_BACKSTAGE_TOKEN}
+          subject: defectdojo-connector
+        accessRestrictions:
+          - plugin: catalog
+```
+
+Generate a strong random token (for example `openssl rand -hex 32`) and store it in your Backstage deployment's environment. See the [Backstage service-to-service auth documentation](https://backstage.io/docs/auth/service-to-service-auth) for details.
+
+#### Connector Mappings
+
+1. 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.
+2. Enter the static external access token in the **Secret** field.
+
+Optional fields (leave blank for the defaults):
+
+* **Namespaces** — comma\-separated catalog namespaces to import; blank imports every namespace.
+* **Component Types** — comma\-separated `spec.type` values (e.g. `service,website`); blank imports every type.
+* **Page Size** — catalog query page size (1\-500, default 250).
+* **TLS Verification** — set to `false` only if Backstage serves a certificate DefectDojo cannot verify (internal CA); not recommended.
+* **Uncategorized Product Type** — the Product Type used for Components with no System (default `Backstage / Uncategorized`).
+* **Owner Group Role** — the role granted to the owning team on mapped Products (default `Maintainer`).
+* **Annotation Mappings** — a JSON object mapping annotation keys to Record attribute names, or to `"tag"` to import an annotation as a Product tag, e.g. `{"github.com/project-slug": "GITHUB_PROJECT", "example.com/tier": "tag"}`.
+
+With **Auto\-Map** enabled, a single Discover \+ Sync builds the complete Product Type / Product / ownership structure with no manual steps. With Auto\-Map disabled, discovered Components appear as Records awaiting your mapping decision.
+
+#### Limitations (v1)
+
+* Backstage **Group membership is not synchronized**: the connector creates/links the owning team as a DefectDojo Group, but populating that group's users is left to your identity provider or admins.
+* Only Components become Products; APIs, Resources, and Domains are not imported as assets (domains surface as tags).
+* Tags and annotations are normalized and bounded to fit DefectDojo field limits (oversized values are truncated).
+
+**A note on the reverse direction:** displaying DefectDojo findings and grades *inside* Backstage (on entity pages) is a natural follow\-on that would be built as a Backstage frontend plugin consuming the DefectDojo REST API — it is deliberately out of scope for this connector, which only pulls catalog data into DefectDojo.
+
 ## **BurpSuite**
 
 DefectDojo’s Burp connector calls Burp’s GraphQL API to fetch data.