feat: add sarif endpoint and ci action guard

Author: haasonsaas

README.md

@@ -123,6 +123,7 @@ Copy `.env.example` to `.env` and adjust values locally if you prefer dotenv-sty
 | `/v1/analysis/{id}` | `GET` | Poll analysis status, findings count, and risk summary snapshot |
 | `/v1/analysis/{id}/decision` | `GET` | Fetch the governance decision (allow/block/warn) with evidence |
 | `/v1/analysis/{id}/bundle` | `GET` | Retrieve the signed DSSE decision bundle |
+| `/v1/analysis/{id}/sarif` | `GET` | Retrieve the SARIF 2.1.0 findings report for the analysis |
 | `/v1/analytics/summary` | `GET` | Retrieve aggregated KPIs (risk rate, provenance, volume, churn, complexity, etc.) |
 | `/v1/analytics/agents/behavior` | `GET` | Retrieve composite behavioral snapshots for each agent |
 | `/v1/detectors/capabilities` | `GET` | Enumerate active detectors (Semgrep configs, versions, metadata) |
@@ -180,6 +181,13 @@ To smoke-test the GitHub resolver end-to-end:
 
 The same process works against forks or sandboxes—helpful when validating new heuristics without polluting production repositories.
 
+## CI Integration
+
+- A composite GitHub Action is bundled at `clients/github-action/`. Reference it from `.github/workflows/provenance.yml` and pass `api_url` + `api_token` secrets to submit each pull request diff. The action fails automatically when the governance outcome is `block`.
+- The workflow helper collects the PR diff (`base_sha..head_sha`), submits it to `/v1/analysis`, polls `/v1/analysis/{id}`, and prints the enriched decision payload so reviewers can inspect risk summaries inline.
+- Consume `/v1/analysis/{id}/sarif` when you need static-analysis interoperability (e.g., uploading to GitHub code scanning or aggregating findings in other dashboards).
+- Surface decision bundles in CI by hitting `/v1/analysis/{id}/bundle` (e.g., attach the DSSE envelope as a build artifact) to preserve signed provenance for downstream policy checks.
+
 ## Telemetry Export
 
 - Each analysis generates an `analysis_metrics` event written to `data/timeseries_events.jsonl` by default.

app/routers/analysis.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, status
+from fastapi.responses import JSONResponse
 
 from app.core.config import settings
 from app.dependencies import get_analysis_service, get_store
@@ -14,6 +15,7 @@
     DecisionBundleResponse,
 )
 from app.services.analysis import AnalysisService
+from app.services.sarif import build_sarif
 
 
 router = APIRouter(prefix=f"{settings.api_v1_prefix}/analysis", tags=["analysis"])
@@ -46,12 +48,16 @@ def get_analysis_status(
     findings_total = len(store.list_findings(analysis_id))
     decision = store.get_policy_decision(analysis_id)
     risk_summary = decision.risk_summary if decision else {}
+    decision_payload = decision.model_dump() if decision else None
+    if decision_payload and "risk_summary" in decision_payload:
+        decision_payload.pop("risk_summary")
     return AnalysisStatusResponse(
         analysis_id=record.analysis_id,
         status=record.status,
         updated_at=record.updated_at,
         findings_total=findings_total,
         risk_summary=risk_summary,
+        decision=decision_payload,
     )
 
 
@@ -68,3 +74,17 @@ def get_decision_bundle(
         bundle=bundle,
         request_id=f"rq_{settings.default_policy_version}-{analysis_id}",
     )
+
+
+@router.get("/{analysis_id}/sarif")
+def get_analysis_sarif(
+    analysis_id: str,
+    analysis_service: AnalysisService = Depends(get_analysis_service),
+    store: RedisWarehouse = Depends(get_store),
+) -> JSONResponse:
+    record = analysis_service.get_analysis(analysis_id)
+    if not record:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Analysis not found")
+    findings = store.list_findings(analysis_id)
+    sarif_report = build_sarif(record, findings)
+    return JSONResponse(sarif_report)

app/schemas/analysis.py

@@ -83,6 +83,7 @@ class AnalysisStatusResponse(BaseModel):
     updated_at: datetime
     findings_total: int
     risk_summary: dict = Field(default_factory=dict)
+    decision: dict | None = None
 
 
 class DecisionBundleResponse(BaseModel):

app/services/sarif.py

@@ -0,0 +1,69 @@
+"""Utilities for generating SARIF reports from findings."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Iterable
+
+from app.models.domain import AnalysisRecord, Finding, SeverityLevel
+
+_SEVERITY_MAP = {
+    SeverityLevel.CRITICAL: "error",
+    SeverityLevel.HIGH: "error",
+    SeverityLevel.MEDIUM: "warning",
+    SeverityLevel.LOW: "note",
+}
+
+
+def build_sarif(analysis: AnalysisRecord, findings: Iterable[Finding]) -> dict:
+    results = []
+    for finding in findings:
+        level = _SEVERITY_MAP.get(finding.severity, "warning")
+        results.append(
+            {
+                "ruleId": finding.rule_key,
+                "level": level,
+                "message": {"text": finding.message},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": finding.file_path},
+                            "region": {
+                                "startLine": finding.line_number,
+                            },
+                        }
+                    }
+                ],
+                "properties": {
+                    "analysis_id": analysis.analysis_id,
+                    "repo_id": analysis.repo_id,
+                    "pr_number": analysis.pr_number,
+                    "engine_name": finding.engine_name,
+                },
+            }
+        )
+
+    sarif = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "Provenance Governance",
+                        "informationUri": "https://github.com/evalops/provenance",
+                        "rules": [],
+                    }
+                },
+                "invocations": [
+                    {
+                        "executionSuccessful": True,
+                        "startTimeUtc": analysis.created_at.isoformat(),
+                        "endTimeUtc": analysis.updated_at.isoformat(),
+                    }
+                ],
+                "results": results,
+            }
+        ],
+    }
+    return sarif

clients/github-action/run.py

@@ -104,6 +104,10 @@ def main() -> None:
     analysis_id = response["analysis_id"]
     decision = poll_decision(args.api_url, args.api_token, analysis_id)
     print(json.dumps(decision, indent=2))
+    decision_info = decision.get("decision") or {}
+    outcome_value = decision_info.get("outcome") or decision.get("status")
+    if isinstance(outcome_value, str) and outcome_value.lower() == "block":
+        raise SystemExit(1)
 
 
 if __name__ == "__main__":

tests/test_api_endpoints.py

@@ -99,6 +99,7 @@ def test_full_analysis_flow_via_api():
     body = status_resp.json()
     assert body["findings_total"] == 1
     assert body["risk_summary"]["findings_by_category"] == {"code_execution": 1}
+    assert body["decision"]["outcome"] == "allow"
 
     summary = client.get("/v1/analytics/summary", params={"time_window": "1d", "metric": "code_volume"})
     assert summary.status_code == 200
@@ -119,3 +120,9 @@ def test_full_analysis_flow_via_api():
     bundle_json = bundle_resp.json()
     assert bundle_json["analysis_id"] == analysis_id
     assert bundle_json["bundle"]["payloadType"] == "application/provenance.decision+json"
+
+    sarif_resp = client.get(f"/v1/analysis/{analysis_id}/sarif")
+    assert sarif_resp.status_code == 200
+    sarif_json = sarif_resp.json()
+    assert sarif_json["version"] == "2.1.0"
+    assert sarif_json["runs"]