git.stella-ops.org/docs/ci/sarif-integration.md

# SARIF Integration Guide

**Sprint:** SPRINT_3500_0004_0001  
**Task:** SDIFF-BIN-032 - Documentation for SARIF integration

## Overview

StellaOps Scanner supports SARIF (Static Analysis Results Interchange Format) 2.1.0 output for seamless integration with CI/CD platforms including GitHub, GitLab, and Azure DevOps.

## Supported Platforms

| Platform | Integration Method | Native Support |
|----------|-------------------|----------------|
| GitHub Actions | Code Scanning API | ✅ Yes |
| GitLab CI | SAST Reports | ✅ Yes |
| Azure DevOps | SARIF Viewer Extension | ✅ Yes |
| Jenkins | SARIF Plugin | ✅ Yes |
| Other | File upload | ✅ Yes |

## Quick Start

### API Endpoint

```bash
# Get SARIF output for a scan
curl -H "Authorization: Bearer $TOKEN" \
  "https://scanner.example.com/api/v1/smart-diff/scans/{scanId}/sarif"

# With pretty printing
curl -H "Authorization: Bearer $TOKEN" \
  "https://scanner.example.com/api/v1/smart-diff/scans/{scanId}/sarif?pretty=true"
```

### CLI Usage

```bash
# Scan with SARIF output
stellaops scan image:tag --output-format sarif > results.sarif

# Smart-diff with SARIF output
stellaops smart-diff --base image:v1 --target image:v2 --output-format sarif
```

## SARIF Rule Definitions

StellaOps emits the following rule categories in SARIF output:

| Rule ID | Name | Description |
|---------|------|-------------|
| SDIFF001 | ReachabilityChange | Vulnerability reachability status changed |
| SDIFF002 | VexStatusFlip | VEX status changed (affected/not_affected/fixed) |
| SDIFF003 | HardeningRegression | Binary hardening flag regressed |
| SDIFF004 | IntelligenceSignal | EPSS/KEV status changed |

## GitHub Actions Integration

```yaml
name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run StellaOps Scanner
        run: |
          stellaops scan ${{ github.repository }} \
            --output-format sarif \
            --output results.sarif
      
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
          category: stellaops
```

## GitLab CI Integration

```yaml
security_scan:
  stage: test
  image: stellaops/cli:latest
  script:
    - stellaops scan $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --output-format sarif > gl-sast-report.sarif
  artifacts:
    reports:
      sast: gl-sast-report.sarif
```

## Azure DevOps Integration

```yaml
trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: Bash@3
    displayName: 'Run StellaOps Scanner'
    inputs:
      targetType: 'inline'
      script: |
        stellaops scan $(containerImage) --output-format sarif > $(Build.ArtifactStagingDirectory)/results.sarif

  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: '$(Build.ArtifactStagingDirectory)/results.sarif'
      artifactName: 'security-results'
```

## SARIF Schema Details

### Result Levels

| SARIF Level | StellaOps Severity | Description |
|-------------|-------------------|-------------|
| `error` | Critical, High | Requires immediate attention |
| `warning` | Medium | Should be reviewed |
| `note` | Low, Info | For awareness |

### Result Kinds

| Kind | Meaning |
|------|---------|
| `fail` | Finding indicates a problem |
| `pass` | Check passed (for VEX suppressed) |
| `notApplicable` | Finding does not apply |
| `informational` | Advisory information |

### Location Information

SARIF results include:
- **Physical location**: File path and line numbers (when available)
- **Logical location**: Component PURL, function name
- **URI**: OCI artifact digest or SBOM reference

## Example SARIF Output

```json
{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "StellaOps Scanner",
          "version": "1.0.0",
          "informationUri": "https://stellaops.io",
          "rules": [
            {
              "id": "SDIFF001",
              "name": "ReachabilityChange",
              "shortDescription": {
                "text": "Vulnerability reachability changed"
              },
              "defaultConfiguration": {
                "level": "warning"
              }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "SDIFF001",
          "level": "warning",
          "message": {
            "text": "CVE-2024-1234 became reachable in pkg:npm/lodash@4.17.20"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "package-lock.json"
                }
              },
              "logicalLocations": [
                {
                  "name": "pkg:npm/lodash@4.17.20",
                  "kind": "package"
                }
              ]
            }
          ],
          "properties": {
            "vulnerability": "CVE-2024-1234",
            "tier": "executed",
            "direction": "increased"
          }
        }
      ]
    }
  ]
}
```

## Filtering Results

### By Tier

```bash
# Only tainted_sink findings
stellaops scan image:tag --output-format sarif --tier tainted_sink

# Executed and tainted_sink
stellaops scan image:tag --output-format sarif --tier executed,tainted_sink
```

### By Priority

```bash
# Only high priority changes
stellaops smart-diff --output-format sarif --min-priority 0.7
```

## Troubleshooting

### SARIF Validation Errors

If your CI platform rejects the SARIF output:

1. Validate against schema:
   ```bash
   stellaops validate-sarif results.sarif
   ```

2. Check for required fields:
   - `$schema` must be present
   - `version` must be `"2.1.0"`
   - Each result must have `ruleId` and `message`

### Empty Results

If SARIF contains no results:
- Check scan completed successfully
- Verify image has vulnerability data
- Ensure feed snapshots are current

## Related Documentation

- [Smart-Diff Detection Rules](../modules/scanner/smart-diff-rules.md)
- [Scanner API Reference](../api/scanner-api.md)
- [CLI Reference](../09_API_CLI_REFERENCE.md)
- [Scoring Configuration](./scoring-configuration.md)