chore: documentation for action / template to check security gate

.github/workflows/publish_docs.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - main
-      - chore/doc_trivy_secrets
+      - chore/documentation_check_security_gate
 
 permissions: read-all
 

docs/getting_started/about.md

@@ -36,10 +36,16 @@ sequenceDiagram
     activate Pipeline
     Pipeline ->> Pipeline: Run scanners
     Pipeline ->> SecObserve: Upload results
-    deactivate Pipeline
     activate SecObserve
     SecObserve ->> SecObserve: Apply rules
     deactivate SecObserve
+    Pipeline ->> SecObserve: Check security gate
+    activate SecObserve
+    SecObserve -->> Pipeline: exit code 0/1
+    deactivate SecObserve
+    Pipeline ->> Pipeline: Stop or continue
+    Pipeline -->> Developer: Feedback
+    deactivate Pipeline
     Developer ->> SecObserve: View observations
     Developer ->> SecObserve: Assess observations
     Developer ->> Developer: Implement fixes
@@ -51,7 +57,13 @@ sequenceDiagram
 3. The pipeline runs several of the supported vulnerability scanners. To make integration easy, SecObserve provides predefined templates for the most relevant scanners, see [GitHub actions and GitLab CI templates](../integrations/github_actions_and_templates.md).
 4. The scanners store their results in files, which are [uploaded into SecObserve](../usage/import_observations.md).
 5. SecObserve applies [rules](../usage/rule_engine.md) to adjust severity and status of observations during the upload process.
-6. The developer can now look at the observations in SecObserve, to see what has changed ...
-7. ... and if necessary [assess observations](../usage/assess_observations.md) to change their status (eg. false positive or risk accepted) or severity.
-8. If fixes are needed to close vulnerabilities, the developer will implement the fixes ...
-9. ... and check them in to the repository. Now the cycle starts again.
+6. The pipeline can call SecObserve to check the status of the [security gate](../usage/security_gates.md).
+7. SecObserve returns an exit code to the pipeline: 
+    * `1` if the security gate has **failed**
+    * `0` if the security gate has **passed** or is **disabled**
+8. The pipeline can stop or continue based on the exit code, depending on the configuration of the check step. Default is to stop the pipeline if the security gate has failed.
+9. The developer can see the result of the pipeline.
+10. The developer can now look at the observations in SecObserve, to see what has changed ...
+11. ... and if necessary [assess observations](../usage/assess_observations.md) to change their status (eg. false positive or risk accepted) or severity.
+12. If fixes are needed to close vulnerabilities, the developer will implement the fixes ...
+13. ... and check them in to the repository. Now the cycle starts again.

docs/integrations/github_actions_and_templates.md

@@ -31,6 +31,10 @@ Most of the actions and templates use the same set of variables:
 | `SO_ORIGIN_DOCKER_IMAGE_NAME_TAG` | *optional* | Name:Tag of Docker image to be set for all imported observations. |
 | `SO_ORIGIN_ENDPOINT_URL` | *optional* | URL of endpoint to be set for all imported observations. |
 | `SO_SUPPRESS_LICENSES` | *optional, only for CycloneDX* | Suppress importing license information if value is `true`. Default is `true` for the *Grype*, *Trivy Filesystem* and *Trivy Image* GitHub action / GitLab templates, default is `false` for the *Importer*  action/template |
+| **Check security gate** |
+| `SO_API_BASE_URL` | *mandatory* | Base URL of the SecObserve backend, e.g. `https://secobserve-backend.example.com`. |
+| `SO_API_TOKEN` | *mandatory* | API token of the user to be used for the check. |
+| `SO_PRODUCT_NAME` | *mandatory* | Name of the product for which the security gate check is being performed. |
 
 ## Available actions and templates
 
@@ -58,6 +62,11 @@ Most of the actions and templates use the same set of variables:
 | [DrHeader](https://github.com/Santandersecurityresearch/DrHeader) | `actions/DAST/drheader` | `templates/DAST/drheader.yml` | [MIT](https://github.com/Santandersecurityresearch/DrHeader/blob/master/LICENSE) |
 | [ZAP](https://github.com/zaproxy/zaproxy)                         | `actions/DAST/zap` | `templates/DAST/zap.yml` | [Apache 2.0](https://github.com/zaproxy/zaproxy/blob/main/LICENSE) |
 
+| Task                                  | GitHub Action             | GitLab CI Template              |
+|---------------------------------------|---------------------------|---------------------------------|
+| Import existing file into SecObserve | `actions/importer` | `templates/importer.yml` |
+| Check security gate of a product (`exit code 1` if security gate **Failed**, `exit code 0` if security gate **Passed** or **Disabled**) | `actions/check_security_gate` | `templates/check_security_gate.yml` |
+
 All GitHub actions and GitLab CI templates use a pre-built Docker image that contains all scanners and the SecObserve importer.
 
 ##  Examplary workflow for GitHub actions