Merge branch 'main' into cursor/askgh-search-scopes-0404

Author: brendan-kellam

.agents/skills/gh-stack/SKILL.md

@@ -0,0 +1,22 @@
+def finding_id($prefix):
+  if ((.title // "") | startswith($prefix + " ")) then
+    (.title | ltrimstr($prefix + " ") | split(": "))
+    | if length > 1 then .[0] else "" end
+  else
+    ""
+  end;
+
+($findings[0].cves | map(.cveId)) as $currentIds
+| map(
+    . + { findingId: finding_id($prefix) }
+    | .findingId as $findingId
+    | if .findingId == "" then
+        . + { action: "ignore" }
+      elif ($skipCodeql and (.findingId | startswith("codeql:"))) then
+        . + { action: "ignore" }
+      elif ($currentIds | index($findingId)) != null then
+        . + { action: "keep" }
+      else
+        . + { action: "close" }
+      end
+  )

.github/scripts/classify-vulnerability-issues.jq

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -z "${LINEAR_API_KEY:-}" ]]; then
+  echo "LINEAR_API_KEY is required" >&2
+  exit 1
+fi
+
+payload=$(cat)
+configured_attempts="${LINEAR_GRAPHQL_ATTEMPTS:-4}"
+retry_delay="${LINEAR_GRAPHQL_RETRY_DELAY_SECONDS:-2}"
+endpoint="${LINEAR_GRAPHQL_ENDPOINT:-https://api.linear.app/graphql}"
+is_mutation=$(jq -r '(.query // "") | test("^\\s*mutation(?:\\s|\\(|\\{)")' <<<"$payload")
+
+# Retrying a mutation after an ambiguous transport failure can replay a write
+# that Linear already committed. Queries are safe to retry; mutations fail
+# visibly after one attempt and rely on the workflow's reconciliation pass.
+if [[ "$is_mutation" == "true" ]]; then
+  attempts=1
+else
+  attempts="$configured_attempts"
+fi
+
+for ((attempt = 1; attempt <= attempts; attempt++)); do
+  response_file=$(mktemp)
+  http_code=""
+
+  if http_code=$(curl \
+    --silent \
+    --show-error \
+    --output "$response_file" \
+    --write-out '%{http_code}' \
+    --connect-timeout 10 \
+    --max-time 45 \
+    -X POST "$endpoint" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: $LINEAR_API_KEY" \
+    -d "$payload"); then
+    response=$(<"$response_file")
+    rm -f "$response_file"
+
+    if [[ "$http_code" =~ ^2[0-9][0-9]$ ]] && jq -e . >/dev/null 2>&1 <<<"$response"; then
+      printf '%s' "$response"
+      exit 0
+    fi
+
+    if [[ "$http_code" =~ ^(408|429|5[0-9][0-9])$ ]]; then
+      echo "Linear GraphQL returned transient HTTP $http_code (attempt $attempt/$attempts)." >&2
+    elif jq -e . >/dev/null 2>&1 <<<"$response"; then
+      # Preserve structured non-retryable errors so the workflow can report
+      # the GraphQL response rather than replacing it with a transport error.
+      printf '%s' "$response"
+      exit 0
+    else
+      echo "Linear GraphQL returned a non-JSON response (HTTP $http_code, attempt $attempt/$attempts)." >&2
+    fi
+  else
+    curl_status=$?
+    response=$(<"$response_file")
+    rm -f "$response_file"
+    echo "Linear GraphQL request failed (curl $curl_status, HTTP ${http_code:-unknown}, attempt $attempt/$attempts)." >&2
+  fi
+
+  if ((attempt < attempts)); then
+    sleep "$retry_delay"
+  fi
+done
+
+echo "Linear GraphQL did not return a valid JSON response after $attempts attempts." >&2
+exit 1

.github/scripts/linear-graphql-request.sh

@@ -0,0 +1,32 @@
+def finding_id($prefix):
+  if ((.title // "") | startswith($prefix + " ")) then
+    (.title | ltrimstr($prefix + " ") | split(": "))
+    | if length > 1 then .[0] else "" end
+  else
+    ""
+  end;
+
+[
+  .data.issues.nodes[]?
+  | select(finding_id($prefix) == $findingId)
+] as $matches
+| ($matches | map(select(.state.type != "completed" and .state.type != "canceled" and .state.type != "duplicate")) | .[0]) as $open
+| ($matches | map(select(.state.type == "completed" or .state.type == "canceled")) | .[0]) as $reopenable
+| ($open // $reopenable // $matches[0]) as $chosen
+| if $chosen == null then
+    {
+      linearIssueExists: false,
+      linearIssueId: "",
+      linearIssueIdentifier: "",
+      linearIssueUrl: "",
+      linearIssueClosed: false
+    }
+  else
+    {
+      linearIssueExists: true,
+      linearIssueId: $chosen.id,
+      linearIssueIdentifier: $chosen.identifier,
+      linearIssueUrl: $chosen.url,
+      linearIssueClosed: (($chosen.state.type == "completed") or ($chosen.state.type == "canceled"))
+    }
+  end

.github/scripts/match-vulnerability-issue.jq

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MATCH_FILTER="$SCRIPT_DIR/match-vulnerability-issue.jq"
+CLASSIFY_FILTER="$SCRIPT_DIR/classify-vulnerability-issues.jq"
+LINEAR_REQUEST="$SCRIPT_DIR/linear-graphql-request.sh"
+WORKFLOW_FILE="$SCRIPT_DIR/../workflows/vulnerability-triage.yml"
+PREFIX="[sourcebot-dev/example]"
+
+assert_json() {
+  local description="$1"
+  local actual="$2"
+  local expected="$3"
+
+  if ! jq -e --argjson expected "$expected" '. == $expected' <<<"$actual" >/dev/null; then
+    echo "FAIL: $description"
+    echo "Expected: $expected"
+    echo "Actual:   $actual"
+    exit 1
+  fi
+}
+
+assert_workflow_contains() {
+  local description="$1"
+  local expected="$2"
+
+  if ! grep -Fq -- "$expected" "$WORKFLOW_FILE"; then
+    echo "FAIL: $description"
+    echo "Expected workflow to contain: $expected"
+    exit 1
+  fi
+}
+
+assert_workflow_contains "checks out assets from the called workflow repository" 'repository: ${{ job.workflow_repository }}'
+assert_workflow_contains "pins assets to the called workflow revision" 'ref: ${{ job.workflow_sha }}'
+assert_workflow_contains "uses the shared match filter" '-f .vulnerability-triage-workflow/.github/scripts/match-vulnerability-issue.jq'
+assert_workflow_contains "uses the shared classification filter" '-f .vulnerability-triage-workflow/.github/scripts/classify-vulnerability-issues.jq'
+assert_workflow_contains "uses the retrying Linear GraphQL client" '.vulnerability-triage-workflow/.github/scripts/linear-graphql-request.sh'
+
+FAKE_CURL_DIR=$(mktemp -d)
+FAKE_CURL_COUNT=$(mktemp)
+trap 'rm -rf "$FAKE_CURL_DIR"; rm -f "$FAKE_CURL_COUNT"' EXIT
+printf '0\n' > "$FAKE_CURL_COUNT"
+
+cat > "$FAKE_CURL_DIR/curl" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+output_file=""
+while (($# > 0)); do
+  case "$1" in
+    --output)
+      output_file="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+count=$(( $(<"$FAKE_CURL_COUNT") + 1 ))
+printf '%s\n' "$count" > "$FAKE_CURL_COUNT"
+if ((count < 3)); then
+  printf 'Bad Gateway' > "$output_file"
+  printf '502'
+else
+  printf '{"data":{"ok":true}}' > "$output_file"
+  printf '200'
+fi
+EOF
+chmod +x "$FAKE_CURL_DIR/curl"
+
+LINEAR_RESPONSE=$(
+  PATH="$FAKE_CURL_DIR:$PATH" \
+    FAKE_CURL_COUNT="$FAKE_CURL_COUNT" \
+    LINEAR_API_KEY="test-key" \
+    LINEAR_GRAPHQL_ATTEMPTS=3 \
+    LINEAR_GRAPHQL_RETRY_DELAY_SECONDS=0 \
+    "$LINEAR_REQUEST" <<<'{"query":"query { viewer { id } }"}'
+)
+assert_json "retries non-JSON Linear responses" "$LINEAR_RESPONSE" '{"data":{"ok":true}}'
+if [[ "$(<"$FAKE_CURL_COUNT")" != "3" ]]; then
+  echo "FAIL: expected Linear request helper to retry twice"
+  exit 1
+fi
+
+printf '0\n' > "$FAKE_CURL_COUNT"
+if PATH="$FAKE_CURL_DIR:$PATH" \
+  FAKE_CURL_COUNT="$FAKE_CURL_COUNT" \
+  LINEAR_API_KEY="test-key" \
+  LINEAR_GRAPHQL_ATTEMPTS=3 \
+  LINEAR_GRAPHQL_RETRY_DELAY_SECONDS=0 \
+  "$LINEAR_REQUEST" <<<'{"query":"mutation { issueCreate(input: {}) { success } }"}' >/dev/null 2>&1; then
+  echo "FAIL: ambiguous Linear mutations must not be retried"
+  exit 1
+fi
+if [[ "$(<"$FAKE_CURL_COUNT")" != "1" ]]; then
+  echo "FAIL: expected exactly one Linear mutation attempt"
+  exit 1
+fi
+
+match() {
+  local finding_id="$1"
+  jq -c --arg prefix "$PREFIX" --arg findingId "$finding_id" -f "$MATCH_FILTER"
+}
+
+EMPTY_MATCH='{"linearIssueExists":false,"linearIssueId":"","linearIssueIdentifier":"","linearIssueUrl":"","linearIssueClosed":false}'
+OPEN_MATCH='{"linearIssueExists":true,"linearIssueId":"open-id","linearIssueIdentifier":"SOU-2","linearIssueUrl":"https://linear.app/SOU-2","linearIssueClosed":false}'
+CLOSED_MATCH='{"linearIssueExists":true,"linearIssueId":"closed-id","linearIssueIdentifier":"SOU-1","linearIssueUrl":"https://linear.app/SOU-1","linearIssueClosed":true}'
+
+NO_ISSUES='{"data":{"issues":{"nodes":[]}}}'
+assert_json "creates when no Linear issue exists" "$(match CVE-2026-123 <<<"$NO_ISSUES")" "$EMPTY_MATCH"
+
+ISSUES='{
+  "data": {
+    "issues": {
+      "nodes": [
+        {
+          "id": "closed-id",
+          "identifier": "SOU-1",
+          "url": "https://linear.app/SOU-1",
+          "title": "[sourcebot-dev/example] CVE-2026-123: old finding",
+          "state": {"type": "completed"}
+        },
+        {
+          "id": "open-id",
+          "identifier": "SOU-2",
+          "url": "https://linear.app/SOU-2",
+          "title": "[sourcebot-dev/example] CVE-2026-123: current finding",
+          "state": {"type": "started"}
+        },
+        {
+          "id": "prefix-collision",
+          "identifier": "SOU-3",
+          "url": "https://linear.app/SOU-3",
+          "title": "[sourcebot-dev/example] CVE-2026-1234: different finding",
+          "state": {"type": "started"}
+        },
+        {
+          "id": "other-repo",
+          "identifier": "SOU-4",
+          "url": "https://linear.app/SOU-4",
+          "title": "[sourcebot-dev/other] CVE-2026-123: different repository",
+          "state": {"type": "started"}
+        },
+        {
+          "id": "duplicate-id",
+          "identifier": "SOU-5",
+          "url": "https://linear.app/SOU-5",
+          "title": "[sourcebot-dev/example] CVE-2026-123: duplicate marker",
+          "state": {"type": "duplicate"}
+        }
+      ]
+    }
+  }
+}'
+assert_json "deduplicates by exact finding id and prefers an open issue" "$(match CVE-2026-123 <<<"$ISSUES")" "$OPEN_MATCH"
+assert_json "does not confuse an id with a longer id" "$(match CVE-2026-12 <<<"$ISSUES")" "$EMPTY_MATCH"
+
+CLOSED_ONLY="$(jq '.data.issues.nodes |= map(select(.id == "closed-id"))' <<<"$ISSUES")"
+assert_json "reopens a closed issue when the finding returns" "$(match CVE-2026-123 <<<"$CLOSED_ONLY")" "$CLOSED_MATCH"
+
+DUPLICATE_ONLY="$(jq '.data.issues.nodes |= map(select(.id == "duplicate-id"))' <<<"$ISSUES")"
+DUPLICATE_MATCH='{"linearIssueExists":true,"linearIssueId":"duplicate-id","linearIssueIdentifier":"SOU-5","linearIssueUrl":"https://linear.app/SOU-5","linearIssueClosed":false}'
+assert_json "does not reopen a duplicate marker" "$(match CVE-2026-123 <<<"$DUPLICATE_ONLY")" "$DUPLICATE_MATCH"
+
+FINDINGS='{
+  "cves": [
+    {"cveId": "CVE-2026-123"},
+    {"cveId": "GHSA-abcd-efgh-ijkl"},
+    {"cveId": "codeql:js/example-rule"}
+  ]
+}'
+OPEN_ISSUES='[
+  {
+    "id": "keep-cve",
+    "title": "[sourcebot-dev/example] CVE-2026-123: still present"
+  },
+  {
+    "id": "keep-codeql",
+    "title": "[sourcebot-dev/example] codeql:js/example-rule: still present"
+  },
+  {
+    "id": "close-cve",
+    "title": "[sourcebot-dev/example] CVE-2025-999: resolved"
+  },
+  {
+    "id": "close-prefix-collision",
+    "title": "[sourcebot-dev/example] CVE-2026-12: resolved"
+  },
+  {
+    "id": "ignore-other-repo",
+    "title": "[sourcebot-dev/other] CVE-2025-999: unrelated"
+  },
+  {
+    "id": "ignore-unmanaged",
+    "title": "[sourcebot-dev/example] maintenance without a finding delimiter"
+  }
+]'
+
+CLASSIFIED="$(jq -c --arg prefix "$PREFIX" --argjson skipCodeql false --slurpfile findings <(printf '%s\n' "$FINDINGS") -f "$CLASSIFY_FILTER" <<<"$OPEN_ISSUES")"
+assert_json "keeps every exact current finding" "$(jq -c '[.[] | select(.action == "keep") | .id]' <<<"$CLASSIFIED")" '["keep-cve","keep-codeql"]'
+assert_json "closes only resolved managed findings" "$(jq -c '[.[] | select(.action == "close") | .id]' <<<"$CLASSIFIED")" '["close-cve","close-prefix-collision"]'
+assert_json "ignores unrelated titles and repositories" "$(jq -c '[.[] | select(.action == "ignore") | .id]' <<<"$CLASSIFIED")" '["ignore-other-repo","ignore-unmanaged"]'
+
+EMPTY_FINDINGS='{"cves":[]}'
+CLASSIFIED_EMPTY="$(jq -c --arg prefix "$PREFIX" --argjson skipCodeql false --slurpfile findings <(printf '%s\n' "$EMPTY_FINDINGS") -f "$CLASSIFY_FILTER" <<<"$OPEN_ISSUES")"
+assert_json "closes all managed issues when a complete scan is clean" "$(jq -c '[.[] | select(.action == "close") | .id]' <<<"$CLASSIFIED_EMPTY")" '["keep-cve","keep-codeql","close-cve","close-prefix-collision"]'
+
+CLASSIFIED_WITH_CODEQL_SKIPPED="$(jq -c --arg prefix "$PREFIX" --argjson skipCodeql true --slurpfile findings <(printf '%s\n' "$EMPTY_FINDINGS") -f "$CLASSIFY_FILTER" <<<"$OPEN_ISSUES")"
+assert_json "preserves CodeQL issues when CodeQL is unavailable" "$(jq -c '[.[] | select(.action == "ignore") | .id]' <<<"$CLASSIFIED_WITH_CODEQL_SKIPPED")" '["keep-codeql","ignore-other-repo","ignore-unmanaged"]'
+assert_json "still closes resolved non-CodeQL issues when CodeQL is unavailable" "$(jq -c '[.[] | select(.action == "close") | .id]' <<<"$CLASSIFIED_WITH_CODEQL_SKIPPED")" '["keep-cve","close-cve","close-prefix-collision"]'
+
+echo "All vulnerability triage reconciliation tests passed."