From 587e2cdfa47585454daf744d1a117cd84209d3f3 Mon Sep 17 00:00:00 2001 From: devGregA Date: Tue, 11 Aug 2026 21:36:53 -0600 Subject: [PATCH] docs: asset kinds and per-source asset aliases (asset model Phase 4) Documents the two user-visible halves of the identity work: * Asset Kinds -- an optional, descriptive kind per Asset (repository, service, host, ...), drawn from an editable registry rather than a fixed list. * Asset Identity -- per-source aliases (namespace / type / value), what makes an identifier resolve to exactly one Asset, why user-asserted aliases survive automation, and why there is no update action. Also documents how connector Auto-Mapping now chooses a Product: the tool's own identifier first, the name second, a new Product last -- and that turning the feature on changes nothing about mappings that already exist. --- .../engagements_tests/PRO__assets.md | 49 +++++++++++++++++++ .../connectors/upstream/manage_records.md | 26 ++++++++++ 2 files changed, 75 insertions(+) diff --git a/docs/content/asset_modelling/engagements_tests/PRO__assets.md b/docs/content/asset_modelling/engagements_tests/PRO__assets.md index c7c5cb4a936..f200be364bf 100644 --- a/docs/content/asset_modelling/engagements_tests/PRO__assets.md +++ b/docs/content/asset_modelling/engagements_tests/PRO__assets.md @@ -174,6 +174,55 @@ Because Findings inherit risk, priority, and ownership from their parent Asset, Importantly, Assets are also the primary determining factor in a Finding’s SLA characteristics. Therefore, the SLA of a Findings depends on the SLA configuration of its parent Asset. More information about SLA configurations can be found [here](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas). +## Asset Kinds + +An Asset can declare what kind of thing it is: a repository, a service, a host, a domain, a +container image, a package, a cloud account, a device, or a branch. The kind is optional — +an Asset without one behaves exactly as it always has — and it is descriptive rather than +functional: it does not change permissions, deduplication, SLAs, or reporting scope. What it +does is make a long Asset list readable, by giving each Asset an icon and a label that says +what you are looking at. + +The list of kinds is data, not a fixed set. The kinds DefectDojo ships are marked as system +kinds and cannot be deleted, but their wording and icons can be changed, and you can add your +own kinds for anything your inventory contains that the shipped list does not cover. + +Kinds are available on the Asset itself and through the API at `/api/v2/asset_kinds/` +(read-only) and as the `kind` field on `/api/v2/assets/`. + +## Asset Identity: Aliases + +The same Asset is usually known by different names in different places: a repository id in +GitHub, a project key in your scanner, a hostname in DNS, an image digest in a registry. An +**alias** records one of those identifiers against the Asset it refers to, so DefectDojo can +recognise the Asset from whichever name a source happens to use. + +Each alias has three parts: + +- a **namespace**, naming the system that issued the identifier — `dns`, `oci`, `purl`, `git`, +or a specific Connector configuration; +- a **type**, saying what kind of identifier it is — `external_id`, `hostname`, `image_digest`, +and so on; +- the **value** itself. + +An identifier resolves to exactly one Asset. Two Assets cannot both claim `api.example.com` in +the `dns` namespace, which is what makes an alias a reliable answer to "which Asset is this?" + +Aliases record where they came from. Ones you add yourself are marked as user-asserted and are +never rewritten by automation; Connector sync maintains its own. That means you can correct a +Connector's idea of what an identifier means without the next sync undoing it. + +Aliases are asserted or withdrawn, never edited: there is no update action on the API, because +changing an identifier in place would silently re-point identity with no record of what it used +to mean. To correct one, remove it and add the right one. + +Connector-issued aliases are written by Connector sync rather than by hand, so the API refuses +writes to a `connector:` namespace. Everything else is yours to declare, through +`/api/v2/asset_aliases/`. + +Aliases require `DD_V3_ASSET_ALIASES` to be enabled before they can be created; existing ones +stay readable whether it is on or off. + ## Asset Nesting DefectDojo supports parent-child relationship between two Assets within the same Organization. This can be configured during Asset creation or in the Asset’s settings. diff --git a/docs/content/connectors/upstream/manage_records.md b/docs/content/connectors/upstream/manage_records.md index 41fea5c0b14..3dcf6a275d8 100644 --- a/docs/content/connectors/upstream/manage_records.md +++ b/docs/content/connectors/upstream/manage_records.md @@ -37,6 +37,32 @@ If you have **Auto-Mapping** enabled, new Records will be Mapped to Products aut If you don't have Auto-Mapping enabled, you can make your own decisions about where you want data to flow. Each time the Connector finds a new Vendor-Equivalent Product (via **Discover**), it will add a new Record to your **Unmapped Records** list, and you can then manually assign that Record to a new or existing Product in DefectDojo. +#### How Auto-Mapping chooses the Product + +Auto-Mapping resolves each Record in a fixed order, and stops at the first answer: + +1. **The tool's own identifier.** Every Record stores the identifier the tool uses for the +Vendor-Equivalent Product. Once a Connector has mapped that identifier once, it recognises it +on every later Discover — so renaming the project in the tool, or in DefectDojo, no longer +loses the Mapping or creates a duplicate Product. +2. **The name.** If the Connector has not seen the identifier before, it looks for a Product +whose name matches. When one is found, the Record is mapped to it and the identifier is +recorded, so step 1 answers from then on. +3. **A new Product.** If neither matches, DefectDojo creates one. + +Step 1 requires the identity feature to be enabled (`DD_V3_ASSET_ALIASES`); until then, +Auto-Mapping resolves by name alone, which is the historical behaviour. Enabling it changes +nothing about existing Mappings: the first Discover after it is turned on records identifiers +for the Records you already have, and later runs use them. + +Because names are matched globally, two tools that each report something called `payments` map +to the same Product on first sight. Recording each tool's identifier separately is what stops +that coincidence from becoming permanent — after the first mapping, each Connector follows its +own identifier rather than the shared name. + +Remapping a Record by hand always wins. When you change a Record's Mapping yourself, the +tool's identifier moves with it, and the next sync follows your decision. + #### Mapping - Example Workflow: David has just finished setting up a connector for his BurpSuite tool, and runs a Discover operation. David has Burp set up to scan 4 different 'Sites', and DefectDojo creates a new Record for each of those Sites.