345 lines
9.2 KiB
Markdown
345 lines
9.2 KiB
Markdown
# 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
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
1. **Static analysis** findings (SARIF from Scanner)
|
|
2. **Runtime telemetry** (execution traces from agents)
|
|
3. **Policy decisions** (gating results)
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
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](../API_CLI_REFERENCE.md)
|
|
- [Scoring Configuration](./scoring-configuration.md)
|