feat: enrich provenance with github heuristics

Author: haasonsaas

.env.example

@@ -21,6 +21,9 @@ PROVENANCE_OTEL_EXPORTER=console
 PROVENANCE_POLICY_WARN_THRESHOLDS={}
 PROVENANCE_POLICY_BLOCK_THRESHOLDS={}
 PROVENANCE_DETECTOR_MODULE_PATHS=[]
+PROVENANCE_GITHUB_TOKEN=
+PROVENANCE_GITHUB_BASE_URL=
+PROVENANCE_GITHUB_AGENT_LABEL_PREFIX=agent:
 PROVENANCE_SEMGREP_CONFIG_PATH=
 PROVENANCE_DASHBOARD_API=http://localhost:8000/v1
 PROVENANCE_DASHBOARD_EVENTS=data/timeseries_events.jsonl

README.md

@@ -77,6 +77,9 @@ Copy `.env.example` to `.env` and adjust values locally if you prefer dotenv-sty
 | `PROVENANCE_POLICY_WARN_THRESHOLDS` | JSON map of category warn thresholds | `{}` |
 | `PROVENANCE_POLICY_BLOCK_THRESHOLDS` | JSON map of category block thresholds | `{}` |
 | `PROVENANCE_DETECTOR_MODULE_PATHS` | JSON array of detector module paths to auto-load | `[]` |
+| `PROVENANCE_GITHUB_TOKEN` | Personal access token for GitHub API enrichment | *(unset)* |
+| `PROVENANCE_GITHUB_BASE_URL` | GitHub enterprise base URL (optional) | *(unset)* |
+| `PROVENANCE_GITHUB_AGENT_LABEL_PREFIX` | PR label prefix used to infer agent IDs | `agent:` |
 
 ## Detection with Semgrep
 
@@ -91,6 +94,7 @@ Copy `.env.example` to `.env` and adjust values locally if you prefer dotenv-sty
 - The JSON results are mapped back to the originating changed lines so findings retain repo/PR/file/line attribution.
 - Extend the rule pack or point the detector at your organization-wide Semgrep registry by updating `SemgrepDetector` in `app/services/detection.py`.
 - Register additional detectors by providing module paths in `PROVENANCE_DETECTOR_MODULE_PATHS`; each module should expose `register_detectors()` returning `BaseDetector` instances.
+- When GitHub credentials are configured, the service automatically inspects commit trailers and PR labels to fill missing agent attribution (see `app/provenance/github_resolver.py`).
 
 ## API Surface
 

app/core/config.py

@@ -34,6 +34,9 @@ class Settings(BaseSettings):
     policy_warn_thresholds: dict[str, int] = Field(default_factory=dict)
     policy_block_thresholds: dict[str, int] = Field(default_factory=dict)
     detector_module_paths: list[str] = Field(default_factory=list)
+    github_token: str | None = None
+    github_base_url: str | None = None
+    github_agent_label_prefix: str = "agent:"
 
     model_config = SettingsConfigDict(env_prefix="provenance_", env_file=".env", extra="ignore")
 

app/dependencies.py

@@ -13,6 +13,7 @@
 from app.services.detection import DetectionService
 from app.services.governance import GovernanceService
 from app.telemetry import sink_from_settings, EventSink
+from app.provenance.github_resolver import GitHubProvenanceResolver
 
 
 @lru_cache
@@ -45,10 +46,22 @@ def get_governance_service() -> GovernanceService:
     return GovernanceService()
 
 
+@lru_cache
+def get_github_resolver() -> GitHubProvenanceResolver | None:
+    if not settings.github_token:
+        return None
+    return GitHubProvenanceResolver(
+        token=settings.github_token,
+        base_url=settings.github_base_url,
+        agent_label_prefix=settings.github_agent_label_prefix,
+    )
+
+
 @lru_cache
 def get_analysis_service() -> AnalysisService:
     store = get_store()
     detection = get_detection_service()
     analytics = get_analytics_service()
     governance = get_governance_service()
-    return AnalysisService(store, detection, governance, analytics)
+    github_resolver = get_github_resolver()
+    return AnalysisService(store, detection, governance, analytics, github_resolver)

app/provenance/github_resolver.py

@@ -0,0 +1,86 @@
+"""GitHub-backed provenance resolution."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Optional
+
+from github import Github, GithubException, Commit
+
+AGENT_TRAILER_PATTERN = re.compile(r"^Agent-ID:\s*(?P<agent>[^\s]+)", re.IGNORECASE)
+CO_AUTHOR_PATTERN = re.compile(r"Co-authored-by:\s*(?P<author>.+)", re.IGNORECASE)
+
+
+class GitHubProvenanceResolver:
+    """Resolve agent attribution using GitHub commit and PR metadata."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str | None = None,
+        agent_label_prefix: str = "agent:",
+    ) -> None:
+        self._agent_label_prefix = agent_label_prefix.lower()
+        if base_url:
+            self._client = Github(login_or_token=token, base_url=base_url.rstrip("/"))
+        else:
+            self._client = Github(login_or_token=token)
+
+    def resolve_agent(
+        self,
+        repo_full_name: str,
+        pr_number: str | None,
+        commit_sha: str | None,
+    ) -> tuple[Optional[str], Optional[str]]:
+        agent_id: Optional[str] = None
+        session_id: Optional[str] = None
+
+        if commit_sha:
+            agent_id, session_id = self._from_commit(repo_full_name, commit_sha)
+        if not agent_id and pr_number:
+            agent_id = self._from_pr_labels(repo_full_name, int(pr_number))
+        return agent_id, session_id
+
+    @lru_cache(maxsize=256)
+    def _fetch_commit(self, repo_full_name: str, sha: str) -> Optional[Commit.Commit]:
+        try:
+            repo = self._client.get_repo(repo_full_name)
+            return repo.get_commit(sha)
+        except GithubException:
+            return None
+
+    def _from_commit(self, repo_full_name: str, sha: str) -> tuple[Optional[str], Optional[str]]:
+        commit = self._fetch_commit(repo_full_name, sha)
+        if not commit:
+            return None, None
+        message = commit.commit.message or ""
+        for line in message.splitlines():
+            match = AGENT_TRAILER_PATTERN.match(line.strip())
+            if match:
+                return match.group("agent"), None
+        for line in message.splitlines():
+            match = CO_AUTHOR_PATTERN.match(line.strip())
+            if match and "copilot" in match.group("author").lower():
+                return "github-copilot", None
+        author_login = getattr(commit.author, "login", "") or ""
+        if author_login:
+            return author_login, None
+        return None, None
+
+    @lru_cache(maxsize=256)
+    def _fetch_pr_labels(self, repo_full_name: str, pr_number: int) -> list[str]:
+        try:
+            repo = self._client.get_repo(repo_full_name)
+            pr = repo.get_pull(pr_number)
+            return [label.name for label in pr.get_labels()]
+        except GithubException:
+            return []
+
+    def _from_pr_labels(self, repo_full_name: str, pr_number: int) -> Optional[str]:
+        for label in self._fetch_pr_labels(repo_full_name, pr_number):
+            lower = label.lower()
+            if lower.startswith(self._agent_label_prefix):
+                return label.split(":", 1)[-1].strip()
+        return None

app/services/analysis.py

@@ -4,6 +4,7 @@
 
 from datetime import datetime, timezone
 import time
+from typing import TYPE_CHECKING
 
 from fastapi import BackgroundTasks
 
@@ -23,6 +24,9 @@
 from app.services.governance import GovernanceService
 from app.telemetry import increment_analysis_ingestion, record_analysis_duration, record_analysis_findings
 
+if TYPE_CHECKING:
+    from app.provenance.github_resolver import GitHubProvenanceResolver
+
 
 def _now() -> datetime:
     return datetime.now(timezone.utc)
@@ -37,11 +41,13 @@ def __init__(
         detection_service: DetectionService,
         governance_service: GovernanceService,
         analytics_service: AnalyticsService,
+        github_resolver: "GitHubProvenanceResolver | None" = None,
     ) -> None:
         self._store = store
         self._detection = detection_service
         self._governance = governance_service
         self._analytics = analytics_service
+        self._github_resolver = github_resolver
 
     def ingest_analysis(
         self,
@@ -108,8 +114,8 @@ def execute_analysis(self, analysis_id: str) -> None:
             record.error_message = str(exc)
             self._store.update_analysis(record)
 
-    @staticmethod
     def _map_changed_line(
+        self,
         analysis_id: str,
         request: AnalysisIngestionRequest,
         payload: ChangedLinePayload,
@@ -124,6 +130,16 @@ def _map_changed_line(
             commit_sha=payload.attribution.commit_sha,
             provenance_marker=payload.attribution.provenance_marker,
         )
+        if not attribution.agent.agent_id:
+            agent_id, session_id = self._resolve_agent(
+                repo=request.repo,
+                pr_number=request.pr_number,
+                commit_sha=attribution.commit_sha,
+            )
+            if agent_id:
+                attribution.agent.agent_id = agent_id
+            if session_id:
+                attribution.agent_session_id = session_id
         return ChangedLine(
             analysis_id=analysis_id,
             repo_id=request.repo,
@@ -140,6 +156,17 @@ def _map_changed_line(
             attribution=attribution,
         )
 
+    def _resolve_agent(
+        self,
+        *,
+        repo: str,
+        pr_number: str,
+        commit_sha: str | None,
+    ) -> tuple[str | None, str | None]:
+        if not self._github_resolver:
+            return None, None
+        return self._github_resolver.resolve_agent(repo, pr_number, commit_sha)
+
     def list_findings(self, analysis_id: str) -> list[Finding]:
         return self._store.list_findings(analysis_id)
 

pyproject.toml

@@ -13,7 +13,8 @@ dependencies = [
     "redis>=5.0,<6.0",
     "semgrep>=1.64,<2.0",
     "opentelemetry-api>=1.25,<2.0",
-    "opentelemetry-sdk>=1.25,<2.0"
+    "opentelemetry-sdk>=1.25,<2.0",
+    "PyGithub>=2.4,<3.0"
 ]
 
 [project.optional-dependencies]

tests/provenance/test_github_resolver.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from app.provenance.github_resolver import GitHubProvenanceResolver
+
+
+class StubCommit:
+    def __init__(self, message: str, author_login: str | None = None):
+        self.commit = SimpleNamespace(message=message)
+        self.author = SimpleNamespace(login=author_login) if author_login else None
+
+
+def test_resolver_extracts_agent_from_commit_trailer(monkeypatch):
+    resolver = GitHubProvenanceResolver(token="token")
+    monkeypatch.setattr(
+        GitHubProvenanceResolver,
+        "_fetch_commit",
+        lambda self, repo, sha: StubCommit("Fix bug\nAgent-ID: claude-3-opus"),
+    )
+    agent, session = resolver.resolve_agent("acme/repo", "42", "abc123")
+    assert agent == "claude-3-opus"
+    assert session is None
+
+
+def test_resolver_uses_coauthor(monkeypatch):
+    resolver = GitHubProvenanceResolver(token="token")
+    message = "Refactor\nCo-authored-by: GitHub Copilot <copilot@example.com>"
+    monkeypatch.setattr(GitHubProvenanceResolver, "_fetch_commit", lambda self, repo, sha: StubCommit(message))
+    agent, _ = resolver.resolve_agent("acme/repo", None, "def456")
+    assert agent == "github-copilot"
+
+
+def test_resolver_falls_back_to_pr_labels(monkeypatch):
+    resolver = GitHubProvenanceResolver(token="token", agent_label_prefix="agent:")
+    monkeypatch.setattr(GitHubProvenanceResolver, "_fetch_commit", lambda self, repo, sha: None)
+    monkeypatch.setattr(GitHubProvenanceResolver, "_fetch_pr_labels", lambda self, repo, pr: ["Agent: gemini-pro"])
+    agent, _ = resolver.resolve_agent("acme/repo", "77", None)
+    assert agent == "gemini-pro"