list-code-alerts.sh

#!/usr/bin/env bash
# list-code-alerts.sh
# ====================
# List code scanning (CodeQL) alerts for a repository or organization
# via the GitHub REST API.
#
# Usage (single repo):
#   export GH_TOKEN="ghp_your_token_here"
#   GH_REPO="owner/repo-name" ./scripts/list-code-alerts.sh
#
# Usage (org-wide):
#   export GH_TOKEN="ghp_your_token_here"
#   GH_ORG="your-org-name" ./scripts/list-code-alerts.sh
#
# Options:
#   STATE     Alert state: open | dismissed | fixed | all (default: open)
#   SEVERITY  Filter by severity: critical | high | medium | low (default: all)
#   TOOL      Filter by tool name (default: all tools; e.g., CodeQL)
#   FORMAT    Output format: table | json | csv (default: table)
#
# Requirements:
#   - gh CLI
#   - jq

set -euo pipefail

# ── Configuration ─────────────────────────────────────────────────────────────

GH_TOKEN="${GH_TOKEN:?Error: GH_TOKEN environment variable is required}"
GH_REPO="${GH_REPO:-}"
GH_ORG="${GH_ORG:-}"
STATE="${STATE:-open}"
SEVERITY="${SEVERITY:-}"
TOOL="${TOOL:-}"
FORMAT="${FORMAT:-table}"

# ── Validate ──────────────────────────────────────────────────────────────────

if [ -z "${GH_REPO}" ] && [ -z "${GH_ORG}" ]; then
  echo "Error: Either GH_REPO (owner/repo) or GH_ORG must be set." >&2
  exit 1
fi

# ── Fetch Alerts ──────────────────────────────────────────────────────────────

fetch_repo_code_alerts() {
  local repo="$1"
  local args=(--field "state=${STATE}" --field "per_page=100")

  [ -n "${SEVERITY}" ] && args+=(--field "severity=${SEVERITY}")
  [ -n "${TOOL}" ] && args+=(--field "tool_name=${TOOL}")

  gh api \
    --paginate \
    "repos/${repo}/code-scanning/alerts" \
    "${args[@]}" \
    --jq ".[].{
      number: .number,
      rule: .rule.id,
      severity: (.rule.security_severity_level // .rule.severity // \"unknown\"),
      state: .state,
      dismissed_reason: (.dismissed_reason // \"N/A\"),
      tool: .tool.name,
      location: .most_recent_instance.location.path,
      line: (.most_recent_instance.location.start_line // 0),
      repository: \"${repo}\"
    }" 2>/dev/null
}

fetch_org_code_alerts() {
  local org="$1"
  local args=(--field "state=${STATE}" --field "per_page=100")

  [ -n "${SEVERITY}" ] && args+=(--field "severity=${SEVERITY}")
  [ -n "${TOOL}" ] && args+=(--field "tool_name=${TOOL}")

  gh api \
    --paginate \
    "orgs/${org}/code-scanning/alerts" \
    "${args[@]}" \
    --jq ".[].{
      number: .number,
      rule: .rule.id,
      severity: (.rule.security_severity_level // .rule.severity // \"unknown\"),
      state: .state,
      dismissed_reason: (.dismissed_reason // \"N/A\"),
      tool: .tool.name,
      location: .most_recent_instance.location.path,
      line: (.most_recent_instance.location.start_line // 0),
      repository: .repository.full_name
    }" 2>/dev/null
}

# ── Format Output ─────────────────────────────────────────────────────────────

format_table() {
  local data="$1"

  printf "\n%-8s %-35s %-10s %-12s %-12s %-40s\n" \
    "NUMBER" "RULE" "SEVERITY" "STATE" "TOOL" "LOCATION"
  printf "%s\n" "$(printf '─%.0s' {1..120})"

  echo "${data}" | jq -r \
    '"\(.number)\t\(.rule)\t\(.severity)\t\(.state)\t\(.tool)\t\(.location // "N/A"):\(.line)"' | \
    while IFS=$'\t' read -r number rule severity state tool location; do
      printf "%-8s %-35s %-10s %-12s %-12s %-40s\n" \
        "${number}" "${rule}" "${severity}" "${state}" "${tool}" "${location}"
    done
}

format_csv() {
  local data="$1"
  echo "number,rule,severity,state,dismissed_reason,tool,location,line,repository"
  echo "${data}" | jq -r \
    '"\(.number),\(.rule),\(.severity),\(.state),\(.dismissed_reason),\(.tool),\(.location // ""),\(.line),\(.repository)"'
}

format_json() {
  echo "${1}" | jq '.'
}

severity_summary() {
  local data="$1"
  echo ""
  echo "── Severity Breakdown ──────────────────────"
  echo "${data}" | jq -r '.[].severity' | \
    sort | uniq -c | sort -rn | \
    while read -r count severity; do
      printf "  %-12s: %s\n" "${severity}" "${count}"
    done
}

# ── Main ──────────────────────────────────────────────────────────────────────

main() {
  local raw_data

  echo "Fetching code scanning alerts (state: ${STATE})..."

  if [ -n "${GH_REPO}" ]; then
    raw_data=$(fetch_repo_code_alerts "${GH_REPO}")
  else
    raw_data=$(fetch_org_code_alerts "${GH_ORG}")
  fi

  if [ -z "${raw_data}" ]; then
    echo "No alerts found matching criteria."
    exit 0
  fi

  local count
  count=$(echo "${raw_data}" | jq -s 'length')
  echo "Found ${count} alert(s)."

  case "${FORMAT}" in
    table)
      format_table "$(echo "${raw_data}" | jq -s '.')"
      severity_summary "$(echo "${raw_data}" | jq -s '.')"
      ;;
    csv)
      format_csv "$(echo "${raw_data}" | jq -s '.')"
      ;;
    json)
      format_json "$(echo "${raw_data}" | jq -s '.')"
      ;;
    *)
      echo "Unknown format: ${FORMAT}. Use: table | csv | json" >&2
      exit 1
      ;;
  esac

  echo ""
  echo "Total: ${count} code scanning alert(s)"
}

main "$@"