9.2 KiB
9.2 KiB
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
# 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
# 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
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
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
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
{
"$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
# 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
# Only high priority changes
stellaops smart-diff --output-format sarif --min-priority 0.7
StellaOps Property Keys
Sprint: SPRINT_20260112_008_DOCS_path_witness_contracts (PW-DOC-003)
SARIF properties bag extensions for StellaOps-specific metadata.
Result-Level Properties
| Property Key | Type | Description |
|---|---|---|
stellaops/nodeHash |
string | Canonical node hash (sha256:<hex>) for static/runtime joining |
stellaops/pathHash |
string | Canonical path hash for full reachability path |
stellaops/topKNodeHashes |
array | Top-K node hashes for efficient lookup |
stellaops/evidenceUri |
string | cas://<hash> URI to evidence bundle |
stellaops/attestationUri |
string | cas://<hash> URI to DSSE envelope |
stellaops/rekorUri |
string | Rekor transparency log entry URL |
stellaops/witnessId |
string | Path witness identifier |
stellaops/witnessHash |
string | BLAKE3 hash of witness payload |
Run-Level Properties
| Property Key | Type | Description |
|---|---|---|
stellaops/scanId |
string | UUID of the scan |
stellaops/graphHash |
string | BLAKE3 hash of the rich graph |
stellaops/sbomDigest |
string | SHA256 digest of source SBOM |
stellaops/feedSnapshot |
string | ISO8601 timestamp of feed data |
Example with StellaOps Properties
{
"results": [
{
"ruleId": "SDIFF001",
"level": "warning",
"message": {
"text": "CVE-2024-1234 became reachable via 3-hop path"
},
"locations": [
{
"logicalLocations": [
{
"name": "pkg:npm/lodash@4.17.20",
"kind": "package"
},
{
"name": "lodash.merge(object, object)",
"kind": "function"
}
]
}
],
"properties": {
"vulnerability": "CVE-2024-1234",
"tier": "executed",
"direction": "increased",
"stellaops/nodeHash": "sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
"stellaops/pathHash": "sha256:fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
"stellaops/topKNodeHashes": [
"sha256:entry1111111111111111111111111111111111111111111111111111111111",
"sha256:sink22222222222222222222222222222222222222222222222222222222222"
],
"stellaops/evidenceUri": "cas://sha256:evidence123...",
"stellaops/attestationUri": "cas://sha256:dsse456...",
"stellaops/rekorUri": "https://rekor.sigstore.dev/api/v1/log/entries/abc123",
"stellaops/witnessId": "550e8400-e29b-41d4-a716-446655440000"
}
}
]
}
Joining Static and Runtime Evidence
Use stellaops/nodeHash to correlate:
- Static analysis findings (SARIF from Scanner)
- Runtime telemetry (execution traces from agents)
- Policy decisions (gating results)
# Query findings by node hash
curl -H "Authorization: Bearer $TOKEN" \
"https://scanner.example.com/api/v1/findings?nodeHash=sha256:a1b2c3..."
# Verify path witness by hash
stellaops witness verify --path-hash sha256:fedcba...
Troubleshooting
SARIF Validation Errors
If your CI platform rejects the SARIF output:
-
Validate against schema:
stellaops validate-sarif results.sarif -
Check for required fields:
$schemamust be presentversionmust be"2.1.0"- Each result must have
ruleIdandmessage
Empty Results
If SARIF contains no results:
- Check scan completed successfully
- Verify image has vulnerability data
- Ensure feed snapshots are current