@docupace/pipeline 1.0.122 → 1.0.123-xray.1

package/.gitignore

@@ -0,0 +1,103 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# IDE
+.idea
+*.iml
+# Dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# Testing
+/coverage
+
+# Next.js
+/.next/
+/out/
+
+# Production
+/build
+/dist
+
+# Misc
+.DS_Store
+*.pem
+cypress/screenshots/
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env*.local
+
+# Vercel
+.vercel
+
+# Typescript
+*.tsbuildinfo
+next-env.d.ts
+
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+.next
+
+scratch
+
+# visual studio code
+.vscode/
+
+src/gql/graphql.js
+.yalc/
+yalc.lock
+
+.last-run.json
+
+test-results
+coverage-reports
+.sonar
+.v8-coverage
+/assets
+tests/lib/data/auth.json
+
+failed-tests.json
+
+/tmp
+
+.claude

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @docupace/pipeline
 
+## 1.0.123
+
+### Patch Changes
+
+- 49984e2: Add Veracode upload-and-scan and SonarQube scan/PR-quality-gate shared pipelines (veracode-scan, sonar-scan, sonar-pr-gate)
+
 ## 1.0.121
 
 ### Patch Changes

package/bitbucket-pipelines.yml

@@ -292,6 +292,273 @@ definitions:
     tenable-scan:
       - step: *tenable-scan-step
 
+    # Uploads and scans one or more app targets with Veracode:
+    # import: pipeline-shared-scripts:master:veracode-scan
+    #
+    # Required: VERACODE_API_ID, VERACODE_API_KEY, VERACODE_TARGETS
+    #   VERACODE_TARGETS="label:appname:path1,path2,...[;label2:appname2:...]"
+    #   (an app profile named <appname> must already exist in the Veracode portal)
+    # Optional: VERACODE_BUILD_CMD — eval'd before packaging, so this step is
+    #   self-contained and needs no separate build step in the consumer pipeline.
+    veracode-scan:
+      - step:
+          name: Veracode Upload and Scan
+          runs-on:
+            - self.hosted
+            - linux.shell
+            - onprem
+          script:
+            - |
+              if [ -z "${VERACODE_API_ID:-}" ] || [ -z "${VERACODE_API_KEY:-}" ]; then
+                echo "ERROR: VERACODE_API_ID / VERACODE_API_KEY not set — cannot run Veracode scan." >&2
+                exit 1
+              fi
+              if [ -z "${VERACODE_TARGETS:-}" ]; then
+                echo "ERROR: VERACODE_TARGETS not set — cannot run Veracode scan." >&2
+                echo "       Expected: label:appname:path1,path2,...[;label2:appname2:path1,...]" >&2
+                exit 1
+              fi
+            - |
+              # VERACODE_BUILD_CMD lets a consumer produce whatever build artifacts
+              # Veracode's SAST needs (compiled bundles, etc.) without a separate
+              # pre-build step in the consumer's own pipeline — the same
+              # self-contained approach the Xray step above uses for its Docker build.
+              if [ -n "${VERACODE_BUILD_CMD:-}" ]; then
+                echo "Running VERACODE_BUILD_CMD..."
+                eval "${VERACODE_BUILD_CMD}"
+              fi
+            - |
+              # Cached across builds on self-hosted runners; downloaded once.
+              if [ ! -f veracode-wrapper/VeracodeJavaAPI.jar ]; then
+                mkdir -p veracode-wrapper
+                curl -sSL "https://repo1.maven.org/maven2/com/veracode/vosp/api/wrappers/vosp-api-wrappers-java/26.3.19.0/vosp-api-wrappers-java-26.3.19.0.jar" \
+                  -o veracode-wrapper/VeracodeJavaAPI.jar
+              fi
+            - |
+              # Each target is zipped and submitted as its own uploadandscan call,
+              # so one repo with several apps (e.g. a frontend and a backend) gets
+              # separate Veracode profiles instead of one scan covering everything.
+              SHORT_SHA="$(printf '%s' "${BITBUCKET_COMMIT:-local}" | cut -c1-7)"
+              failed=0
+              OLD_IFS="${IFS}"
+              IFS=';'
+              set -- ${VERACODE_TARGETS}
+              IFS="${OLD_IFS}"
+              for target in "$@"; do
+                [ -z "${target}" ] && continue
+                label="$(printf '%s' "${target}" | cut -d: -f1)"
+                appname="$(printf '%s' "${target}" | cut -d: -f2)"
+                paths="$(printf '%s' "${target}" | cut -d: -f3)"
+                [ -z "${label}" ] && label="app"
+                slug="$(printf '%s' "${label}" | tr -c 'A-Za-z0-9._-' '-')"
+
+                if [ -z "${appname}" ] || [ -z "${paths}" ]; then
+                  echo "Target '${label}' is missing an appname or paths in VERACODE_TARGETS — skipping." >&2
+                  failed=1
+                  continue
+                fi
+
+                zip_file="veracode-${slug}.zip"
+                rm -f "${zip_file}"
+                OLD_IFS2="${IFS}"
+                IFS=','
+                set -- ${paths}
+                IFS="${OLD_IFS2}"
+                zip -r "${zip_file}" "$@"
+
+                # -createprofile false — the app profile must already exist in the
+                # Veracode portal. -autoscan true starts the scan once prescan passes.
+                java -jar veracode-wrapper/VeracodeJavaAPI.jar \
+                  -vid "${VERACODE_API_ID}" \
+                  -vkey "${VERACODE_API_KEY}" \
+                  -action uploadandscan \
+                  -appname "${appname}" \
+                  -createprofile false \
+                  -autoscan true \
+                  -filepath "${zip_file}" \
+                  -version "sha-${SHORT_SHA}-${label}" || { failed=1; echo "ERROR: Veracode scan submission failed for '${label}'." >&2; }
+
+                rm -f "${zip_file}"
+              done
+              [ "${failed}" -ne 0 ] && exit 1
+              exit 0
+
+    # Runs a SonarQube analysis against the current branch, fire-and-forget
+    # (no quality-gate enforcement): import: pipeline-shared-scripts:master:sonar-scan
+    #
+    # Required: SONAR_TOKEN (soft-skips the whole step if unset)
+    # Optional: SONAR_HOST_URL (default https://sonarcloud.io), SONAR_DEFAULT_BRANCH
+    #   (default "main").
+    #
+    # Single project (default): SONAR_PROJECT_DIR (default ".", the dir holding
+    #   sonar-project.properties), SONAR_COVERAGE_CMD (eval'd before scanning),
+    #   SONAR_COVERAGE_REPORT_PATH (if set, required to exist and be non-empty
+    #   afterward).
+    #
+    # Multiple projects in one repo (e.g. a frontend and a backend, each its own
+    # sonar.projectKey): set SONAR_TARGETS instead of SONAR_PROJECT_DIR —
+    # "label:projectDir;label2:projectDir2" (semicolon between targets, mirrors
+    # VERACODE_TARGETS' delimiter convention). Each label's own coverage
+    # command/report path can be set via SONAR_COVERAGE_CMD_<LABEL> /
+    # SONAR_COVERAGE_REPORT_PATH_<LABEL> (label upper-cased, non-alphanumerics
+    # replaced with "_" — label "frontend" reads SONAR_COVERAGE_CMD_FRONTEND),
+    # falling back to the global SONAR_COVERAGE_CMD/SONAR_COVERAGE_REPORT_PATH
+    # when no per-target one is set. A failed target is reported and scanning
+    # continues on to the rest; the step fails afterward if any target failed —
+    # same pattern as VERACODE_TARGETS.
+    #
+    # depth: full — Sonar reads git blame to attribute New Code; a shallow clone
+    # only sees the tip commit and silently treats everything as new.
+    sonar-scan: &sonar-scan-pipeline
+      - step: &sonar-scan-step
+          name: SonarQube Scan
+          runs-on:
+            - self.hosted
+            - linux.shell
+            - onprem
+          clone:
+            depth: full
+          script:
+            - |
+              if [ -z "${SONAR_TOKEN:-}" ]; then
+                echo "Skipping SonarQube scan: SONAR_TOKEN not set"
+                exit 0
+              fi
+            - &sonar-scan-script |
+              export DOCKER_HOST=""
+              unset DOCKER_CONTEXT
+              SONAR_HOST="${SONAR_HOST_URL:-https://sonarcloud.io}"
+              DEFAULT_BRANCH="${SONAR_DEFAULT_BRANCH:-main}"
+              WORKDIR="$(pwd)"
+
+              # Bitbucket's built-ins: BITBUCKET_BRANCH / BITBUCKET_PR_ID /
+              # BITBUCKET_PR_DESTINATION_BRANCH. An upload with no branch parameter
+              # is filed against the project's default branch, so scanning a
+              # feature branch without one would silently overwrite that branch's
+              # analysis and quality-gate status. Resolved once — every target in
+              # this run shares the same branch/PR context.
+              BRANCH="${BITBUCKET_BRANCH:-}"
+              PR_ID="${BITBUCKET_PR_ID:-}"
+              PR_BASE="${BITBUCKET_PR_DESTINATION_BRANCH:-}"
+              BRANCH_DOCKER_ARGS=""
+              BRANCH_SONAR_ARGS=""
+
+              if [ -n "${PR_ID}" ]; then
+                BRANCH_DOCKER_ARGS="-e PR_ID=${PR_ID}"
+                BRANCH_SONAR_ARGS="-Dsonar.pullrequest.key=${PR_ID}"
+                [ -n "${BRANCH}" ] && BRANCH_SONAR_ARGS="${BRANCH_SONAR_ARGS} -Dsonar.pullrequest.branch=${BRANCH}"
+                [ -n "${PR_BASE}" ] && BRANCH_SONAR_ARGS="${BRANCH_SONAR_ARGS} -Dsonar.pullrequest.base=${PR_BASE}"
+              elif [ -n "${BRANCH}" ] && [ "${BRANCH}" != "${DEFAULT_BRANCH}" ]; then
+                BRANCH_DOCKER_ARGS="-e BRANCH=${BRANCH}"
+                BRANCH_SONAR_ARGS="-Dsonar.branch.name=${BRANCH}"
+              elif [ -n "${BITBUCKET_TAG:-}" ] || [ "${BRANCH}" = "${DEFAULT_BRANCH}" ]; then
+                echo "Sonar: analysing as the default branch (${DEFAULT_BRANCH})"
+              else
+                echo "ERROR: cannot tell which branch this analysis belongs to — none of BITBUCKET_PR_ID, BITBUCKET_BRANCH or BITBUCKET_TAG is set." >&2
+                echo "       Refusing to upload: SonarCloud would file it against '${DEFAULT_BRANCH}' and overwrite that branch's analysis." >&2
+                exit 1
+              fi
+
+              if [ "${SONAR_WAIT_FOR_GATE:-false}" = "true" ]; then
+                BRANCH_SONAR_ARGS="${BRANCH_SONAR_ARGS} -Dsonar.qualitygate.wait=true -Dsonar.qualitygate.timeout=${SONAR_QUALITYGATE_TIMEOUT:-300}"
+              fi
+
+              # Looks up "${1}_<SLUG>" if set, else prints nothing — POSIX sh has no
+              # ${!indirect} expansion, so this shells out through eval instead.
+              target_var() {
+                eval "printf '%s' \"\${$1_${2}:-}\""
+              }
+
+              # Each target is its own SonarCloud project — like Veracode's per-app
+              # profiles, a repo with several components (frontend/backend) needs
+              # its own sonar.projectKey per component, not one shared analysis.
+              failed=0
+              OLD_IFS="${IFS}"
+              IFS=';'
+              set -- ${SONAR_TARGETS:-default:${SONAR_PROJECT_DIR:-.}}
+              IFS="${OLD_IFS}"
+
+              for target in "$@"; do
+                [ -z "${target}" ] && continue
+                label="$(printf '%s' "${target}" | cut -d: -f1)"
+                project_dir="$(printf '%s' "${target}" | cut -d: -f2)"
+                [ -z "${label}" ] && label="default"
+                [ -z "${project_dir}" ] && project_dir="."
+                slug="$(printf '%s' "${label}" | tr -c 'A-Za-z0-9' '_' | tr 'a-z' 'A-Z')"
+
+                coverage_cmd="$(target_var SONAR_COVERAGE_CMD "${slug}")"
+                [ -z "${coverage_cmd}" ] && coverage_cmd="${SONAR_COVERAGE_CMD:-}"
+                coverage_path="$(target_var SONAR_COVERAGE_REPORT_PATH "${slug}")"
+                [ -z "${coverage_path}" ] && coverage_path="${SONAR_COVERAGE_REPORT_PATH:-}"
+
+                # SONAR_COVERAGE_CMD(_<LABEL>) lets a consumer produce a coverage
+                # report before the scan runs, without a separate pre-scan step —
+                # the same self-contained approach as VERACODE_BUILD_CMD above.
+                # SONAR_COVERAGE_REPORT_PATH(_<LABEL>), if set, is required to exist
+                # afterward: a run with no coverage report still "succeeds" but
+                # silently reports 0% coverage.
+                if [ -n "${coverage_cmd}" ]; then
+                  echo "[${label}] Running coverage command..."
+                  eval "${coverage_cmd}" || echo "WARN: coverage command exited non-zero for '${label}'; checking for the report anyway."
+                fi
+                if [ -n "${coverage_path}" ] && [ ! -s "${coverage_path}" ]; then
+                  echo "ERROR: ${coverage_path} missing or empty for target '${label}' — Sonar would report 0% coverage." >&2
+                  failed=1
+                  continue
+                fi
+
+                DOCKER_ARGS="run --rm --platform linux/amd64 -e SONAR_HOST_URL=${SONAR_HOST} -e SONAR_TOKEN ${BRANCH_DOCKER_ARGS} -v ${WORKDIR}:/workspace -w /workspace/${project_dir}"
+                SONAR_ARGS="sonar-scanner -Dsonar.host.url=${SONAR_HOST} -Dproject.settings=/workspace/${project_dir}/sonar-project.properties ${BRANCH_SONAR_ARGS}"
+
+                echo "[${label}] Running: docker ${DOCKER_ARGS} sonarsource/sonar-scanner-cli:latest ${SONAR_ARGS}"
+                docker ${DOCKER_ARGS} sonarsource/sonar-scanner-cli:latest ${SONAR_ARGS} || {
+                  failed=1
+                  echo "ERROR: Sonar scan failed for target '${label}'." >&2
+                }
+              done
+
+              [ "${failed}" -ne 0 ] && exit 1
+              exit 0
+
+    # Enforces the SonarQube quality gate on a PR into SONAR_GATE_BRANCH (default
+    # "main"); skips for PRs into any other branch:
+    # import: pipeline-shared-scripts:master:sonar-pr-gate
+    #
+    # Required: SONAR_TOKEN (hard-fails if unset and the gate applies to this PR)
+    # Optional: same as sonar-scan, plus SONAR_GATE_BRANCH (default "main") and
+    #   SONAR_QUALITYGATE_TIMEOUT (default 300 seconds).
+    sonar-pr-gate:
+      - step:
+          name: SonarQube Quality Gate
+          runs-on:
+            - self.hosted
+            - linux.shell
+            - onprem
+          clone:
+            depth: full
+          script:
+            - |
+              DEST="${BITBUCKET_PR_DESTINATION_BRANCH:-}"
+              GATE_BRANCH="${SONAR_GATE_BRANCH:-main}"
+
+              if [ -z "${DEST}" ]; then
+                echo "ERROR: BITBUCKET_PR_DESTINATION_BRANCH not set — refusing to run the PR quality gate blind." >&2
+                exit 1
+              fi
+
+              if [ "${DEST}" != "${GATE_BRANCH}" ]; then
+                echo "Skipping Sonar quality gate: PR targets '${DEST}', not '${GATE_BRANCH}'"
+                exit 0
+              fi
+
+              if [ -z "${SONAR_TOKEN:-}" ]; then
+                echo "ERROR: SONAR_TOKEN not set — cannot enforce the Sonar quality gate for a PR into ${GATE_BRANCH}." >&2
+                exit 1
+              fi
+
+              export SONAR_WAIT_FOR_GATE=true
+            - *sonar-scan-script
+
   steps:
     - step: &version-step
         runs-on:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docupace/pipeline",
-  "version": "1.0.122",
+  "version": "1.0.123-xray.1",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -12,7 +12,10 @@
     "dp-next-cli": "src/next/cli.js",
     "dp-auth0-cli": "src/auth0/cli.js",
     "dp-merge-cli": "src/merge/cli.js",
-    "dp-micro-cli": "src/micro/cli.js"
+    "dp-micro-cli": "src/micro/cli.js",
+    "dp-xray-cli": "src/xray/cli.js",
+    "dp-tenable-cli": "src/tenable/cli.js",
+    "dp-veracode-cli": "src/veracode/cli.js"
   },
   "keywords": [
     "bash"

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  unrs-resolver: true

package/src/changeset/validate.js

@@ -1,14 +1,24 @@
 import fs from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { $ } from 'zx';
 
 import { setGitInfo } from '../next/util.js';
 import { versionStatus } from './version.js';
 
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'),
+).version;
+
 export async function validateChangesets() {
+  console.log(`validateChangesets: @docupace/pipeline version = ${PACKAGE_VERSION}`);
   await setGitInfo();
   const destBranch = process.env.BITBUCKET_PR_DESTINATION_BRANCH;
+  console.log(`validateChangesets: destBranch = ${destBranch}`);
+  console.log(`validateChangesets: fetching origin ${destBranch}:${destBranch}`);
   await $`git fetch origin ${destBranch}:${destBranch}`;
+  console.log('validateChangesets: fetch succeeded');
   let releases;
 
   try {

package/src/next/util.js

@@ -84,12 +84,41 @@ export async function getChangedAppPackages() {
   return appPackages;
 }
 
+function maskCreds(url) {
+  return url.replace(/:[^:@/]+@/, ':***@');
+}
+
 export async function setGitInfo() {
+  console.log(`setGitInfo: SET_GITOPS_USER=${process.env.SET_GITOPS_USER || '(unset)'}`);
   if (process.env.SET_GITOPS_USER) {
+    const before = (await $`git remote get-url origin`).stdout.trim();
+    console.log(`setGitInfo: origin before = ${maskCreds(before)}`);
+
     await $`git config --global user.email "gitops@docupace.com"`;
     await $`git config --global user.name "Gitops"`;
-    const repoUrl = `git@bitbucket.org:dp-cloud/${process.env.BITBUCKET_REPO_SLUG}.git`;
-    console.log(`Setting new origin: ${repoUrl}`);
-    await $`git remote set-url origin ${repoUrl}`;
+
+    // Some self-hosted runners rewrite `git@bitbucket.org:` (SSH) to a bare,
+    // credential-less `https://bitbucket.org/` via a git `insteadOf` rule, so an
+    // SSH-form origin silently loses its identity at fetch/push time. Use an
+    // HTTPS URL with the token embedded instead — insteadOf doesn't touch it.
+    const token =
+      process.env.BITBUCKET_STEP_OAUTH_TOKEN || process.env.BITBUCKET_TOKEN;
+    if (!token) {
+      console.log(
+        'setGitInfo: no BITBUCKET_STEP_OAUTH_TOKEN/BITBUCKET_TOKEN available, leaving origin as-is',
+      );
+    } else {
+      const repoUrl = `https://x-token-auth:${token}@bitbucket.org/dp-cloud/${process.env.BITBUCKET_REPO_SLUG}.git`;
+      console.log(`Setting new origin: ${maskCreds(repoUrl)}`);
+      await $`git remote set-url origin ${repoUrl}`;
+    }
+
+    const after = (await $`git remote get-url origin`).stdout.trim();
+    console.log(`setGitInfo: origin after = ${maskCreds(after)}`);
+  } else {
+    const current = (await $`git remote get-url origin`).stdout.trim();
+    console.log(
+      `setGitInfo: SET_GITOPS_USER not set, leaving origin as-is = ${maskCreds(current)}`,
+    );
   }
 }

package/src/tenable/args.js

@@ -0,0 +1,157 @@
+// Pure parsing/formatting logic for the Tenable scan step, ported from
+// bin/tenable-scan.sh. No fs/docker calls here so it's unit-testable.
+
+// Mirrors `tr -c 'A-Za-z0-9._-' '-'`: every character outside that set is
+// replaced with '-' (no squeezing of consecutive replacements).
+export function slugify(label) {
+  return label.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+// Splits `str` on `sep` into exactly `n` fields, folding any extra fields
+// into the last one — matching `read a b c d <<< "$str"` semantics, where a
+// trailing variable absorbs everything left over.
+function splitFixed(str, sep, n) {
+  const parts = str.split(sep);
+  if (parts.length <= n) {
+    return [...parts, ...Array(n - parts.length).fill('')];
+  }
+  return [...parts.slice(0, n - 1), parts.slice(n - 1).join(sep)];
+}
+
+// One "label:auditDir:buildContext:dockerfile" entry from SCAN_TARGETS.
+// auditDir belongs to the Xray step and is ignored here. A target with no
+// build context is returned with skipped: true rather than dropped, so the
+// caller can log why it was skipped (matching the bash script's behavior).
+export function parseScanTargets(scanTargetsStr) {
+  return (scanTargetsStr || '')
+    .split(';')
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .map((raw) => {
+      const [rawLabel, , rawContext, rawDockerfile] = splitFixed(raw, ':', 4);
+      const label = rawLabel || 'app';
+      const slug = slugify(label);
+      if (!rawContext) {
+        return { label, slug, buildContext: '', dockerfile: '', skipped: true };
+      }
+      return {
+        label,
+        slug,
+        buildContext: rawContext,
+        dockerfile: rawDockerfile || `${rawContext}/Dockerfile`,
+        skipped: false,
+      };
+    });
+}
+
+export function defaultScanTargets(buildContext, dockerfilePath) {
+  const ctx = buildContext || '.';
+  return `app::${ctx}:${dockerfilePath || `${ctx}/Dockerfile`}`;
+}
+
+export function buildCodeMetadata({
+  commit = 'local',
+  branch = '',
+  prDestinationBranch = '',
+  workspace = 'unknown',
+  repoSlug = 'unknown',
+  gitAuthorName = '',
+} = {}) {
+  return {
+    shortSha: commit.slice(0, 7),
+    codeBranch: branch || prDestinationBranch || 'unknown',
+    codeRepoUrl: `https://bitbucket.org/${workspace}/${repoSlug}`,
+    codeUser: gitAuthorName || 'bitbucket-pipelines',
+  };
+}
+
+// The scanner requires --pipeline-run-url as soon as any pipeline flag is
+// supplied, so the trio (id/trigger/url) travels together or not at all —
+// includeInScanArgs tells the caller which case applies.
+export function buildPipelineRunInfo({
+  runId = '',
+  runTrigger = '',
+  runUrl = '',
+  prId = '',
+  buildNumber = '',
+  workspace = 'unknown',
+  repoSlug = 'unknown',
+} = {}) {
+  const resolvedRunId = runId || buildNumber || '';
+  const resolvedTrigger = runTrigger || (prId ? 'pull_request' : '') || 'push';
+  const resolvedUrl =
+    runUrl ||
+    (buildNumber
+      ? `https://bitbucket.org/${workspace}/${repoSlug}/pipelines/results/${buildNumber}`
+      : '');
+
+  return {
+    runId: resolvedRunId,
+    runTrigger: resolvedTrigger,
+    runUrl: resolvedUrl,
+    includeInScanArgs: Boolean(resolvedRunId) && Boolean(resolvedUrl),
+  };
+}
+
+// The scanner's documented vocabularies are lowercase — severities
+// information|low|medium|high|critical, formats cyclonedx|json|junit|md — and it
+// does not correct a case mismatch or complain about one: it just exports nothing.
+// Callers set these from env vars that read naturally capitalised ("Medium"), so
+// normalise here rather than making every caller remember.
+export function buildScanArgs({
+  slug,
+  scanTarget,
+  codeBranch,
+  commit,
+  codeUser,
+  codeRepoUrl,
+  minSeverity,
+  runInfo,
+  failOnMinSeverity = '',
+}) {
+  const args = [
+    'container-image',
+    'scan',
+    '--archive-path',
+    '/tmp/tenable/image.tar',
+    '--name',
+    scanTarget,
+    '--code-branch',
+    codeBranch,
+    '--code-commit-hash',
+    commit,
+    '--code-commit-user',
+    codeUser,
+    '--code-repository-url',
+    codeRepoUrl,
+    '--min-severity',
+    String(minSeverity).toLowerCase(),
+    '--output-file-formats',
+    'json,md,junit',
+    '--output-path',
+    '/tmp/tenable/out',
+    '--output-file-name',
+    `${slug}-tenable`,
+    '--no-color',
+  ];
+
+  if (runInfo?.includeInScanArgs) {
+    args.push(
+      '--pipeline-run-id',
+      runInfo.runId,
+      '--pipeline-run-trigger',
+      runInfo.runTrigger,
+      '--pipeline-run-url',
+      runInfo.runUrl,
+    );
+  }
+
+  if (failOnMinSeverity) {
+    args.push('--fail-on-min-severity', failOnMinSeverity.toLowerCase());
+  }
+
+  return args;
+}
+
+export const SEPARATOR =
+  '==============================================================';