[docs] locations (pro feature), maintenance

docs/assets/scss/common/_custom.scss

@@ -210,6 +210,25 @@ h1, h2, h3, h4, h5, h6,
   display: none;
 }
 
+// Pro badge — appears next to sidebar items with audience: pro
+// Box height is `1lh` so it equals one line-height of the surrounding text.
+.pro-badge {
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 1lh;
+  margin-left: 0.5em;
+  padding: 0 0.45em;
+  border: 1px solid #F2561D;
+  border-radius: 0.25rem;
+  background-color: rgba(#F2561D, 0.72);
+  color: #fff;
+  font-size: 0.7em;
+  font-weight: 500;
+  vertical-align: middle;
+  white-space: nowrap;
+}
+
 // ============================================================
 // Cards
 // ============================================================
@@ -419,6 +438,12 @@ h1, h2, h3, h4, h5, h6,
     border-color: #F2762E;
   }
 
+  // Pro badge in dark mode
+  .pro-badge {
+    background-color: rgba(#F2561D, 0.85);
+    border-color: #F2762E;
+  }
+
   // Selection color in dark mode
   ::selection {
     background-color: rgba(#82B0D9, 0.3);

docs/content/asset_modelling/hierarchy/OS__sla_configuration.md → docs/content/asset_modelling/OS_hierarchy/OS__sla_configuration.md

@@ -8,7 +8,7 @@ aliases:
 ---
 Each Product in DefectDojo can have its own Service Level Agreement (SLA) configuration, which represents the days your organization has to remediate or otherwise manage a Finding.
 
-SLA can be set based on either **[Finding Severity](/asset_modelling/hierarchy/product_hierarchy/#findings)** or **[Finding Risk](/asset_modelling/hierarchy/pro__priority_sla/)** (in DefectDojo Pro).
+SLA can be set based on either **[Finding Severity](/asset_modelling/os_hierarchy/product_hierarchy/#findings)** or **[Finding Risk](/asset_modelling/pro_hierarchy/priority_sla/)** (in DefectDojo Pro).
 
 ![image](images/sla_multiple.png)
 

docs/content/asset_modelling/OS_hierarchy/_index.md

@@ -0,0 +1,11 @@
+---
+title: "Product Hierarchy"
+audience: opensource
+date: 2021-02-02T20:46:29+01:00
+draft: false
+type: docs
+weight: 3
+sidebar:
+  collapsed: false
+exclude_search: true
+---

docs/content/asset_modelling/hierarchy/_index.md → docs/content/asset_modelling/PRO_hierarchy/_index.md

@@ -3,6 +3,7 @@ title: "Asset Hierarchy"
 date: 2021-02-02T20:46:29+01:00
 draft: false
 type: docs
+audience: pro
 weight: 3
 sidebar:
   collapsed: false

docs/content/asset_modelling/hierarchy/PRO__assets_organizations.md → docs/content/asset_modelling/PRO_hierarchy/assets_organizations.md

@@ -82,7 +82,7 @@ Core Application [Organization]
     └── nginx
 ```
 
-In this diagram, every element under "Core Application" could be recorded as a separate Asset, with unique business criticality (see: [Priority & Risk](/asset_modelling/hierarchy/pro__priority_sla/#prioritization-engines/)), RBAC, and corresponding Engagements and Tests.  You could continue to test, and store results, on the parent Asset (for example, `webapp-backend`), but you could also run isolated testing on a particular child Asset (for example, `database`).
+In this diagram, every element under "Core Application" could be recorded as a separate Asset, with unique business criticality (see: [Priority & Risk](/asset_modelling/pro_hierarchy/priority_sla/#prioritization-engines/)), RBAC, and corresponding Engagements and Tests.  You could continue to test, and store results, on the parent Asset (for example, `webapp-backend`), but you could also run isolated testing on a particular child Asset (for example, `database`).
 
 ### Pen Tests: Isolated RBAC
 

docs/content/asset_modelling/hierarchy/PRO__priority_sla.md → docs/content/asset_modelling/PRO_hierarchy/priority_sla.md

@@ -197,7 +197,7 @@ Note that when a Product's Prioritization Engine is changed, or a Prioritization
 
 Each Product in DefectDojo can have its own Service Level Agreement (SLA) configuration, which represents the days your organization has to remediate or otherwise manage a Finding.
 
-SLA can be set based on either **[Finding Severity](/asset_modelling/hierarchy/product_hierarchy/#findings)** or **[Finding Risk](/asset_modelling/hierarchy/pro__priority_sla/)** (in DefectDojo Pro).
+SLA can be set based on either **[Finding Severity](/asset_modelling/os_hierarchy/product_hierarchy/#findings)** or **[Finding Risk](/asset_modelling/pro_hierarchy/priority_sla/)** (in DefectDojo Pro).
 
 ![image](images/sla_multiple.png)
 

docs/content/asset_modelling/PRO_hierarchy/product_health_grade.md

@@ -0,0 +1,31 @@
+---
+title: "Product Health Grade"
+description: "How DefectDojo calculates a Product Health Grade"
+aliases:
+  - /en/working_with_findings/organizing_engagements_tests/product_health_grade
+---
+DefectDojo can calculate a grade for your Products based on the amount of Findings contained within. Grades are ranked from A \- F.
+
+Note that only Active \& Verified Findings contribute to a Product Grade \- unverified Findings will not have an impact.
+
+## Product Grade Calculation
+
+Every Product Grade starts at 100 (with no Findings).
+
+Grade calculation starts by looking at the highest **Severity** level of a Finding in a Product, and reducing the Product Health to a base level.
+
+| **Highest Severity Level of a Finding** | **Maximum Grade** |
+| --- | --- |
+| **Critical** | **40** |
+| **High** | **60** |
+| **Medium** | **80** |
+| **Low** | **95** |
+
+Further points are then deducted from the Grade for each additional Finding:
+
+| **Severity Level of an additional Finding** | **Grade Reduced by** |
+| --- | --- |
+| **Critical** | **5** |
+| **High** | **3** |
+| **Medium** | **2** |
+| **Low** | **1** |

docs/content/asset_modelling/locations/PRO__locations_overview.md

@@ -0,0 +1,79 @@
+---
+title: "Locations Overview"
+description: "What Locations are and why they replace Endpoints"
+audience: pro
+weight: 1
+---
+
+**Locations** are a new asset-modelling tool in DefectDojo Pro. They replace the legacy **Endpoints** model and absorb the previous **Components** (library) data, giving DefectDojo a single, polymorphic way to describe *where* a Finding lives — whether that's a URL, a software dependency from an **SBOM**, or, in the future, a **cloud resource ID**, **container image**, or **code repository**.
+
+Locations are currently in **Beta** and will need to be enabled on your instance. To enable Locations on your instance, contact [support@defectdojo.com](mailto:support@defectdojo.com).
+
+## Why Replace Endpoints?
+
+The original Endpoints model was built around URLs and IP addresses — it carried web-app fields like `protocol`, `host`, `port`, `path`, and a fixed status table that was tightly coupled to Findings. Three problems followed:
+
+1. **Limited fidelity.** Endpoints could not cleanly describe non-URL assets such as third-party libraries, container images, or cloud resources, even though scanners increasingly produce findings about those things.
+2. **Performance ceiling.** Per-Finding Endpoint_Status rows and the URL-shaped schema did not scale well at large customer volumes.
+3. **Components were second-class.** Software libraries lived only as denormalised fields on a Finding, so a library could not exist independently of a vulnerability — making true SBOM management impossible.
+
+Locations fix all three by introducing a **base `Location` object** with a typed payload, plus dedicated **subtypes** for each asset shape. The MVP ships two subtypes:
+
+- **URL Locations** — functional equivalent of the old Endpoints, with the same protocol/host/port/path/query/fragment fields.
+- **Dependency Locations** — software libraries identified by [Package URL (pURL)](https://github.com/package-url/purl-spec), used to model SBOM contents.
+
+Future Location types under consideration include cloud provider resource IDs (AWS ARN, Azure Resource ID, GCP Full Resource Name), container images (registry/repository:tag and SHA256 fingerprints), and code repositories.
+
+## Key Concepts
+
+### Locations and Subtypes
+
+A **Location** is the shared parent. It carries:
+
+- A `Location Type` (e.g. `"url"`, `"dependency"`)
+- A canonical `Location Value` string used for display, search, and de-duplication
+- `Tags` and inherited tags from the parent Asset
+- Metadata (custom key/value pairs)
+
+A **subtype** (URL or Dependency) holds the structured fields specific to that kind of location. URLs and Dependencies always live alongside a parent Location object; the subtype's `Location Value` is generated from its structured fields.
+
+### References
+
+Locations are not directly attached to Products or Findings. Instead, two **Reference** objects link them:
+
+- **Asset References** — relationships the Location has to Assets (e.g. `libFoo` is *owned by* Asset 6, *used by* Asset 9). Each reference carries a status (`Active` or `Mitigated`) and an optional **relationship** ("Used By" or "Owned By").
+- **Finding References** — relationships the Location has to Findings. Each reference carries a richer status (`Active`, `Mitigated`, `False Positive`, `Risk Accepted`, `Out of Scope`) plus the auditor and audit time.
+
+This separation is what allows a library to exist on a Product *without* needing a Finding — a missing capability in the old Components model.
+
+### Auto-Association at Import Time
+
+When a parser produces a Finding that references a URL or library, the importer:
+
+1. Looks up an existing Location matching the URL or pURL; if none exists, it creates one.
+2. Creates a Finding Reference linking the Finding to the Location with status `Active`.
+3. Creates (or reuses) an Asset Reference so the Location also lives on the parent Asset.
+
+Existing parsers have been updated to emit Location data when the feature flag is on, and to fall back to the legacy Endpoint model when it is off. No reconfiguration is needed when Locations are enabled — the next import will route through the Locations pipeline automatically.
+
+## What's in the MVP
+
+| Capability | Status |
+| --- | --- |
+| Foundational `Location`, `URL`, `Dependency` models | Shipped |
+| REST API for Locations and References | Shipped (read-only `Location`, full CRUD on References) |
+| Endpoint API read-compatibility shim | Shipped |
+| Endpoint → URL one-way migration command | Shipped |
+| Parser updates (URLs and dependencies) | Shipped for the major parsers |
+| SBOM upload (CycloneDX, SPDX v2/v3) | Shipped via `/api/v2/sbom-import/` |
+| Pro UI for Locations, URLs, Dependencies | Shipped (Beta) |
+| pURL search/filter | Shipped |
+| License tracking on dependencies | Partial (`license_expression` field) |
+| SWID Tag SBOM format | Not in MVP |
+
+## Where to Go Next
+
+- **Enable the feature** — contact [support@defectdojo.com](mailto:support@defectdojo.com) to turn Locations on for your instance.
+- **Migrate from Endpoints** — see [Migrating from Endpoints](../pro__migrating_from_endpoints) for what the migration preserves, and how the legacy Endpoint API behaves afterward.
+- **Day-to-day URL workflows** — see [Working with URLs](../pro__working_with_urls).
+- **SBOMs and dependencies** — see [Working with SBOMs](../pro__working_with_sboms).

docs/content/asset_modelling/locations/PRO__migrating_from_endpoints.md

@@ -0,0 +1,70 @@
+---
+title: "Migrating from Endpoints"
+description: "What happens when you migrate existing Endpoint data to Locations"
+audience: pro
+weight: 3
+---
+
+When you enable Locations on an existing DefectDojo Pro instance, the data already stored as Endpoints needs to be carried forward into the new Locations model. This page describes migration, what it preserves, and how the legacy Endpoint API behaves once the migration has run.
+
+Note that migration is **one-way**. There is no automated rollback path that re-creates Endpoints from Locations.
+
+## What the Migration Does
+
+For every existing Endpoint, migration will:
+
+1. **Creates a URL Location** (or re-uses an existing one) using the Endpoint's `protocol`, `userinfo`, `host`, `port`, `path`, `query`, and `fragment` fields. The new URL is automatically attached to a parent `Location` object.
+2. **Carries over tags.** Every tag on the Endpoint is added to the Location's tag set.
+3. **Carries over metadata.** Each `DojoMeta` row attached to the Endpoint is re-pointed at the new Location.
+4. **Creates a `LocationProductReference`** so the URL appears under the correct Asset (Product).
+5. **Creates a `LocationFindingReference` for every `Endpoint_Status`**:
+
+   | Endpoint_Status flag | Resulting Location status |
+   | --- | --- |
+   | `risk_accepted=True` | **Risk Accepted** |
+   | `false_positive=True` | **False Positive** |
+   | `out_of_scope=True` | **Out of Scope** |
+   | `mitigated=True` | **Mitigated** |
+   | (none of the above) | **Active** |
+
+   The mapping is order-sensitive: the *first* matching flag wins. This intentionally collapses the old multi-flag combinations down to the single canonical status that Locations use.
+
+
+## What the Migration Does Not Do
+
+- It does **not** create Dependency Locations. SBOM and library data has never existed as Endpoints, so there is nothing for the migration to convert. To populate Dependencies, upload SBOMs (see [Working with SBOMs](../pro__working_with_sboms)) or re-run scans with parsers that emit dependency data.
+- It does **not** delete the original Endpoint or Endpoint_Status rows. They remain in the database to back the read-only legacy API. They are not used by the new UI or by imports after the feature is enabled.
+
+## Endpoint API After Migration
+
+Once Locations is enabled, the legacy Endpoint API enters a **read-compatibility** mode designed to keep existing automations working without code changes — but only for read traffic.
+
+### What still works
+
+- `GET /api/v2/endpoints/` — Returns rows that *look like* Endpoints but are actually projected from Location Product Reference rows joined to URL Locations. The familiar fields (`protocol`, `host`, `port`, `path`, `query`, `fragment`, `tags`, `product`, `active_finding_count`) are all present.
+- `GET /api/v2/endpoints/{id}/` — Single-Endpoint retrieval works the same way. The `id` is the original Endpoint ID and is preserved through the migration via the Asset Reference mapping.
+- `GET /api/v2/endpoint_status/` and `GET /api/v2/endpoint_status/{id}/` — Returns rows projected from `LocationFindingReference`. The legacy `mitigated`, `false_positive`, `out_of_scope`, and `risk_accepted` boolean fields are reconstructed.
+- Filtering by `protocol`, `host`, `port`, `path`, `query`, `fragment`, `product`, and `tag(s)` continues to work.
+- The `generate_report` action on individual Endpoints continues to work.
+
+### What returns 403
+
+- `POST`, `PUT`, `PATCH`, and `DELETE` on `/api/v2/endpoints/` and `/api/v2/endpoint_status/` all return `HTTP 403` with the body:
+
+  > Writes to this endpoint are deprecated when V3_FEATURE_LOCATIONS is enabled
+
+  Clients that write Endpoint data must move to the new Reference endpoints (`POST /api/v2/location_findings/`, `POST /api/v2/location_products/`) and to the URL endpoint (`POST /api/v2/urls/`).
+
+### Behavioural Differences to Watch For
+
+A few things behave differently from the original Endpoint API:
+
+- **Single status instead of flags.** Locations have one status at a time. If your code relied on a Finding being *both* `mitigated=True` *and* `false_positive=True` simultaneously on an Endpoint_Status, that is no longer representable — the migration picks the highest-priority flag (the order shown in the table above).
+- **`endpoint` field on Endpoint_Status.** The legacy `endpoint` field is reconstructed by looking up the matching Asset Reference. In rare cases where a Finding's Asset no longer matches its Location's Asset references, this field may be null.
+- **Pagination and ordering.** Available ordering fields on the read-compat shim are `host`, `product`, `id`, and `active_finding_count`. If your client orders by another field, switch to one of these or move to the new Locations endpoints.
+
+## Tags and Metadata
+
+Tags applied to Endpoints become tags on the Location object (not on the URL subtype). Tag-based filters in the legacy API continue to match.
+
+Endpoint metadata is re-pointed at the Location during migration. Existing automations that read metadata via `/api/v2/endpoint_meta/` should continue to work; new metadata should be written through the Location endpoints.