docs: add SARIF normalization and exit code handling to Section 2-3-5 (Security Gates)

[moghit-eou]

Currently, Section 2-3-5 discusses security gates but lacks concrete implementation details for handling the realities of multi-scanner DevSecOps pipelines. When running multiple SCA tools (e.g., OSV-Scanner for dependencies, Trivy for containers), teams often face fragmented pass/fail signals and inconsistent exit code semantics, leading to silent false negatives or blocked pipelines due to misconfigured tool crashes.

Proposed Changes

• SARIF Standardization: Added Python code examples demonstrating how to parse multiple SARIF files to extract the highest security-severity score across all scanners.
• Gate Decision Matrix: Introduced a deterministic mapping mechanism that explicitly separates a tool crash (ERROR) from a vulnerability threshold breach (FAILED).
• Exit Code Trap Documentation: Added specific guidance (with an OSV-Scanner example) on normalizing exit codes before they break the CI, ensuring that an exit code of 1 meaning "vulnerabilities found" is not misinterpreted as "scanner failed."
• CI Gate Enforcement: Added a practical implementation snippet showing how to halt the pipeline using sys.exit(1) and standard error outputs (stderr) based on the normalized decision.

This PR is part of a GSoC project (cc @jdaln for context). The wider project follows the OWASP DevSecOps Guidelines as its foundation.

[jdaln]

Hello @Ali-Yazdani ,

As @moghit-eou mentioned this is a proposed upstream contribution as part of the following GSoC project https://summerofcode.withgoogle.com/programs/2026/projects/m6uAnHtG .

Happy to receive feedback :)