feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration
- Add RateLimitConfig for configuration management with YAML binding support. - Introduce RateLimitDecision to encapsulate the result of rate limit checks. - Implement RateLimitMetrics for OpenTelemetry metrics tracking. - Create RateLimitMiddleware for enforcing rate limits on incoming requests. - Develop RateLimitService to orchestrate instance and environment rate limit checks. - Add RateLimitServiceCollectionExtensions for dependency injection registration.
This commit is contained in:
master
250
docs/ci/sarif-integration.md
Normal file
250
docs/ci/sarif-integration.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user