@docupace/pipeline 1.0.128 → 1.0.131

package/.gitleaksignore

@@ -0,0 +1,9 @@
+# Historical audit trail only. Because the Secrets Scan step clones at
+# depth: 1, gitleaks only ever sees the latest commit — these fingerprints
+# (tied to specific historical commit SHAs) will never actually be re-scanned
+# and do not suppress future findings. The real fix for these two was
+# removing the credential from testCanny.sh; see that commit for details.
+#
+# Canny API key in testCanny.sh, revoked (curl confirmed: "invalid api key").
+2337b1f58f2e5fec0d71ca22305573505c84daee:testCanny.sh:generic-api-key:4
+dfa078fd93eeb339d32ec4067a247195caef24cd:testCanny.sh:generic-api-key:4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @docupace/pipeline
 
+## 1.0.130
+
+### Patch Changes
+
+- cfa3fe9: Add a shared secrets-scan pipeline definition (importable as pipeline-shared-scripts:master:secrets-scan, also runnable manually via custom.secrets-scan in this repo) that runs Atlassian's git-secrets-scan pipe (gitleaks) with clone depth 1, so only the latest commit is scanned rather than full history
+- cfa3fe9: Add dp-tenable-cli, dp-veracode-cli, and dp-xray-cli Node CLIs porting the Tenable scan, Veracode upload-and-scan, and JFrog Xray Slack-notify bash logic
+- cfa3fe9: Fix setGitInfo to fall back to BITBUCKET_APP_PASSWORD (an API token, paired with the static x-bitbucket-api-token-auth username, matching getRepUrl in next/config.js) when BITBUCKET_STEP_OAUTH_TOKEN/BITBUCKET_TOKEN isn't set, fixing changeset validation failing to authenticate against Bitbucket on runners that rewrite the SSH origin to a credential-less HTTPS URL
+
 ## 1.0.123
 
 ### Patch Changes

package/bin/tenable-scan.sh

@@ -119,8 +119,8 @@ scan_one() {
     "--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"
+    "--min-severity" "$(printf '%s' "${MIN_SEVERITY}" | tr 'A-Z' 'a-z')"
+    "--output-file-formats" "json,md,junit"
     "--output-path" "/tmp/tenable/out"
     "--output-file-name" "${slug}-tenable"
     "--no-color"
@@ -134,15 +134,24 @@ scan_one() {
     )
   fi
   if [[ -n "${TENABLE_FAIL_ON_MIN_SEVERITY:-}" ]]; then
-    scan_args+=("--fail-on-min-severity" "${TENABLE_FAIL_ON_MIN_SEVERITY}")
+    scan_args+=("--fail-on-min-severity" "$(printf '%s' "${TENABLE_FAIL_ON_MIN_SEVERITY}" | tr 'A-Z' 'a-z')")
   fi
 
   echo "Running Tenable scan for '${slug}' (min-severity=${MIN_SEVERITY}${TENABLE_FAIL_ON_MIN_SEVERITY:+, fail-on=${TENABLE_FAIL_ON_MIN_SEVERITY}})..."
+  # --entrypoint is not optional: Tenable's own GitHub action builds FROM this image
+  # solely to replace the entrypoint with a script that runs `tenable container-image
+  # scan "$@"`, so the image's own entrypoint is not that binary. Handing the
+  # subcommand to whatever it does start fails silently — exit 0, no output, no
+  # reports. The binary also takes its output destination from the environment (the
+  # action passes no --output-path flag at all), so it is set both ways.
   docker run --rm \
     --workdir /tmp/tenable \
     --volume "${work}:/tmp/tenable" \
     --env TENABLE_API_TOKEN \
     --env TENABLE_API_URL \
+    --env "TENABLE_OUTPUT_PATH=/tmp/tenable/out" \
+    --env "TENABLE_OUTPUT_FILE_NAME=${slug}-tenable" \
+    --entrypoint "${TENABLE_SCANNER_ENTRYPOINT:-tenable}" \
     --pull=always \
     "${SCANNER_IMAGE}" "${scan_args[@]}"
   local scan_exit=$?

package/bitbucket-pipelines.yml

@@ -453,6 +453,69 @@ definitions:
               [ "${failed}" -ne 0 ] && exit 1
               exit 0
 
+    # Scans only the latest commit(s) for hardcoded secrets using Atlassian's
+    # git-secrets-scan pipe (gitleaks under the hood):
+    # import: pipeline-shared-scripts:master:secrets-scan
+    #
+    # No `runs-on` here deliberately: Bitbucket's Pipes launcher requires a
+    # runner in Docker execution mode, which this workspace's on-prem
+    # self-hosted runners don't provide (they're shell-mode only) — omitting
+    # `runs-on` falls back to Bitbucket's own cloud runners, which do support
+    # Pipes.
+    #
+    # Per https://support.atlassian.com/bitbucket-cloud/kb/how-to-scan-only-the-latest-commits-for-secrets-using-the-git-secrets-scan-pipe/
+    # the pipe itself has no "latest commit only" flag — gitleaks' default `git`
+    # mode scans the whole history it can see. The scope is controlled entirely
+    # by the step's own `clone: depth`, which is why this step overrides the
+    # repo-wide default (depth: 2) down to depth: 1: with a depth-1 clone there
+    # is only one commit for gitleaks to see, so it scans just that one. This
+    # also means the step never manages BITBUCKET_PREVIOUS_COMMIT/HEAD^ ranges
+    # itself — a deeper clone here would silently widen the scan.
+    #
+    # Optional: SECRETS_SCAN_EXTRA_ARGS (extra gitleaks flags, e.g. a custom
+    #   --gitleaks-ignore-path or --config — appended after the default
+    #   --redact below, so a repo can add flags without losing redaction; do
+    #   NOT pass --exit-code 0, that would make the pipe always exit 0 and
+    #   silently defeat the registry-push gate that depends on this step
+    #   failing on a real find), SECRETS_SCAN_CREATE_REPORT (default "true" —
+    #   set "false" to skip the Code Insights report), SECRETS_SCAN_DEBUG
+    #   (default "false").
+    secrets-scan: &def-secrets-scan
+      - step:
+          name: Secrets Scan (latest commit)
+          clone:
+            depth: 1
+          script:
+            # bitbucket-pipelines.yml variable substitution only does a plain
+            # ${VAR} lookup (empty string if unset) — it doesn't support shell
+            # ${VAR:-default} fallback syntax, so defaults are applied here
+            # instead, before the pipe reads them.
+            #
+            # --redact is on by default: gitleaks-report.json below is kept
+            # as a build artifact for triage, and without --redact its
+            # `Secret` field would hold the actual matched credential in
+            # plain text — turning a transient leak into a persistent,
+            # downloadable copy of it for anyone with repo read access.
+            - |
+              export SECRETS_SCAN_CREATE_REPORT="${SECRETS_SCAN_CREATE_REPORT:-true}"
+              export SECRETS_SCAN_DEBUG="${SECRETS_SCAN_DEBUG:-false}"
+              export SECRETS_SCAN_EXTRA_ARGS="--redact ${SECRETS_SCAN_EXTRA_ARGS}"
+            - pipe: atlassian/git-secrets-scan:3.2.0
+              variables:
+                GITLEAKS_EXTRA_ARGS: ${SECRETS_SCAN_EXTRA_ARGS}
+                CREATE_REPORT: ${SECRETS_SCAN_CREATE_REPORT}
+                DEBUG: ${SECRETS_SCAN_DEBUG}
+          # Gitleaks writes this report before the pipe attempts its Bitbucket
+          # Code Insights upload, so it's captured here even if that upload
+          # fails (a known bug in the pipe: it can crash on a 400 from
+          # Bitbucket's annotations API for certain file paths) or the step
+          # otherwise fails on a real finding. `artifacts:` is collected
+          # regardless of step exit code — this is how to see which secrets
+          # were found (file, line, rule, fingerprint) with the matched
+          # secret value itself redacted by --redact above.
+          artifacts:
+            - gitleaks-report.json
+
     # Runs a SonarQube analysis against the current branch, fire-and-forget
     # (no quality-gate enforcement): import: pipeline-shared-scripts:master:sonar-scan
     #
@@ -725,11 +788,39 @@ pipelines:
     xray-scan: *def-xray-scan
     tenable-scan: *def-tenable-scan
     veracode-scan: *def-veracode-scan
+    secrets-scan: *def-secrets-scan
     sonar-scan: *def-sonar-scan
     sonar-pr-gate: *def-sonar-pr-gate
 
   pull-requests:
     '**':
+      # Inlined rather than aliased to *def-secrets-scan: that anchor is bound
+      # to a whole pipeline (a list with one step), and YAML's merge key only
+      # splices mappings, not list items, so it can't be spliced into this
+      # list. Keep this step's content in sync with the secrets-scan
+      # definition above if it changes.
+      - step:
+          name: Secrets Scan (latest commit)
+          # No `runs-on` deliberately — see the secrets-scan definition above
+          # for why (Pipes need a Docker-mode runner, which the on-prem
+          # runners here don't provide; omitting runs-on falls back to
+          # Bitbucket's cloud runners).
+          clone:
+            depth: 1
+          script:
+            - |
+              export SECRETS_SCAN_CREATE_REPORT="${SECRETS_SCAN_CREATE_REPORT:-true}"
+              export SECRETS_SCAN_DEBUG="${SECRETS_SCAN_DEBUG:-false}"
+              export SECRETS_SCAN_EXTRA_ARGS="--redact ${SECRETS_SCAN_EXTRA_ARGS}"
+            - pipe: atlassian/git-secrets-scan:3.2.0
+              variables:
+                GITLEAKS_EXTRA_ARGS: ${SECRETS_SCAN_EXTRA_ARGS}
+                CREATE_REPORT: ${SECRETS_SCAN_CREATE_REPORT}
+                DEBUG: ${SECRETS_SCAN_DEBUG}
+          # See the secrets-scan definition above for why this is captured
+          # as an artifact regardless of the step's exit code.
+          artifacts:
+            - gitleaks-report.json
       - step:
           runs-on:
             - self.hosted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docupace/pipeline",
-  "version": "1.0.128",
+  "version": "1.0.131",
   "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/src/auth0/metadata.js

@@ -4,11 +4,14 @@ import * as path from 'node:path'; // ESM-compatible import
 import { cloneRepository, pushDeployConfig } from '../next/deploy.js';
 import { getAuth0AuthToken } from './configure.js';
 import { getVaultSecrets } from './vault.js';
-import { getVaultSecretsConfigs } from '../next/config.js';
+import {
+  connectDeployRepoName,
+  getVaultSecretsConfigs,
+} from '../next/config.js';
 
 export async function getAuth0Metadata(site, env, auth0Tenant, jiraTicket) {
   try {
-    const connectDeployRepoPath = await cloneRepository('connect-deploy');
+    const connectDeployRepoPath = await cloneRepository(connectDeployRepoName);
 
     const envMap = {
       dev: 'dev',

package/src/auth0/metadata.test.js

@@ -34,6 +34,7 @@ jest.unstable_mockModule('./vault.js', () => ({
 
 jest.unstable_mockModule('../next/config.js', () => ({
   getVaultSecretsConfigs: jest.fn(),
+  connectDeployRepoName: 'dp-eks-connect-ui-gitops',
 }));
 
 // ----- Imports AFTER mocks -----
@@ -43,7 +44,9 @@ const axios = (await import('axios')).default;
 const { cloneRepository, pushDeployConfig } = await import('../next/deploy.js');
 const { getAuth0AuthToken } = await import('./configure.js');
 const { getVaultSecrets } = await import('./vault.js');
-const { getVaultSecretsConfigs } = await import('../next/config.js');
+const { getVaultSecretsConfigs, connectDeployRepoName } = await import(
+  '../next/config.js'
+);
 
 // ----- Shared Setup -----
 beforeAll(() => {
@@ -113,7 +116,7 @@ describe('getAuth0Metadata', () => {
 
     await getAuth0Metadata(site, env, auth0Tenant);
 
-    expect(cloneRepository).toHaveBeenCalledWith('connect-deploy');
+    expect(cloneRepository).toHaveBeenCalledWith(connectDeployRepoName);
     expect(fs.readFile).toHaveBeenCalledWith('conf/application.conf', 'utf-8');
     expect(fs.ensureDir).toHaveBeenCalledWith('conf/saml');
     expect(fs.writeFile).toHaveBeenCalledWith(

package/src/changeset/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { $ } from 'zx';
+import path from 'path';
 import { validateChangesets } from './validate.js';
 import dotenv from 'dotenv';
 import { isMonoRepo, setGitInfo } from '../next/util.js';
@@ -19,6 +20,26 @@ const program = new Command();
 
 const args = process.argv;
 
+async function runPostVersionScript(scriptPath, releases) {
+  if (!scriptPath || !releases?.length) {
+    return;
+  }
+
+  const resolvedScriptPath = path.resolve(process.cwd(), scriptPath);
+  console.log(`📌 Running post-version script: ${resolvedScriptPath}`);
+
+  if (isMonoRepo()) {
+    for (const release of getAppReleases(releases)) {
+      await $`node ${resolvedScriptPath} ${release.newVersion}`;
+    }
+  } else {
+    const newVersion = releases[0]?.newVersion;
+    if (newVersion) {
+      await $`node ${resolvedScriptPath} ${newVersion}`;
+    }
+  }
+}
+
 async function commitTagCommand(releases) {
   console.log('📌 Checking for updates to commit...');
 
@@ -157,12 +178,17 @@ program
     '--install-latest',
     'Install the latest version of @docupace/pipeline instead of the current version',
   )
+  .option(
+    '--post-version-script <path>',
+    'Path to a JS file to run after the version is bumped but before it is committed, tagged, and pushed. Called with the new version as its first argument.',
+  )
   .action(async (options) => {
     console.log('📦 Running all steps...');
     try {
       const releases = await versionCommand(false, options.installLatest);
       await updateJiraWithVersion(releases);
       await updateWikiWithVersion(releases);
+      await runPostVersionScript(options.postVersionScript, releases);
       await commitTagCommand(releases);
     } catch (error) {
       console.error('❌ Version-commit-tag failed:', error);

package/src/changeset/validate.js

@@ -1,14 +1,32 @@
 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/config.js

@@ -144,7 +144,7 @@ export const getBitbucketInfo = () => {
 };
 
 export const getRepUrl = (repoName) => {
-  const { username, password, workspace } = getBitbucketInfo();
+  const { password, workspace } = getBitbucketInfo();
   return `https://x-bitbucket-api-token-auth:${password}@bitbucket.org/${workspace}/${repoName}.git`;
 };
 
@@ -172,3 +172,5 @@ export const coreSiteEnvMap = {
 };
 
 export const autoDeployConfigName = 'auto-deploy.yaml';
+
+export const connectDeployRepoName = 'dp-eks-connect-ui-gitops';

package/src/next/connect.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import { $ } from 'zx';
 import { getVaultSecrets } from '../auth0/vault.js';
+import { connectDeployRepoName } from './config.js';
 
 process.env.COMMON_VAULT_PATH =
   process.env.COMMON_VAULT_PATH || 'secret/data/common/config';
@@ -109,9 +110,9 @@ export async function connectClone() {
   process.env.AUTH0_DOMAIN = `docupace-${idpEnvMap[process.env.BUILD_ENVIRONMENT]}-${process.env.BUILD_SITE}.${process.env.AUTH0_REGION_DOMAIN}`;
 
   const projectRoot = process.cwd();
-  // 4) Clone 'connect-deploy' into CONNECT_DIR
+  // 4) Clone connect deploy repo into CONNECT_DIR
 
-  await gitCheckout('connect-deploy', process.env.CONNECT_DIR);
+  await gitCheckout(connectDeployRepoName, process.env.CONNECT_DIR);
 
   await gitCheckout(
     `${siteSettingsEnvMap[connectToEnv]}-site-settings`,

package/src/next/deploy.js

@@ -7,6 +7,7 @@ import semver from 'semver';
 import { $ } from 'zx';
 import {
   appInfo,
+  connectDeployRepoName,
   environmentConfig,
   getDefaultAppInfo,
   getRepUrl,
@@ -1188,7 +1189,7 @@ export async function deployFromSite(
     );
     if (getComparedVersion) {
       console.log('Version to deploy is: ', getComparedVersion);
-      const connectDeployPath = await cloneRepository('connect-deploy');
+      const connectDeployPath = await cloneRepository(connectDeployRepoName);
       // update target version set to git-commit-${getCommparedVersion}}
       await updateAndCommitConnectVersion(
         toEnv,

package/src/next/deploy.test.js

@@ -54,6 +54,7 @@ jest.unstable_mockModule('./config.js', () => ({
     deployAttributes: ['image.tag'],
   })),
   autoDeployConfigName: 'auto-deploy.yaml',
+  connectDeployRepoName: 'dp-eks-connect-ui-gitops',
 }));
 
 jest.unstable_mockModule('./copy.js', () => ({

package/src/next/util.js

@@ -84,12 +84,54 @@ 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.
+    // Not every step has BITBUCKET_STEP_OAUTH_TOKEN (it depends on step/repo
+    // OAuth config), so fall back to BITBUCKET_APP_PASSWORD (an API token,
+    // despite the name — app passwords are deprecated) paired with the
+    // static x-bitbucket-api-token-auth username, matching getRepUrl() in
+    // ../next/config.js.
+    const token =
+      process.env.BITBUCKET_STEP_OAUTH_TOKEN || process.env.BITBUCKET_TOKEN;
+    const apiToken = process.env.BITBUCKET_APP_PASSWORD;
+    let repoUrl;
+    if (token) {
+      repoUrl = `https://x-token-auth:${token}@bitbucket.org/dp-cloud/${process.env.BITBUCKET_REPO_SLUG}.git`;
+    } else if (apiToken) {
+      repoUrl = `https://x-bitbucket-api-token-auth:${apiToken}@bitbucket.org/dp-cloud/${process.env.BITBUCKET_REPO_SLUG}.git`;
+    }
+    if (!repoUrl) {
+      console.log(
+        'setGitInfo: no BITBUCKET_STEP_OAUTH_TOKEN/BITBUCKET_TOKEN or BITBUCKET_APP_PASSWORD available, leaving origin as-is',
+      );
+    } else {
+      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 =
+  '==============================================================';