@docupace/pipeline 1.0.121 → 1.0.122-connect.0

package/bin/tenable-scan.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+#
+# Tenable Cloud Security container image scan.
+#
+# Builds the image, exports it to a tar, and scans the tar with
+# tenable/cloud-security-scanner. The archive route is used deliberately: the
+# scanner container has no access to the host docker daemon, so --name alone
+# would make it try to pull the image from a registry — which fails for an
+# image we've only just built locally.
+#
+# A repo can hold more than one app, so this scans every image listed in
+# SCAN_TARGETS (shared with the Xray step) rather than a single build context.
+#
+# Required (set as Bitbucket pipeline variables):
+#   TENABLE_API_TOKEN, TENABLE_API_URL
+# Optional:
+#   SCAN_TARGETS                  label:auditDir:buildContext:dockerfile[;...]
+#                                 auditDir is ignored here; a target with an
+#                                 empty buildContext is skipped
+#   TENABLE_FAIL_ON_MIN_SEVERITY  Low|Medium|High|Critical — fail the step at or
+#                                 above this severity (default: report only)
+#   TENABLE_MIN_SEVERITY          lowest severity to include (default Medium)
+#   XRAY_BUILD_CONTEXT            single-target fallback when SCAN_TARGETS unset
+#   XRAY_DOCKERFILE_PATH          Dockerfile (default <context>/Dockerfile)
+#   TENABLE_IMAGE                 scan this image instead of building one
+#   TENABLE_SCANNER_IMAGE         override the scanner image/tag
+
+set -uo pipefail
+
+REPORT_DIR="${TENABLE_REPORT_DIR:-tenable-report}"
+SCANNER_IMAGE="${TENABLE_SCANNER_IMAGE:-tenable/cloud-security-scanner:latest}"
+MIN_SEVERITY="${TENABLE_MIN_SEVERITY:-Medium}"
+
+if [[ -z "${TENABLE_API_TOKEN:-}" || -z "${TENABLE_API_URL:-}" ]]; then
+  echo "TENABLE_API_TOKEN / TENABLE_API_URL not set — skipping Tenable scan."
+  exit 0
+fi
+
+# These runners inherit DOCKER_HOST=tcp://localhost:2375 with no daemon there,
+# and DOCKER_CONTEXT is reserved by the docker CLI for selecting a named context.
+export DOCKER_HOST=""
+unset DOCKER_CONTEXT
+
+COMMIT="${BITBUCKET_COMMIT:-local}"
+SHORT_SHA="${COMMIT:0:7}"
+
+# Git metadata is auto-detected from a mounted repo; pass it explicitly so the
+# scan is attributed correctly regardless of clone depth or mount layout.
+CODE_BRANCH="${BITBUCKET_BRANCH:-${BITBUCKET_PR_DESTINATION_BRANCH:-unknown}}"
+CODE_REPO_URL="https://bitbucket.org/${BITBUCKET_WORKSPACE:-unknown}/${BITBUCKET_REPO_SLUG:-unknown}"
+CODE_USER="$(git log -1 --pretty=format:'%an' 2>/dev/null || echo 'bitbucket-pipelines')"
+[[ -z "${CODE_USER}" ]] && CODE_USER="bitbucket-pipelines"
+
+# Pipeline attribution. The scanner requires --pipeline-run-url as soon as any
+# pipeline flag is supplied, so default it to this run's URL rather than letting
+# a half-set trio fail validation. The TENABLE_PIPELINE_RUN_* variables from the
+# docs are honoured when present.
+RUN_ID="${TENABLE_PIPELINE_RUN_ID:-${BITBUCKET_BUILD_NUMBER:-}}"
+RUN_TRIGGER="${TENABLE_PIPELINE_RUN_TRIGGER:-${BITBUCKET_PR_ID:+pull_request}}"
+RUN_TRIGGER="${RUN_TRIGGER:-push}"
+RUN_URL="${TENABLE_PIPELINE_RUN_URL:-}"
+if [[ -z "${RUN_URL}" && -n "${BITBUCKET_BUILD_NUMBER:-}" ]]; then
+  RUN_URL="https://bitbucket.org/${BITBUCKET_WORKSPACE:-unknown}/${BITBUCKET_REPO_SLUG:-unknown}/pipelines/results/${BITBUCKET_BUILD_NUMBER}"
+fi
+
+mkdir -p "${REPORT_DIR}"
+
+# Scans one image and writes its reports to ${REPORT_DIR}/<slug>-tenable.*
+# Args: slug, build context, dockerfile, pre-built image ("" to build)
+# Returns the scanner's exit code.
+scan_one() {
+  local slug="$1" build_context="$2" dockerfile="$3" prebuilt="$4"
+  local scan_target built_image="" work
+
+  if [[ -n "${prebuilt}" ]]; then
+    scan_target="${prebuilt}"
+    echo "Scanning pre-existing image ${scan_target}"
+  elif [[ -f "${dockerfile}" ]]; then
+    scan_target="${BITBUCKET_REPO_SLUG:-image}-${slug}:tenable-${SHORT_SHA}"
+    echo "Building ${scan_target} from ${dockerfile} (context ${build_context})..."
+    # --load is buildx-only; fall back to the legacy builder, which loads into
+    # the local image store anyway.
+    local build_args=("${build_context}" "--file" "${dockerfile}" "--tag" "${scan_target}")
+    if docker buildx version >/dev/null 2>&1; then
+      build_args+=("--load")
+    fi
+    if ! docker build "${build_args[@]}"; then
+      echo "Docker build failed for '${slug}' — skipping its Tenable scan."
+      return 1
+    fi
+    built_image="${scan_target}"
+  else
+    echo "No Dockerfile at ${dockerfile} — nothing to scan for '${slug}'."
+    return 0
+  fi
+
+  # Keep the work dir inside the build directory: it must be bind-mountable, and
+  # on some hosts the system temp dir is a symlink that docker won't follow.
+  work="$(mktemp -d "$(pwd)/.tenable-work.XXXXXX")"
+
+  # The scanner runs in its own container with no access to the host daemon, so
+  # hand it the image as a tar rather than a name to resolve.
+  echo "Exporting ${scan_target} to an archive..."
+  if ! docker save "${scan_target}" -o "${work}/image.tar"; then
+    echo "docker save failed for '${slug}' — skipping its Tenable scan."
+    rm -rf "${work}"
+    [[ -n "${built_image}" ]] && docker rmi -f "${built_image}" >/dev/null 2>&1
+    return 1
+  fi
+
+  # --output-path must already exist, and the scanner validates it before scanning.
+  mkdir -p "${work}/out"
+
+  local scan_args=(
+    "container-image" "scan"
+    "--archive-path" "/tmp/tenable/image.tar"
+    "--name" "${scan_target}"
+    "--code-branch" "${CODE_BRANCH}"
+    "--code-commit-hash" "${COMMIT}"
+    "--code-commit-user" "${CODE_USER}"
+    "--code-repository-url" "${CODE_REPO_URL}"
+    "--min-severity" "${MIN_SEVERITY}"
+    "--output-file-formats" "Json,Md,JUnit"
+    "--output-path" "/tmp/tenable/out"
+    "--output-file-name" "${slug}-tenable"
+    "--no-color"
+  )
+  # All three travel together, or none of them do.
+  if [[ -n "${RUN_ID}" && -n "${RUN_URL}" ]]; then
+    scan_args+=(
+      "--pipeline-run-id" "${RUN_ID}"
+      "--pipeline-run-trigger" "${RUN_TRIGGER}"
+      "--pipeline-run-url" "${RUN_URL}"
+    )
+  fi
+  if [[ -n "${TENABLE_FAIL_ON_MIN_SEVERITY:-}" ]]; then
+    scan_args+=("--fail-on-min-severity" "${TENABLE_FAIL_ON_MIN_SEVERITY}")
+  fi
+
+  echo "Running Tenable scan for '${slug}' (min-severity=${MIN_SEVERITY}${TENABLE_FAIL_ON_MIN_SEVERITY:+, fail-on=${TENABLE_FAIL_ON_MIN_SEVERITY}})..."
+  docker run --rm \
+    --workdir /tmp/tenable \
+    --volume "${work}:/tmp/tenable" \
+    --env TENABLE_API_TOKEN \
+    --env TENABLE_API_URL \
+    --pull=always \
+    "${SCANNER_IMAGE}" "${scan_args[@]}"
+  local scan_exit=$?
+
+  # Collect reports even on a non-zero exit — a threshold failure still produces them.
+  if compgen -G "${work}/out/*" > /dev/null; then
+    cp -R "${work}/out/." "${REPORT_DIR}/"
+  else
+    echo "Tenable produced no report files for '${slug}'."
+  fi
+
+  # Surface the summary in the build log.
+  if [[ -f "${REPORT_DIR}/${slug}-tenable.md" ]]; then
+    echo "--- Tenable summary: ${slug} ---"
+    head -60 "${REPORT_DIR}/${slug}-tenable.md"
+  fi
+
+  rm -rf "${work}"
+  [[ -n "${built_image}" ]] && docker rmi -f "${built_image}" >/dev/null 2>&1
+  return "${scan_exit}"
+}
+
+# TENABLE_IMAGE names an already-built image, which is inherently single-target.
+if [[ -n "${TENABLE_IMAGE:-}" ]]; then
+  scan_one "image" "" "" "${TENABLE_IMAGE}"
+  EXIT_CODE=$?
+else
+  if [[ -z "${SCAN_TARGETS:-}" ]]; then
+    CTX="${XRAY_BUILD_CONTEXT:-.}"
+    SCAN_TARGETS="app::${CTX}:${XRAY_DOCKERFILE_PATH:-${CTX}/Dockerfile}"
+    echo "SCAN_TARGETS not set — scanning a single target: ${SCAN_TARGETS}"
+  fi
+
+  EXIT_CODE=0
+  SCANNED=0
+  # Split on ';' into targets, then on ':' into label:auditDir:context:dockerfile.
+  # auditDir belongs to the Xray step and is ignored here.
+  IFS=';' read -r -a TARGETS <<< "${SCAN_TARGETS}"
+  for target in "${TARGETS[@]}"; do
+    [[ -z "${target}" ]] && continue
+    IFS=':' read -r t_label _t_audit t_context t_dockerfile <<< "${target}"
+    [[ -z "${t_label}" ]] && t_label="app"
+    # Labels reach filenames and image tags, so keep them tame.
+    t_slug="$(printf '%s' "${t_label}" | tr -c 'A-Za-z0-9._-' '-')"
+    if [[ -z "${t_context}" ]]; then
+      echo "Target '${t_label}' has no build context — skipping its image scan."
+      continue
+    fi
+    [[ -z "${t_dockerfile}" ]] && t_dockerfile="${t_context}/Dockerfile"
+
+    echo "=============================================================="
+    echo "Tenable target '${t_label}'"
+    echo "=============================================================="
+    scan_one "${t_slug}" "${t_context}" "${t_dockerfile}" ""
+    rc=$?
+    SCANNED=$((SCANNED + 1))
+    # Report the worst outcome across targets, so one clean app can't mask
+    # another's failure.
+    [[ "${rc}" -ne 0 ]] && EXIT_CODE="${rc}"
+  done
+
+  if [[ "${SCANNED}" -eq 0 ]]; then
+    echo "No scannable targets in SCAN_TARGETS — nothing to do."
+  fi
+fi
+
+if compgen -G "${REPORT_DIR}/*" > /dev/null; then
+  echo "Reports written to ${REPORT_DIR}/:"
+  ls -1 "${REPORT_DIR}"
+fi
+
+if [[ "${EXIT_CODE}" -ne 0 ]]; then
+  if [[ -n "${TENABLE_FAIL_ON_MIN_SEVERITY:-}" ]]; then
+    echo "Tenable scan exited ${EXIT_CODE} — findings at or above ${TENABLE_FAIL_ON_MIN_SEVERITY}, or a scan itself failed."
+  else
+    echo "Tenable scan exited ${EXIT_CODE}."
+  fi
+fi
+exit "${EXIT_CODE}"

package/bin/xray-bitbucket-insights.sh

@@ -0,0 +1,287 @@
+#!/usr/bin/env bash
+#
+# Publishes Xray findings to Bitbucket Code Insights, so results show up on the
+# commit and in the pull request instead of only inside a downloaded artifact.
+#
+# Usage: xray-bitbucket-insights.sh <label:file.json> [label:file.json ...]
+#
+# Auth, in order of preference:
+#   1. the pipelines auth proxy on localhost:29418, which signs requests for us.
+#      It only exists on Atlassian-hosted runners, and the API must then be
+#      called over http:// (not https://) so the proxy can inject the header.
+#   2. BITBUCKET_ACCESS_TOKEN / BITBUCKET_STEP_OAUTH_TOKEN as a bearer token.
+#   3. BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD as basic auth.
+# Self-hosted runners (runs-on: self.hosted) have no proxy, so one of 2 or 3 is
+# required there — otherwise this exits without publishing.
+#
+# Behaviour:
+#   - one report per commit (ID: xray-security), result PASSED/FAILED
+#   - annotations for findings that have a file path (secrets/SAST/IaC), so they
+#     appear inline in the PR diff
+#   - dependency findings have no file, so they are summarised in the report card
+#   - never fails the build: a reporting problem shouldn't mask a scan result
+#
+# XRAY_INSIGHTS_FAIL_ON: lowest severity that marks the report FAILED.
+#   critical | high (default) | medium | low | never
+
+set -uo pipefail
+
+if [[ -z "${BITBUCKET_COMMIT:-}" ]]; then
+  echo "Not running in Bitbucket Pipelines (BITBUCKET_COMMIT unset) — skipping Code Insights."
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq not available — skipping Code Insights."
+  exit 0
+fi
+
+WORKSPACE="${BITBUCKET_WORKSPACE:-${BITBUCKET_REPO_OWNER:-}}"
+REPO="${BITBUCKET_REPO_SLUG:-}"
+COMMIT="${BITBUCKET_COMMIT}"
+REPORT_ID="xray-security"
+PROXY="${BITBUCKET_API_PROXY:-http://localhost:29418}"
+FAIL_ON="${XRAY_INSIGHTS_FAIL_ON:-high}"
+API_PATH="2.0/repositories/${WORKSPACE}/${REPO}/commit/${COMMIT}/reports/${REPORT_ID}"
+
+api() {
+  # $1 method, $2 url, $3 optional body file
+  local method="$1" url="$2" body="${3:-}"
+  if [[ -n "$body" ]]; then
+    curl -sS "${CURL_AUTH[@]}" -X "$method" "$url" \
+      -H 'Content-Type: application/json' --data-binary "@${body}" \
+      -w '\n%{http_code}' 2>&1
+  else
+    curl -sS "${CURL_AUTH[@]}" -X "$method" "$url" -w '\n%{http_code}' 2>&1
+  fi
+}
+
+TMP_ALL="$(mktemp)"
+TMP_BODY="$(mktemp)"
+TMP_ANN="$(mktemp)"
+trap 'rm -f "$TMP_ALL" "$TMP_BODY" "$TMP_ANN"' EXIT
+# JSONL, one finding per line: a real scan's findings exceed Linux's 128 KB
+# per-argument limit, so they can't be passed through --argjson.
+: > "$TMP_ALL"
+
+# ---------------------------------------------------------------------------
+# Collect findings from every simple-json input.
+# ---------------------------------------------------------------------------
+PARSED_SCANS=0
+SKIPPED_SCANS=""
+for arg in "$@"; do
+  label="${arg%%:*}"
+  file="${arg#*:}"
+  if [[ ! -s "$file" ]] || ! jq empty "$file" >/dev/null 2>&1; then
+    SKIPPED_SCANS="${SKIPPED_SCANS}${SKIPPED_SCANS:+, }${label}"
+    continue
+  fi
+  PARSED_SCANS=$((PARSED_SCANS + 1))
+
+  jq -c --arg scan "$label" '
+    def sev: (.severity // "Unknown");
+    def sca(rows; kind): (rows // [])[] | {
+      scan: $scan, kind: kind, severity: sev,
+      id: (((.cves // []) | map(.cve // empty) | join(", ")) as $c
+           | if $c == "" then (.issueId // "N/A") else $c end),
+      package: ((.impactedPackageName // "N/A") + ":" + (.impactedPackageVersion // "")),
+      fixed: ((.fixedVersions // []) | join(", ")),
+      summary: (.summary // ""),
+      applicable: (.applicable // ""),
+      path: "", line: 0
+    };
+    def code(rows; kind): (rows // [])[] | {
+      scan: $scan, kind: kind, severity: sev,
+      id: (.ruleId // "N/A"),
+      package: (.finding // .scannerShortDescription // "N/A"),
+      fixed: "",
+      summary: (.scannerDescription // .scannerShortDescription // .finding // ""),
+      applicable: "",
+      path: (.file // ""), line: (.startLine // 0)
+    };
+    [ sca(.vulnerabilities; "Vulnerability")
+    , sca(.securityViolations; "Security violation")
+    , sca(.licensesViolations; "License violation")
+    , sca(.operationalRiskViolations; "Operational risk")
+    , code(.secrets; "Secret")
+    , code(.secretsViolations; "Secret violation")
+    , code(.sast; "SAST")
+    , code(.sastViolations; "SAST violation")
+    , code(.iac; "IaC")
+    , code(.iacViolations; "IaC violation")
+    , code(.maliciousCode; "Malicious code")
+    ] | flatten | .[]
+  ' "$file" 2>/dev/null >> "$TMP_ALL"
+done
+
+if [[ "$PARSED_SCANS" -eq 0 ]]; then
+  echo "No parseable scan output — publishing a PENDING Code Insights report."
+fi
+
+count_sev() { jq -s --arg s "$1" '[.[]|select(.severity==$s)]|length' "$TMP_ALL"; }
+CRITICAL=$(count_sev Critical); HIGH=$(count_sev High)
+MEDIUM=$(count_sev Medium);    LOW=$(count_sev Low)
+TOTAL=$(jq -s 'length' "$TMP_ALL")
+
+# ---------------------------------------------------------------------------
+# Pass/fail decision.
+# ---------------------------------------------------------------------------
+case "$FAIL_ON" in
+  critical) BLOCKING=$((CRITICAL)) ;;
+  high)     BLOCKING=$((CRITICAL + HIGH)) ;;
+  medium)   BLOCKING=$((CRITICAL + HIGH + MEDIUM)) ;;
+  low)      BLOCKING=$((CRITICAL + HIGH + MEDIUM + LOW)) ;;
+  never)    BLOCKING=0 ;;
+  *)        BLOCKING=$((CRITICAL + HIGH)) ;;
+esac
+
+if [[ "$PARSED_SCANS" -eq 0 ]]; then
+  RESULT="PENDING"
+  DETAILS="Xray produced no parseable output — the scan did not complete. Check the pipeline log."
+elif [[ "$BLOCKING" -gt 0 ]]; then
+  RESULT="FAILED"
+  DETAILS="${BLOCKING} finding(s) at or above ${FAIL_ON} severity. ${TOTAL} total across ${PARSED_SCANS} scan(s)."
+else
+  RESULT="PASSED"
+  DETAILS="No findings at or above ${FAIL_ON} severity. ${TOTAL} total across ${PARSED_SCANS} scan(s)."
+fi
+if [[ -n "$SKIPPED_SCANS" ]]; then
+  DETAILS="${DETAILS} Incomplete: ${SKIPPED_SCANS}."
+fi
+
+# Log the tally before anything can bail out, so the numbers are in the build
+# log even when there's no way to publish them.
+echo "Xray findings: critical=${CRITICAL} high=${HIGH} medium=${MEDIUM} low=${LOW} total=${TOTAL} → ${RESULT}"
+
+LINK=""
+if [[ -n "${BITBUCKET_BUILD_NUMBER:-}" ]]; then
+  LINK="https://bitbucket.org/${WORKSPACE}/${REPO}/pipelines/results/${BITBUCKET_BUILD_NUMBER}"
+fi
+
+# data is capped at 10 elements by the API.
+jq -n \
+  --arg details "$DETAILS" --arg result "$RESULT" --arg link "$LINK" \
+  --argjson critical "$CRITICAL" --argjson high "$HIGH" \
+  --argjson medium "$MEDIUM" --argjson low "$LOW" --argjson total "$TOTAL" \
+  '{
+    title: "JFrog Xray Security Scan",
+    details: $details,
+    report_type: "SECURITY",
+    reporter: "JFrog Xray",
+    result: $result,
+    data: [
+      {title:"Critical", type:"NUMBER", value:$critical},
+      {title:"High",     type:"NUMBER", value:$high},
+      {title:"Medium",   type:"NUMBER", value:$medium},
+      {title:"Low",      type:"NUMBER", value:$low},
+      {title:"Total",    type:"NUMBER", value:$total}
+    ]
+  }
+  | if $link != "" then . + {link:$link} else . end' > "$TMP_BODY"
+
+# Pick an auth method. The proxy is probed rather than assumed: on a self-hosted
+# runner nothing listens on 29418 and every call fails with "connection refused".
+# Any HTTP response means the proxy is there; we only care about connectivity.
+CURL_AUTH=()
+if curl -s -o /dev/null --max-time 5 --proxy "$PROXY" \
+     "http://api.bitbucket.org/2.0/repositories/${WORKSPACE}/${REPO}" 2>/dev/null; then
+  BASE="http://api.bitbucket.org/${API_PATH}"
+  CURL_AUTH=(--proxy "$PROXY")
+  echo "Publishing via the Bitbucket Pipelines auth proxy."
+elif [[ -n "${BITBUCKET_ACCESS_TOKEN:-}" ]]; then
+  BASE="https://api.bitbucket.org/${API_PATH}"
+  CURL_AUTH=(-H "Authorization: Bearer ${BITBUCKET_ACCESS_TOKEN}")
+  echo "Publishing with BITBUCKET_ACCESS_TOKEN (no auth proxy on this runner)."
+elif [[ -n "${BITBUCKET_STEP_OAUTH_TOKEN:-}" ]]; then
+  BASE="https://api.bitbucket.org/${API_PATH}"
+  CURL_AUTH=(-H "Authorization: Bearer ${BITBUCKET_STEP_OAUTH_TOKEN}")
+  echo "Publishing with the step OAuth token (no auth proxy on this runner)."
+elif [[ -n "${BITBUCKET_USERNAME:-}" && -n "${BITBUCKET_APP_PASSWORD:-}" ]]; then
+  BASE="https://api.bitbucket.org/${API_PATH}"
+  # -u keeps the credential out of the URL, so it can't leak via -w or an error.
+  CURL_AUTH=(-u "${BITBUCKET_USERNAME}:${BITBUCKET_APP_PASSWORD}")
+  echo "Publishing with BITBUCKET_USERNAME/APP_PASSWORD (no auth proxy on this runner)."
+else
+  echo "No auth proxy on this runner and no BITBUCKET_ACCESS_TOKEN, step OAuth token,"
+  echo "or BITBUCKET_USERNAME+BITBUCKET_APP_PASSWORD set — skipping Code Insights."
+  exit 0
+fi
+
+echo "Publishing Code Insights report (${RESULT}: crit=${CRITICAL} high=${HIGH} med=${MEDIUM} low=${LOW})..."
+resp="$(api PUT "$BASE" "$TMP_BODY")"
+code="$(tail -n1 <<<"$resp")"
+if [[ "$code" != "200" && "$code" != "201" ]]; then
+  echo "Could not publish Code Insights report (HTTP ${code}):"
+  sed '$d' <<<"$resp" | head -5
+  exit 0
+fi
+echo "Report published: ${BASE}"
+
+# ---------------------------------------------------------------------------
+# Annotations. Only findings with a file path can be placed in the diff; the API
+# accepts at most 1000 per report and 100 per bulk POST.
+# ---------------------------------------------------------------------------
+ANN_TOTAL=$(jq -s '[.[]|select(.path != "")]|length' "$TMP_ALL")
+if [[ "$ANN_TOTAL" -eq 0 ]]; then
+  echo "No file-scoped findings to annotate (dependency findings are summarised in the report)."
+  exit 0
+fi
+
+jq -s -c '
+  # Chunk into batches of 100 (the bulk-POST limit). _nwise is jq-internal and
+  # absent in newer builds, so slice explicitly.
+  def chunks($n): . as $a
+    | [range(0; ($a|length); $n)] | map($a[. : . + $n]);
+  def sev_map: if . == "Critical" then "CRITICAL"
+               elif . == "High" then "HIGH"
+               elif . == "Medium" then "MEDIUM"
+               elif . == "Low" then "LOW"
+               else "LOW" end;
+  def ann_type: if . == "Secret" or . == "Secret violation" or . == "Malicious code"
+                then "VULNERABILITY"
+                elif . == "SAST" or . == "SAST violation" then "BUG"
+                else "VULNERABILITY" end;
+  [ .[] | select(.path != "") ]
+  | .[:1000]
+  | to_entries
+  | map(
+      # Derive the ID from the finding itself, not its position, so re-running a
+      # scan updates the same annotation instead of leaving orphans behind.
+      # The index is a tiebreaker for genuine duplicates.
+      ("xray-" + (.value.id + "-" + .value.path + "-" + (.value.line|tostring)
+                  | gsub("[^A-Za-z0-9._-]"; "-") | .[:230])
+             + "-" + (.key|tostring)) as $eid
+      | {
+      external_id: $eid,
+      annotation_type: (.value.kind | ann_type),
+      severity: (.value.severity | sev_map),
+      summary: ("[" + .value.severity + "] " + .value.id + " — " + .value.package),
+      details: (.value.summary | .[:2000]),
+      path: .value.path
+    }
+    + (if .value.line > 0 then {line: .value.line} else {} end))
+  | chunks(100)[]
+' "$TMP_ALL" > "$TMP_ANN"
+
+BATCH=0
+POSTED=0
+while IFS= read -r batch; do
+  [[ -z "$batch" ]] && continue
+  BATCH=$((BATCH + 1))
+  printf '%s' "$batch" > "${TMP_ANN}.batch"
+  resp="$(api POST "${BASE}/annotations" "${TMP_ANN}.batch")"
+  code="$(tail -n1 <<<"$resp")"
+  n="$(jq 'length' <<<"$batch")"
+  if [[ "$code" == "200" || "$code" == "201" ]]; then
+    POSTED=$((POSTED + n))
+  else
+    echo "Annotation batch ${BATCH} rejected (HTTP ${code}):"
+    sed '$d' <<<"$resp" | head -5
+  fi
+done < "$TMP_ANN"
+rm -f "${TMP_ANN}.batch"
+
+echo "Published ${POSTED}/${ANN_TOTAL} annotation(s) in ${BATCH} batch(es)."
+if [[ "$ANN_TOTAL" -gt 1000 ]]; then
+  echo "Note: capped at the API limit of 1000 annotations; $((ANN_TOTAL - 1000)) not shown in the diff."
+fi
+exit 0