HomeGuidesAPI ReferenceChangelog
Guides

SARIF

Suggest Edits

SARIF CLI

This CLI is provided to import and convert SARIF (Static Analysis Results Interchange Format) files into RegScale by for OCSF conversion. It is designed to process security findings from static analysis tools and create corresponding Vulnerability, VulnerabilityMapping, and ScanHistory objects in RegScale. The CLI currently supports the below functionality:

  • import - converts SARIF files to OCSF format and imports findings as vulnerabilities into an Asset record in RegScale

Prerequisites - Init.yaml Configuration

This integration requires an Access Token added to the init.yaml file to configure the SARIF integration via the CLI. Obtain an Access Token and directions on use from RegScale.

SARIF Processing Workflow

The CLI currently supports processing SARIF files to create RegScale vulnerabilities. The SARIF processing workflow is shown below:

  • The user first logs into RegScale via the CLI to set the access token or otherwise creates a service account as described in the CLI Login documentation
  • The user then calls the CLI ( regscale sarif import) to process SARIF files while setting the following flags:
    • file_path - path to the SARIF file or directory containing multiple SARIF files
    • asset_id - the ID # of the RegScale Asset to associate the vulnerabilities with
    • scan_date - optional scan date (defaults to current date if not provided)
  • The CLI loads and validates the SARIF file(s) from the specified path
  • Each SARIF file is converted to OCSF format using the Synqly API
  • The converted data is saved to a local "converted" directory for reference
  • Vulnerability objects are created in RegScale based on the OCSF findings
  • VulnerabilityMapping objects are created to associate vulnerabilities with the specified asset
  • A ScanHistory record is created to track the import process and vulnerability counts

The CLI provides detailed logging throughout the process to indicate progress and to provide troubleshooting in case of problems.

SARIF CLI Command Example

The following command provides an example of processing SARIF files for a given RegScale Asset. These commands can be easily adapted for the customer's specific use case. The steps are shown below:

  • Log into RegScale to set the token which is good for 24 hours and will secure all future RegScale API calls (NOTE: You can skip this step if you are using a RegScale Service Account)
regscale login
  • Process SARIF files for the specified asset
regscale sarif import --file_path="/path/to/sarif/files" --asset_id=123 --scan_date="2024-01-15"

Batch Processing Multiple Files

The CLI supports processing multiple SARIF files at once by specifying a directory path:

regscale sarif import --file_path="/path/to/directory/with/sarif/files" --asset_id=123

When processing a directory, the CLI will:

  • Find all files with .sarif extension in the specified directory
  • Process each file sequentially
  • Create a consolidated scan history record
  • Provide progress updates and summary statistics

Init.yaml Example

For a basic SARIF integration with RegScale, the following init.yaml structure is necessary (example/notional key structure shown below, replace with actual customer keys):

domain: https://mycompany.regscale.com
token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC38.eyJzdWIiOiJob3dpZWF2cCIsImp0aSI6ImI0NDIxMjRhLTYxOWEtNGI1Mi1hMzUzLTA5YzdjZTRmM2JmOCIsImlhdCI6MTY0NDc4NzY4MiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvbmFtZWlkZW50aWZpZXIiOiJjOWY1NzllMi1hOGM4LTRjMDItOGU5MS1jZTEyMmExYWE1MTciLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiaG93aWVhdnAiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJBZG1pbmlzdHJhdG9yIiwibmJmIjoxNjQ0Nzg3NjgyLCJleHAiOjE2NDQ4NzQwODIsImlzcyI6IkF0bGFzIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MDAwLyJ9.SkjmRktGLkljysVeoRqcx_hHiVR2gjcA2uZiSJbVkPc
userId: c9f579e2-a8c9-4c02-8e91-ce122a1aa518
synqlyAccessToken: your_synqly_access_token_here

Building a Bash Script to Execute the CLI

You can chain together RegScale CLI commands using scripts. These scripts could be in Bash, Python, PowerShell, etc. Below is an example Bash file (named "sarifProcessor.sh") in Ubuntu for executing the SARIF CLI that processes SARIF files after authenticating:

#!/bin/sh
regscale login
regscale sarif import --file_path="/path/to/sarif/reports" --asset_id=123 --scan_date="2024-01-15"

To execute the Bash file, run this command: . sarifProcessor.sh. You can chain together any arbitrary set of CLI commands to have them execute sequentially.

Supported SARIF Features

The SARIF importer supports:

  • SARIF Schema Validation: Basic validation to ensure files are valid SARIF format
  • Multiple Runs: Processing SARIF files with multiple analysis runs
  • Vulnerability Mapping: Converting SARIF results to RegScale vulnerabilities with proper severity mapping
  • Metadata Extraction: Preserving tool information, versions, and rule details
  • Asset Association: Linking findings to specific RegScale assets
  • Scan History: Tracking import operations and vulnerability counts by severity

Output and Artifacts

During processing, the CLI creates several artifacts:

  • Converted Files: OCSF-formatted JSON files saved to a "converted" directory
  • Progress Tracking: Real-time progress indicators for large file processing
  • Detailed Logging: Comprehensive logs including file processing status, vulnerability counts, and any errors
  • Summary Reports: Final statistics showing created and updated vulnerabilities

Error Handling

The CLI includes robust error handling for:

  • Invalid or corrupted SARIF files
  • Synqly API connectivity issues
  • RegScale API authentication and connectivity problems
  • File system permissions and path issues
  • Missing or invalid asset IDs

All errors are logged with detailed information to assist with troubleshooting and resolution.

Updated 3 days ago