Dev preview/gitlab sarif converter

docs/integrating-scribe/ci-integrations/gitlab-sarif-results.md

@@ -0,0 +1,92 @@
+---
+sidebar_label: "SARIF Conversion to GitLab SAST"
+title: Converting SARIF Files to GitLab SAST Results
+sidebar_position: 10
+---
+
+# GitLab SARIF Converter Script
+
+This script automates the conversion of various JSON formats generated by Valint (e.g., SARIF, statement, attestation files) into GitLab-compatible SAST result. The script includes options to install dependencies, select the input and output file locations, and handle specific JSON processing requirements.
+
+---
+
+## Installation
+
+1. **Download the Script**  
+   Use `curl` or `wget` to download the script from the repository:
+
+   ```bash
+   wget https://raw.githubusercontent.com/scribe-security/misc/refs/heads/master/gitlab-sarif-converter.sh
+   chmod +x gitlab-sarif-converter.sh
+   ```
+
+2. **Check Prerequisites**  
+   Ensure `jq` and `base64` are installed, as they are required for processing JSON data. Use the package manager to install them:
+
+   ```bash
+   # For Debian-based systems
+   sudo apt update && sudo apt install jq coreutils -y
+
+   # For RedHat-based systems
+   sudo yum install jq coreutils -y
+   ```
+
+3. **Install the SARIF Converter** (optional)  
+   The script includes a `-i` flag to download and install the `sarif-converter` binary if it’s not already available in the specified path.
+
+
+## Running Valint
+
+Valint is a tool that verifies the integrity of software packages and can output various formats such as SARIF, statements, or attestations. Before using the GitLab SARIF Converter script, ensure you have run Valint to generate the necessary JSON files.
+
+### Example Command to Run Valint
+
+To verify a target (e.g., a Docker image) and output a statement or SARIF file, use the following command:
+
+```bash
+valint verify --bom busybox:latest -o attest --output-file busybox.sarif.statement.json
+```
+
+In this example:
+- `--bom busybox:latest`: Specifies the target image for verification.
+- `-o attest`: Sets the output type. Use `-o sarif` for SARIF output or `-o statement` for a standard statement output.
+- `--output-file busybox.sarif.statement.json`: Indicates the output file where the generated data will be stored.
+
+## Usage
+
+The script is designed to process different file types, such as `.sarif`, `.statement.json`, `.sig.json`, or `.sarif.json`, and convert them to GitLab-compatible SARIF files. Below are common use cases and options.
+
+### Command Syntax
+
+```bash
+./gitlab-sarif-converter.sh [-F <file-path>] [-B <binary-path>] [-O <output-file>] [-x] [-i] [-h]
+```
+
+### Options
+
+- `-F <file-path>`: Specifies the file to process.
+- `-B <binary-path>`: Specifies the path to the `sarif-converter` binary (default is `./sarif-converter`).
+- `-O <output-file>`: Defines the output file name (default is `output.gitlab.json`).
+- `-x`: Enables debug mode, showing script execution details.
+- `-i`: Installs the `sarif-converter` binary if it’s missing.
+- `-h` or `--help`: Displays usage information.
+
+### Example Usage
+
+1. **Convert a Statement JSON file:**
+
+   ```bash
+   ./gitlab-sarif-converter.sh -F example.sarif.json -O converted.gitlab.json
+   ```
+
+2. **Enable Debug Mode and Install Missing Converter Binary:**
+
+   ```bash
+   ./gitlab-sarif-converter.sh -x -i -F example.sarif
+   ```
+
+3. **Specify a Custom Binary Path:**
+
+   ```bash
+   ./gitlab-sarif-converter.sh -B /usr/local/bin/sarif-converter -F sample.sig.json
+   ```