Merge pull request #2093 from SEKOIA-IO/fix-broken-links

Fix broken links, anchors and images and enforce CI `mkdocs build --strict` to fail on broken internal links

.github/workflows/deploy-public-website.yaml

@@ -49,7 +49,7 @@ jobs:
 
       - name: Build site
         run: |
-          poetry run python -m mkdocs build
+          poetry run python -m mkdocs build --strict
 
       - name: Install Swift
         run: |

.github/workflows/preview.yaml

@@ -46,7 +46,7 @@ jobs:
 
       - name: Build site
         run: |
-          poetry run python -m mkdocs build
+          poetry run python -m mkdocs build --strict
 
       - name: Save PR number
         run: |

README.md

@@ -13,8 +13,14 @@ Once your pull request is created, a SEKOIA.IO reviewer will take responsibility
 The service relies on the [MkDocs](https://www.mkdocs.org/) Python framework helped by a customized [Material theme](https://squidfunk.github.io/mkdocs-material/). To serve the documentation on the port `8000` of your computer, you should create a Python virtual environment, install the few requirements detailed in `pyproject.toml` and trigger the execution of the MkDocs server:
 
 ```shell
-$ mkdir -p docs/stylesheets/ && sassc src/sekoiaio.scss docs/stylesheets/sekoiaio.css
 $ pip install poetry
 $ poetry install
-$ poetry run mkdocs serve
+$ poetry run mkdocs serve --strict
 ```
+
+## Guidelines
+
+* You may use absolute links and images such as `[caption](/folder/page.md#anchor)` or `![!someimage](/folder/image.png)`, they will be interpreted as relative to the `docs/` folder. So the example link would point to `docs/folder/page.md` which must exist in the repo. `mkdocs serve --strict` will help you catching any broken link
+* When you want to point to the developer documentation, please use full URLs, such as `[delete_playbook_endpoint](https://docs.sekoia.io/xdr/develop/rest_api/playbooks/#tag/Playbooks/operation/delete_playbook_resource)`, because the API documentation is rendered client-side via ReDoc out of OpenAPI specs retrieved from app.sekoia.io platform's API
+* Always include the `.md` extension when linking to markdown files in the repo: `[link](/integration/example/index.md)` is okay, whereas `[link](/integration/example/)` or `[link](/integration/example/index)` won't work.
+* All links to internal pages and anchors are strictly validated by the CI (via `mkdocs build --strict`) to spot any broken link. Therefore, please refrain as much as possible from using full URLs to point to internal pages, as they won't be covered by automated broken link verification.

_shared_content/automate/actions.md

@@ -8,7 +8,7 @@ An `Action` helps you execute specific tasks depending on your needs. There are
 - Extract data: [data collection enrichers](#data-collection)
 - Connect and use [third-party applications](#third-party-applications)
 - Set up [notifications](#notifications)
-- Use [helpers](#Helpers) to build your own actions
+- Use [helpers](#helpers) to build your own actions
 
 The Actions Library lists all available actions in playbooks with their detailed configuration.
 
@@ -18,11 +18,11 @@ The Actions Library lists all available actions in playbooks with their detailed
 
 | Name | Description |
 | --- | --- |
-| [Get Event Field Common Values](/integration/action_library/generic/sekoia-io/#get-event-field-common-values) | Retrieve the most common values of an ECS field based on the time window |
-| [List Assets](/integration/action_library/generic/sekoia-io/#list-assets) | Retrieve detailed information about assets based on a filter |
-| [Search Alerts](/integration/action_library/generic/sekoia-io/#search-alerts) | Retrieve detailed information about alerts (such as the urgency, name of the rule, etc… except events) based on a filter. |
-| [Get Alert](/integration/action_library/generic/sekoia-io/#get-alert) | Retrieve detailed alert information such as the urgency, name of the rule, pattern, etc… except events. |
-| [Get Events](/integration/action_library/generic/sekoia-io/#get-events) | Retrieve events based on a search. This action is equivalent to a search on the event page and takes into consideration 3 parameters: a query with filters (`source.ip=xx.xxx.xx`), and earliest time/latest time: two dates to determine the date range of the search. |
+| [Get Event Field Common Values](/integration/action_library/sekoia-io.md#get-event-field-common-values) | Retrieve the most common values of an ECS field based on the time window |
+| [List Assets](/integration/action_library/sekoia-io.md#list-assets) | Retrieve detailed information about assets based on a filter |
+| [Search Alerts](/integration/action_library/sekoia-io.md#search-alerts) | Retrieve detailed information about alerts (such as the urgency, name of the rule, etc… except events) based on a filter. |
+| [Get Alert](/integration/action_library/sekoia-io.md#get-alert) | Retrieve detailed alert information such as the urgency, name of the rule, pattern, etc… except events. |
+| [Get Events](/integration/action_library/sekoia-io.md#get-events) | Retrieve events based on a search. This action is equivalent to a search on the event page and takes into consideration 3 parameters: a query with filters (`source.ip=xx.xxx.xx`), and earliest time/latest time: two dates to determine the date range of the search. |
 
 !!!note
 	`Get Events` can be used to retrieve events from an alert. Events associated to an alert contain the key `alert_short_ids` with the value of the ID of the alert.
@@ -31,15 +31,15 @@ The Actions Library lists all available actions in playbooks with their detailed
 
 | Name | Description |
 | --- | --- |
-| [Create an asset](/integration/action_library/generic/sekoia-io/#create-asset) | Create an asset |
-| [Delete an asset](/integration/action_library/generic/sekoia-io/#delete-an-asset) | Delete an asset |
-| [Add attribute to asset](/integration/action_library/generic/sekoia-io/#add-attribute-to-asset) | Add attribute to asset |
-| [Add key to asset](/integration/action_library/generic/sekoia-io/#add-key-to-asset) | Add key to asset |
-| [Edit alert](/integration/action_library/generic/sekoia-io/#edit-alert) | Edit an alert details such as the urgency or the alert category |
-| [Comment alert](/integration/action_library/generic/sekoia-io/#comment-alert) | Add a comment to the alert |
-| [Update alert status](/integration/action_library/generic/sekoia-io/#update-alert-status) | Change the status of an alert |
-| [Push Events to Intake](/integration/action_library/generic/sekoia-io/#push-events-to-intake) | Push one or more events to an Intake |
-| [Attach Alerts to Case](/integration/action_library/generic/sekoia-io/#attach-alerts-to-case) | Attach one or more alerts to a case. |
+| [Create an asset](/integration/action_library/sekoia-io.md#create-asset) | Create an asset |
+| [Delete an asset](/integration/action_library/sekoia-io.md#delete-an-asset) | Delete an asset |
+| [Add attribute to asset](/integration/action_library/sekoia-io.md#add-attribute-to-asset) | Add attribute to asset |
+| [Add key to asset](/integration/action_library/sekoia-io.md#add-key-to-asset) | Add key to asset |
+| [Edit alert](/integration/action_library/sekoia-io.md#edit-alert) | Edit an alert details such as the urgency or the alert category |
+| [Comment alert](/integration/action_library/sekoia-io.md#comment-alert) | Add a comment to the alert |
+| [Update alert status](/integration/action_library/sekoia-io.md#update-alert-status) | Change the status of an alert |
+| [Push Events to Intake](/integration/action_library/sekoia-io.md#push-events-to-intake) | Push one or more events to an Intake |
+| [Attach Alerts to Case](/integration/action_library/sekoia-io.md#attach-alerts-to-case) | Attach one or more alerts to a case. |
 
 
 #### How to update an alert status
@@ -58,53 +58,53 @@ To update an alert status, you need to copy the `status_uuid` corresponding to t
 
 To get notified, you can rely on these tools:
 
-- [Mandrill](/integration/action_library/applicative/mandrill.md): Send Message
-- [Mattermost](/integration/action_library/applicative/mattermost.md): Post message / Post Sekoia.io alert
-- [Pagerduty](/integration/action_library/applicative/pagerduty.md): Trigger Alert
-- [The Hive](/integration/action_library/collaboration_tools/the-hive.md): Create an alert in the Hive
+- [Mandrill](/integration/action_library/mandrill.md): Send Message
+- [Mattermost](/integration/action_library/mattermost.md): Post message / Post Sekoia.io alert
+- [Pagerduty](/integration/action_library/pagerduty.md): Trigger Alert
+- [The Hive](/integration/action_library/the-hive.md): Create an alert in the Hive
 - ...
 
 ## Data collection
 
 If you have an account in one of the listed tools below, you can easily extract data from there and import it to Sekoia.io. This is made possible with an API key.
 
-- [BinaryEdge](/integration/action_library/threat_intelligence/binaryedge-s-api.md)
-- [Censys](/integration/action_library/threat_intelligence/censys.md)
-- [GLIMPS](/integration/action_library/threat_intelligence/glimps.md)
-- [IKnowWhatYouDownloaded](/integration/action_library/threat_intelligence/iknowwhatyoudownload.md)
-- [Onyphe](/integration/action_library/threat_intelligence/onyphe.md)
-- [Public Suffix](/integration/action_library/threat_intelligence/public-suffix.md)
-- [RiskIQ](/integration/action_library/threat_intelligence/riskiq.md)
-- [Shodan](/integration/action_library/threat_intelligence/shodan.md)
-- [VirusTotal](/integration/action_library/threat_intelligence/virustotal.md)
-- [Whois](/integration/action_library/threat_intelligence/whois.md)
+- [BinaryEdge](/integration/action_library/binaryedge-s-api.md)
+- [Censys](/integration/action_library/censys.md)
+- [GLIMPS](/integration/action_library/glimps.md)
+- [IKnowWhatYouDownloaded](/integration/action_library/iknowwhatyoudownload.md)
+- [Onyphe](/integration/action_library/onyphe.md)
+- [Public Suffix](/integration/action_library/public-suffix.md)
+- [RiskIQ](/integration/action_library/riskiq.md)
+- [Shodan](/integration/action_library/shodan.md)
+- [VirusTotal](/integration/action_library/virustotal.md)
+- [Whois](/integration/action_library/whois.md)
 - ...
 
 ## Helpers
 
 | Name | Description |
 | --- | --- |
-| [fileutils](/integration/action_library/generic/fileutils.md) | Extract data from XML or JSON files |
-| [http](/integration/action_library/generic/http.md) | Request HTTP resources (download file, request URL) |
-| [STIX](/integration/action_library/threat_intelligence/stix.md) | Add source, add tags, create relationships, cryptolaemus to STIX, CVE to STIX, filter bundle, JSON objects to observables, VirusTotal LiveHunt to observables, MISP to STIX, observables to contextualized indicators, observables to indicators, remove orphan objects, STIX to MISP, string to observables |
+| [fileutils](/integration/action_library/fileutils.md) | Extract data from XML or JSON files |
+| [http](/integration/action_library/http.md) | Request HTTP resources (download file, request URL) |
+| [STIX](/integration/action_library/stix.md) | Add source, add tags, create relationships, cryptolaemus to STIX, CVE to STIX, filter bundle, JSON objects to observables, VirusTotal LiveHunt to observables, MISP to STIX, observables to contextualized indicators, observables to indicators, remove orphan objects, STIX to MISP, string to observables |
 
 These helpers need their associated trigger to function properly:
 
 | Name | Description |
 | --- | --- |
-| [MISP](/integration/action_library/threat_intelligence/misp.md) | Gather, store, share and correlate threat intelligence. Convert from MISP to STIX, publish MISP event |
-| [MWDB](/integration/action_library/threat_intelligence/mwdb.md) | Convert a MWDB config to a bundle of observables |
-| [Triage](/integration/action_library/threat_intelligence/triage.md) | Triage raw results to observables |
+| [MISP](/integration/action_library/misp.md) | Gather, store, share and correlate threat intelligence. Convert from MISP to STIX, publish MISP event |
+| [MWDB](/integration/action_library/mwdb.md) | Convert a MWDB config to a bundle of observables |
+| [Triage](/integration/action_library/triage.md) | Triage raw results to observables |
 
 ## Third-party applications
 
-- [Microsoft Entra ID (Azure AD) ](/integration/action_library/iam/microsoft-entra-id.md)
-- [Microsoft Remote Server](/integration/action_library/applicative/microsoft-remote-server.md)
-- [Fortigate Firewalls](/integration/action_library/network/fortigate-firewalls.md)
-- [HarfangLab](/integration/action_library/endpoint/harfanglab.md)
-- [Panda Security](/integration/action_library/endpoint/panda-security.md)
-- [Sentinel One](/integration/action_library/endpoint/sentinelone.md)
-- [ServiceNow](/integration/action_library/collaboration_tools/servicenow.md)
+- [Microsoft Entra ID (Azure AD) ](/integration/action_library/microsoft-entra-id.md)
+- [Microsoft Remote Server](/integration/action_library/microsoft-remote-server.md)
+- [Fortigate Firewalls](/integration/action_library/fortigate-firewalls.md)
+- [HarfangLab](/integration/action_library/harfanglab.md)
+- [Panda Security](/integration/action_library/panda-security.md)
+- [Sentinel One](/integration/action_library/sentinelone.md)
+- [ServiceNow](/integration/action_library/servicenow.md)
 - ...
 
 More actions are available in the Actions Library. To learn how to set up an action, please refer to its documentation.

_shared_content/automate/build-playbooks.md

@@ -60,7 +60,7 @@ To create a playbook from scratch, you will need to create an empty playbook, go
 
 Please refer to the documentation for each of these types to learn how to use them efficiently.
 
-You can refer to our [playbook templates](https://github.com/SEKOIA-IO/Community/tree/main/playbooks/templates) and [use cases](/xdr/usecases/playbook/synchronize_alerts/) for inspiration.
+You can refer to our [playbook templates](https://github.com/SEKOIA-IO/Community/tree/main/playbooks/templates) and [use cases](/xdr/usecases/playbook/synchronize_alerts.md) for inspiration.
 
 ## Meta-playbook creation
 

_shared_content/automate/navigate-playbooks.md

@@ -53,7 +53,7 @@ The workflow view is composed of three main sections:
 
 #### Actions library
 
-Accessible in a side panel that appears when clicking on the `+` on the left of the screen, this library provides you with a set of [triggers](https://docs.sekoia.io/xdr/features/automate/triggers/), [actions](https://docs.sekoia.io/xdr/features/automate/actions/) and [operators](https://docs.sekoia.io/xdr/features/automate/operators/) to help automate your workflow.
+Accessible in a side panel that appears when clicking on the `+` on the left of the screen, this library provides you with a set of [triggers](/xdr/features/automate/triggers.md), [actions](/xdr/features/automate/actions.md) and [operators](/xdr/features/automate/operators.md) to help automate your workflow.
 
 These actions are regrouped in apps and services that are interconnected with Sekoia.io.
 
@@ -65,7 +65,7 @@ To find actions in the listing, you can either:
 To add these actions to your graph, click on the dots next to the action name and drag it to the graph area. Dropping actions into this area will form a **block**.
 
 !!! note
-    Configuration for each of these blocks is detailed in the [Library section](https://docs.sekoia.io/xdr/features/automate/library/aws/) of this documentation.
+    Configuration for each of these blocks is detailed in the [Library section](/xdr/features/automate/library/aws.md) of this documentation.
 
 #### Graph area
 
@@ -229,7 +229,7 @@ This tab includes filters for sorting by Status. Additionally, 'Meta-Playbooks'
 
 #### Run results
 
-Run results are accessible either from the tab `Runs` in the playbook or in the panel that details a [playbook's details](#details-panel).
+Run results are accessible either from the tab `Runs` in the playbook or in the panel that details a [playbook's details](#playbook-details).
 
 This panel contains the following information: