add locations docs

Author: paulOsinski

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.

docs/content/asset_modelling/locations/PRO__working_with_sboms.md

@@ -0,0 +1,107 @@
+---
+title: "Working with SBOMs"
+description: "Manage software dependencies and SBOMs as Locations"
+audience: pro
+weight: 5
+---
+
+DefectDojo Pro models software libraries as **Dependency Locations**. A Dependency is a Location subtype identified by a [Package URL (pURL)](https://github.com/package-url/purl-spec) and intended to represent a single library or package — `org.apache.logging.log4j:log4j-core@2.17.0`, `pypi/django@5.0.2`, `npm/react@18.2.0`, and so on.
+
+Dependencies replace the previous **Components** model, which was attached only to Findings. With Locations, libraries can exist independently of any vulnerability — you can upload an SBOM to an Asset and then let Findings auto-attach to the dependencies they reference as scans come in.
+
+## What a Dependency Holds
+
+Every Dependency is uniquely identified by a pURL, decomposed into atomic fields you can search and filter on:
+
+| Field | Meaning | Example |
+| --- | --- | --- |
+| `purl_type` | Library ecosystem | `npm`, `pypi`, `maven`, `cargo`, `nuget`, `gem` |
+| `namespace` | Vendor or organisation | `org.apache.logging` |
+| `name` | Library name | `log4j-core` |
+| `version` | Specific version | `2.17.0` |
+| `qualifiers` *(optional)* | Implementation details | `arch=amd64` |
+| `subpath` *(optional)* | Path within an archive or monorepo | `src/lib/foo` |
+| `artifact_hashes` *(optional)* | Fingerprints | SHA256 sums |
+| `license_expression` *(optional)* | SPDX license expression | `Apache-2.0`, `MIT` |
+| `file_path` *(optional)* | Where the library was found in the project | `package-lock.json` |
+
+This atomic decomposition is what makes pURL-based search useful: you can ask *"all `pypi` packages in the `django` namespace at version 4.x"* and DefectDojo can answer that without parsing a free-text string.
+
+## Owned-By vs Used-By
+
+When a Dependency is associated with an Asset, the Asset Reference carries an optional **relationship** describing *how* the library belongs to the Asset:
+
+- **`owned_by`** — *"this library is owned by this Asset"*. Use this for first-party libraries an Asset publishes or maintains.
+- **`used_by`** — *"this library is used by this Asset"*. Use this for third-party dependencies an Asset consumes.
+
+The same library can be `owned_by` one Asset and `used_by` several others, which is exactly the relationship you need to answer *"who consumes the package my team publishes?"* during vulnerability triage.
+
+## Uploading an SBOM
+
+To populate Dependencies in bulk, upload an SBOM file against a Product. The endpoint is:
+
+```
+POST /api/v2/sbom-import/
+```
+
+| Field | Description |
+| --- | --- |
+| `product` | The target Product (Asset) ID |
+| `file` | The SBOM file |
+| `scan_type` | The SBOM format — see supported formats below |
+| `replace` *(optional)* | If `true`, stale Product associations not backed by an existing Finding reference are removed. Default: `false` (cumulative) |
+
+The importer parses the file, extracts `Dependency` records, deduplicates them against existing Locations (creating new ones as needed), and creates Asset References linking each Dependency to the Product. The Pro UI exposes the same upload flow — see the **Upload SBOM** action on a Product's Locations tab.
+
+### Supported Formats
+
+The MVP ships parsers for the two dominant SBOM formats:
+
+- **CycloneDX** — JSON and XML
+- **SPDX** — JSON (v2 and v3), XML, and tag-value
+
+SWID Tag format is not yet supported.
+
+### Replace vs Append
+
+By default, repeated uploads are **additive**: dependencies that already exist on the Asset are kept, new ones are added, and nothing is removed. This matches the typical workflow of incremental SBOM updates.
+
+Set `replace=true` to prune. When replace mode is on, after a successful import the importer removes Product associations that were not present in the new SBOM **and** are not currently referenced by an active Finding. References tied to active Findings are preserved even in replace mode, so you do not lose vulnerability context just because a new SBOM omits a package.
+
+## Findings That Reference Libraries
+
+When a parser ingests a vulnerability tied to a library — for example, an SCA tool reporting `CVE-2021-44228` against `log4j-core@2.14.1` — the importer:
+
+1. Looks up an existing Dependency Location by pURL, or creates a new one.
+2. Creates a `LocationFindingReference` linking the Finding to the Dependency with status **Active**.
+3. Creates a `LocationProductReference` so the Dependency also appears on the parent Product, if it isn't already.
+
+Because Findings and SBOM uploads share the same underlying Dependency objects, a Finding ingested *before* an SBOM upload will be retroactively visible in the SBOM view, and vice versa.
+
+## REST API
+
+| Task | Endpoint |
+| --- | --- |
+| Upload an SBOM | `POST /api/v2/sbom-import/` |
+| List Dependencies | `GET /api/v2/dependencies/` |
+| Create a Dependency manually | `POST /api/v2/dependencies/` |
+| List Dependency Locations | `GET /api/v2/location/?location_type=dependency` |
+| Link a Dependency to a Finding | `POST /api/v2/location_findings/` |
+| Link a Dependency to a Product (with `owned_by` / `used_by`) | `POST /api/v2/location_products/` |
+
+Filters on `/api/v2/dependencies/` include the pURL component fields, tags, and ordering on `name`, `version`, and active-finding count.
+
+## In the Pro UI
+
+When Locations is enabled, the navigation exposes:
+
+- **Locations / Dependencies** — Global list of every Dependency across the instance, with pURL filters.
+- **Locations on a Product/Asset** — Per-Asset view that shows both URLs and Dependencies, with the **Upload SBOM** action surfaced on the Dependencies tab.
+- **New Dependency** — Form to create a single library by entering its pURL components manually.
+- **Findings detail** — A Finding that touches a library shows its Dependency Locations alongside any URL Locations, so you can see *"this CVE affects `log4j-core@2.14.1` on Asset 6 and Asset 9"* in one place.
+
+## What's Not in the MVP
+
+- **SWID Tag SBOM format** — Not parsed. CycloneDX or SPDX is required.
+- **License risk scoring** — The `license_expression` field is captured when present in the SBOM, but DefectDojo does not yet flag findings on license incompatibility. License-based reporting is on the roadmap as a follow-up to the Locations MVP.
+- **Container image and cloud resource Locations** — Future Location subtypes. For now, libraries discovered inside a container image are recorded as Dependencies; the container image itself is not yet a first-class Location.