docs: fix the API sample code, do_not_reactivate, Location findings and records screenshots

docs/content/asset_modelling/locations/PRO__location_map.md

@@ -58,15 +58,15 @@ The page has three panels: actions on the left, the canvas in the middle, and de
 Click a node to select it. The right panel then shows:
 
 - **Type** and **Value** of the node.
-- For a single location: **Status Here** and its **Relationship** to the Asset. Users who can edit Locations on the Asset can change the relationship with **Set a Relationship** and **Save**, or remove it with **Clear**.
+- For a single location: **Status Here** and its **Relationship** to the Asset. Users who can edit Locations on the Asset can change the relationship: pick one under **Set a Relationship** and click **Save**. Picking **Clear** and saving removes it. A Reader sees the relationship but cannot change it.
 - For a group: how many **Locations** and **Children** it has.
-- **Findings**: active findings by severity, split into **Direct** (on this node) and **Beneath** (on nodes under it), with a **Total**.
+- **Findings**: active findings by severity, split into **Direct** (on this node) and **Beneath** (on nodes under it), with a **Total**. A group also shows how many **Locations Beneath** it.
 
 With no node selected, the right panel shows a short **Map Overview**. Click the empty canvas or use **Clear the selection** to deselect.
 
 When a single location is selected, the left panel offers two actions:
 
-- **View Findings** opens the active findings recorded on that location.
+- **View Findings** opens the active findings recorded on that location. To see all of its findings, whatever their status, use the **Total Findings** count in the location list (see [Narrowing the Map with the List](#narrowing-the-map-with-the-list)).
 - **Copy Value** copies the full location value to the clipboard.
 
 A group is drawn from several locations, so these actions apply only to a single location.
@@ -88,7 +88,7 @@ Under **Canvas**, **Type Boundaries** turns the dashed regions on or off. The **
 
 ### Adding Locations
 
-**New Location** and **Add Existing** work as they do on the table page, and the map redraws to include what you added. See [Working with URLs](/asset_modelling/locations/pro__working_with_urls/) for the permissions each one needs.
+**New Location** and **Add Existing** work as they do on the table page, and the map redraws to include what you added. They appear only for users who can add or edit Locations on the Asset, so a Reader does not see them. See [Working with URLs](/asset_modelling/locations/pro__working_with_urls/) for the permissions each one needs.
 
 ## Turning the Map Off
 

docs/content/asset_modelling/locations/PRO__locations_overview.md

@@ -91,7 +91,8 @@ Existing parsers have been updated to emit Location data when the feature flag i
 
 ## Where to Go Next
 
-- **Enable the feature** — turn Locations on yourself from the [Feature Flags page](/admin/feature_flags/pro__feature_flags/); no Support request is required.
-- **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).
+- **Enable the feature**: turn Locations on yourself from the [Feature Flags page](/admin/feature_flags/pro__feature_flags/); no Support request is required.
+- **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).
+- **See an Asset's Locations on a map**: see [Location Map](../pro__location_map).
+- **SBOMs and dependencies**: see [Working with SBOMs](../pro__working_with_sboms).

docs/content/asset_modelling/locations/PRO__working_with_urls.md

@@ -22,12 +22,12 @@ When you create or upload a URL, DefectDojo parses it into the structured fields
 
 When the Locations feature is enabled, the navigation exposes:
 
-- **Act > Explore > Attack Surface > Locations** — A list of every Location across both URL and Dependency subtypes. Filter by type, status, Asset, Finding, or tag.
-- **Act > Explore > Attack Surface > URLs** — A scoped list of URL Locations only. This is the closest analogue to the old Endpoints page.
+- **Act > Explore > Attack Surface > Locations**: A list of every Location across both URL and Dependency subtypes. Filter by type, status, Asset, Finding, or tag.
+- **Act > Explore > Attack Surface > URLs**: A scoped list of URL Locations only. This is the closest analogue to the old Endpoints page.
 - **New URL** on the URLs list — A form to create a single URL with structured fields, tags, and optional Asset/Finding associations.
-- **Locations on an Asset** — From any Asset, the **Locations** tab shows the URLs and Dependencies attached to that Asset, with status counts and quick actions.
-- **The Location page** — Click a Location's value in any list, or choose **View Location** from its row menu, to open the page for that Location. It is the counterpart of the old Endpoint page: the Location's type, value, tags and overall status; when it was first and last seen; each Asset that references it, in a table you can search, sort and filter by Asset, status, relationship, and first or last seen date; its **Custom Fields**; and every Finding found there.
-- **Custom Fields on a Location** — The name and value pairs the Endpoint page called metadata appear in the same **Custom Fields** card the Endpoint page uses. A Location is shared by every Asset that recorded the same value, so a field can belong to one Asset. The card shows the Asset under each value, adds the Asset to a tab's name when two Assets use the same field name, and only shows fields for Assets you can view. Add a field with the **+** on the card or **Add Custom Field** in the Location's menu, and choose the Asset it belongs to, or none. Edit or delete a field from its gear menu. Changing a field needs edit permission on the Location, and on its Asset when the field belongs to one.
+- **Locations on an Asset**: From any Asset, the **Locations** tab shows the URLs and Dependencies attached to that Asset, with status counts and quick actions.
+- **The Location page**: Click a Location's value in any list, or choose **View Location** from its row menu, to open the page for that Location. It is the counterpart of the old Endpoint page: the Location's type, value, tags and overall status; when it was first and last seen; each Asset that references it, in a table you can search, sort and filter by Asset, status, relationship, and first or last seen date; its **Custom Fields**; and **Affected Open Findings**, the active Findings recorded there. That table always filters on Status Active. To see every Finding on a Location, whatever its status, open a list of Locations (an Asset's Locations table, **Choose Locations** on the [Location Map](../pro__location_map), or **All Locations**) and click the location's count in the **Total Findings** column: it opens the Findings list filtered to that Location. **Mitigated Findings** does the same for the Findings recorded there as Mitigated, False Positive, Risk Accepted or Out of Scope.
+- **Custom Fields on a Location**: The name and value pairs the Endpoint page called metadata appear in the same **Custom Fields** card the Endpoint page uses. A Location is shared by every Asset that recorded the same value, so a field can belong to one Asset. The card shows the Asset under each value, adds the Asset to a tab's name when two Assets use the same field name, and only shows fields for Assets you can view. Add a field with the **+** on the card or **Add Custom Field** in the Location's menu, and choose the Asset it belongs to, or none. Edit or delete a field from its gear menu. Changing a field needs edit permission on the Location, and on its Asset when the field belongs to one.
 
 ![image](images/PRO_Location_Page.png)
 

docs/content/automation/api/api-v2-docs.md

@@ -116,82 +116,76 @@ Plan the change before making it: pick a window, ask token owners to rotate firs
 
 ## Sample Code
 
-Here are some simple python examples and their results produced against
-the `/users` endpoint:
+Here are two simple Python examples against the `/findings` endpoint. Any user with an API token can run them: the response holds only the findings that user has permission to view.
+
+The first lists findings and prints each one's id and title:
 
 {{< highlight python >}}
 import requests
 
-url = 'http://127.0.0.1:8000/api/v2/users'
-headers = {'content-type': 'application/json',
-            'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'}
-r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed
+url = 'https://defectdojo.example.com/api/v2/findings/'
+headers = {
+    'content-type': 'application/json',
+    'Authorization': 'Token <Your API Token>',
+}
+r = requests.get(url, headers=headers, verify=True)  # set verify to False if the SSL certificate is self-signed
+r.raise_for_status()
 
-for key, value in r.__dict__.items():
-  print(f"'{key}': '{value}'")
-  print('------------------')
+for finding in r.json()['results']:
+    print(finding['id'], finding['title'])
 {{< /highlight >}}
 
-This code will return the list of all the users defined in DefectDojo.
-The json object result looks like:
+The output is one line per finding:
 
-{{< highlight json >}}
-    [
-        {
-          "first_name": "Tyagi",
-          "id": 22,
-          "last_login": "2019-06-18T08:05:51.925743",
-          "last_name": "Paz",
-          "username": "dev7958"
-        },
-        {
-          "first_name": "saurabh",
-          "id": 31,
-          "last_login": "2019-06-06T11:44:32.533035",
-          "last_name": "",
-          "username": "saurabh.paz"
-        }
-    ]
+{{< highlight text >}}
+101 Example SQL Injection
+102 Example Cross-Site Scripting
 {{< /highlight >}}
 
-Here is another example against the `/users` endpoint, this
-time we will filter the results to include only the users whose user
-name includes `jay`:
+The second filters the list to active findings of High severity, using query parameters. Severity values are case-sensitive: use `Critical`, `High`, `Medium`, `Low` or `Info`.
 
 {{< highlight python >}}
 import requests
 
-url = 'http://127.0.0.1:8000/api/v2/users/?username__contains=jay'
-headers = {'content-type': 'application/json',
-            'Authorization': 'Token c8572a5adf107a693aa6c72584da31f4d1f1dcff'}
-r = requests.get(url, headers=headers, verify=True) # set verify to False if ssl cert is self-signed
+url = 'https://defectdojo.example.com/api/v2/findings/'
+headers = {
+    'content-type': 'application/json',
+    'Authorization': 'Token <Your API Token>',
+}
+params = {'severity': 'High', 'active': 'true'}
+r = requests.get(url, headers=headers, params=params, verify=True)  # set verify to False if the SSL certificate is self-signed
+r.raise_for_status()
 
-for key, value in r.__dict__.items():
-  print(f"'{key}': '{value}'")
-  print('------------------')
+print(r.json())
 {{< /highlight >}}
 
-The json object result is:
+List endpoints are paginated. The response holds the total `count`, the URLs of the `next` and `previous` pages (`null` when there are none), and the current page of findings in `results`. `prefetch` stays empty unless you ask for related objects with the `prefetch` parameter. Each finding carries every field of the Finding model; the example below is trimmed to a few of them:
 
 {{< highlight json >}}
-[
-    {
-        "first_name": "Jay",
-        "id": 22,
-        "last_login": "2015-10-28T08:05:51.925743",
-        "last_name": "Paz",
-        "username": "jay7958"
-    },
-    {
-        "first_name": "",
-        "id": 31,
-        "last_login": "2015-10-13T11:44:32.533035",
-        "last_name": "",
-        "username": "jay.paz"
-    }
-]
+{
+    "count": 2,
+    "next": null,
+    "previous": null,
+    "prefetch": {},
+    "results": [
+        {
+            "id": 101,
+            "title": "Example SQL Injection",
+            "severity": "High",
+            "active": true
+        },
+        {
+            "id": 103,
+            "title": "Example Server-Side Request Forgery",
+            "severity": "High",
+            "active": true
+        }
+    ]
+}
 {{< /highlight >}}
 
+A page holds 25 results by default. Set `limit` to change the page size and `offset` to start further in, or follow the `next` URL until it is `null` to read every page.
+
 See [Django Rest Framework\'s documentation on interacting with an
 API](https://www.django-rest-framework.org/) for
 additional examples and tips.
@@ -313,7 +307,7 @@ A reimport can be performed by specifying the names of these entities in the API
 
 When `auto_create_context` is `True`, the Organization, Asset and Engagement will be created if they do not already exist. Make sure your user has sufficient [permissions](/admin/user_management/about_perms_and_roles/) to create an Asset/Organization.
 
-When `do_not_reactivate` is `True`, the importing/reimporting will ignore uploaded active findings and not reactivate previously closed findings, while still creating new findings if there are new ones. You will get a note on the finding to explain that it was not reactivated for that reason.
+When `do_not_reactivate` is `True`, a reimport keeps a closed finding closed when it appears in the report again, instead of reactivating it, and adds a note to that finding saying it was not reactivated. New findings in the report are still created, and findings that are already open are processed as usual. A first import has no existing findings to reactivate, so the option only changes a reimport.
 
 A reimport will automatically select the latest test inside the provided engagement that satisfies the provided `scan_type` and (optionally) provided `test_title`.