@docupace/pipeline 1.0.123-xray.0 → 1.0.123-xray.1

package/package.json

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

package/src/tenable/args.js

@@ -93,6 +93,11 @@ export function buildPipelineRunInfo({
   };
 }
 
+// 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,
@@ -120,9 +125,9 @@ export function buildScanArgs({
     '--code-repository-url',
     codeRepoUrl,
     '--min-severity',
-    minSeverity,
+    String(minSeverity).toLowerCase(),
     '--output-file-formats',
-    'Json,Md,JUnit',
+    'json,md,junit',
     '--output-path',
     '/tmp/tenable/out',
     '--output-file-name',
@@ -142,7 +147,7 @@ export function buildScanArgs({
   }
 
   if (failOnMinSeverity) {
-    args.push('--fail-on-min-severity', failOnMinSeverity);
+    args.push('--fail-on-min-severity', failOnMinSeverity.toLowerCase());
   }
 
   return args;

package/src/tenable/args.test.js

@@ -184,9 +184,9 @@ describe('buildScanArgs', () => {
       '--code-repository-url',
       'https://bitbucket.org/dp-cloud/my-repo',
       '--min-severity',
-      'Medium',
+      'medium',
       '--output-file-formats',
-      'Json,Md,JUnit',
+      'json,md,junit',
       '--output-path',
       '/tmp/tenable/out',
       '--output-file-name',
@@ -220,7 +220,7 @@ describe('buildScanArgs', () => {
   test('appends --fail-on-min-severity only when set', () => {
     expect(buildScanArgs(base)).not.toContain('--fail-on-min-severity');
     expect(buildScanArgs({ ...base, failOnMinSeverity: 'High' })).toEqual(
-      expect.arrayContaining(['--fail-on-min-severity', 'High']),
+      expect.arrayContaining(['--fail-on-min-severity', 'high']),
     );
   });
 });

package/src/tenable/scan.js

@@ -97,7 +97,17 @@ export async function scanOne(target, ctx) {
     args: scanArgs,
     volume: `${work}:/tmp/tenable`,
     workdir: '/tmp/tenable',
-    env: ['TENABLE_API_TOKEN', 'TENABLE_API_URL'],
+    // The output destination goes over BOTH transports on purpose. Tenable's own
+    // GitHub action passes output-path and output-file-name only as TENABLE_*
+    // env vars, never as flags, so a build of the scanner that ignores the flags
+    // would silently fall back to its default path (the working directory) and
+    // leave the reports where nothing looks for them.
+    env: [
+      'TENABLE_API_TOKEN',
+      'TENABLE_API_URL',
+      'TENABLE_OUTPUT_PATH=/tmp/tenable/out',
+      `TENABLE_OUTPUT_FILE_NAME=${slug}-tenable`,
+    ],
   });
 
   // Collect reports even on a non-zero exit — a threshold failure still produces them.
@@ -105,7 +115,28 @@ export async function scanOne(target, ctx) {
     fsops.mkdirp(reportDir);
     fsops.copyReports(`${work}/out`, reportDir);
   } else {
-    log(`Tenable produced no report files for '${slug}'.`);
+    // Before declaring the scan reportless, look in the work root: that is the
+    // scanner's default output path, so anything it wrote while ignoring the
+    // requested one lands beside the archive — and the work dir is deleted a few
+    // lines below, taking the reports with it.
+    const stray = fsops
+      .listDir(work)
+      .filter((name) => name !== 'image.tar' && name !== 'out');
+    if (stray.length > 0) {
+      log(
+        `Tenable wrote to the work root rather than the requested output path: ${stray.join(', ')}`,
+      );
+      fsops.mkdirp(reportDir);
+      for (const name of stray) {
+        fsops.copyReports(`${work}/${name}`, `${reportDir}/${name}`);
+      }
+    } else {
+      // The scanner exits 0 and prints nothing when it rejects an output format,
+      // so an empty work dir is worth reporting with the exit code attached.
+      log(
+        `Tenable produced no report files for '${slug}' (scanner exit ${exitCode}).`,
+      );
+    }
   }
 
   const summaryPath = `${reportDir}/${slug}-tenable.md`;

package/src/tenable/scan.test.js

@@ -101,6 +101,55 @@ describe('scanOne', () => {
     expect(docker.rmi).not.toHaveBeenCalled();
   });
 
+  test('recovers reports the scanner wrote to the work root instead of out/', async () => {
+    const work = '/work/.tenable-work.abc';
+    const fsops = makeFakeFsops({
+      listDir: jest.fn((dir) =>
+        dir === `${work}/out`
+          ? []
+          : ['image.tar', 'out', 'results.json', 'results.md'],
+      ),
+    });
+    const ctx = baseCtx({ fsops });
+
+    await scanOne(
+      { label: 'image', slug: 'image', prebuiltImage: 'my-image:tag' },
+      ctx,
+    );
+
+    // The archive and the empty output dir are not reports; everything else is.
+    expect(fsops.copyReports).toHaveBeenCalledTimes(2);
+    expect(fsops.copyReports).toHaveBeenCalledWith(
+      `${work}/results.json`,
+      'tenable-report/results.json',
+    );
+    expect(fsops.copyReports).toHaveBeenCalledWith(
+      `${work}/results.md`,
+      'tenable-report/results.md',
+    );
+  });
+
+  test('reports the scanner exit code when nothing was written anywhere', async () => {
+    const docker = makeFakeDocker({ run: jest.fn().mockResolvedValue(2) });
+    const fsops = makeFakeFsops({
+      listDir: jest.fn((dir) =>
+        dir === '/work/.tenable-work.abc/out' ? [] : ['image.tar'],
+      ),
+    });
+    const log = jest.fn();
+    const ctx = baseCtx({ docker, fsops, log });
+
+    await scanOne(
+      { label: 'image', slug: 'image', prebuiltImage: 'my-image:tag' },
+      ctx,
+    );
+
+    expect(fsops.copyReports).not.toHaveBeenCalled();
+    expect(log.mock.calls.flat().join('\n')).toContain(
+      "no report files for 'image' (scanner exit 2)",
+    );
+  });
+
   test('skips a target with no Dockerfile at the expected path', async () => {
     const docker = makeFakeDocker();
     const fsops = makeFakeFsops({ exists: jest.fn().mockReturnValue(false) });

package/src/veracode/args.js

@@ -0,0 +1,67 @@
+// Pure parsing/formatting logic for the Veracode scan step, ported from the
+// veracode-scan step in bitbucket-pipelines.yml. No fs/process 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, '-');
+}
+
+// Mirrors `printf '%s' "${BITBUCKET_COMMIT:-local}" | cut -c1-7`.
+export function shortSha(commit = 'local') {
+  return (commit || 'local').slice(0, 7);
+}
+
+// One "label:appname:path1,path2,..." entry from VERACODE_TARGETS. Mirrors
+// `cut -d: -f1/-f2/-f3`: only the first three colon-delimited fields matter,
+// and a 4th+ field (e.g. a colon inside a path) is silently dropped rather
+// than folded into the paths field.
+export function parseVeracodeTargets(targetsStr) {
+  return (targetsStr || '')
+    .split(';')
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .map((raw) => {
+      const [rawLabel = '', appname = '', pathsField = ''] = raw.split(':');
+      const label = rawLabel || 'app';
+      const slug = slugify(label);
+      const paths = pathsField.split(',').filter((p) => p.length > 0);
+
+      if (!appname || paths.length === 0) {
+        return { label, slug, appname, paths, skipped: true };
+      }
+      return { label, slug, appname, paths, skipped: false };
+    });
+}
+
+export function buildZipFilename(slug) {
+  return `veracode-${slug}.zip`;
+}
+
+export function buildVersion(sha, label) {
+  return `sha-${sha}-${label}`;
+}
+
+// -createprofile false — the app profile must already exist in the Veracode
+// portal. -autoscan true starts the scan once prescan passes.
+export function buildUploadArgs({ vid, vkey, appname, filepath, version }) {
+  return [
+    '-vid',
+    vid,
+    '-vkey',
+    vkey,
+    '-action',
+    'uploadandscan',
+    '-appname',
+    appname,
+    '-createprofile',
+    'false',
+    '-autoscan',
+    'true',
+    '-filepath',
+    filepath,
+    '-version',
+    version,
+  ];
+}

package/src/veracode/args.test.js

@@ -0,0 +1,137 @@
+import { describe, expect, test } from '@jest/globals';
+import {
+  slugify,
+  shortSha,
+  parseVeracodeTargets,
+  buildZipFilename,
+  buildVersion,
+  buildUploadArgs,
+} from './args.js';
+
+describe('slugify', () => {
+  test('replaces every non [A-Za-z0-9._-] character with a dash', () => {
+    expect(slugify('my app!')).toBe('my-app-');
+    expect(slugify('my/app')).toBe('my-app');
+    expect(slugify('already-safe_v1.2')).toBe('already-safe_v1.2');
+  });
+});
+
+describe('shortSha', () => {
+  test('truncates a commit sha to 7 characters', () => {
+    expect(shortSha('abcdef1234567')).toBe('abcdef1');
+  });
+
+  test('defaults to "local" when no commit is given', () => {
+    expect(shortSha()).toBe('local');
+    expect(shortSha('')).toBe('local');
+  });
+});
+
+describe('parseVeracodeTargets', () => {
+  test('parses label:appname:path1,path2 entries', () => {
+    const targets = parseVeracodeTargets(
+      'frontend:my-app-fe:apps/fe,libs/shared;backend:my-app-be:apps/be',
+    );
+
+    expect(targets).toEqual([
+      {
+        label: 'frontend',
+        slug: 'frontend',
+        appname: 'my-app-fe',
+        paths: ['apps/fe', 'libs/shared'],
+        skipped: false,
+      },
+      {
+        label: 'backend',
+        slug: 'backend',
+        appname: 'my-app-be',
+        paths: ['apps/be'],
+        skipped: false,
+      },
+    ]);
+  });
+
+  test('defaults an empty label to "app" and slugifies it', () => {
+    const [target] = parseVeracodeTargets(':my-app:src');
+    expect(target.label).toBe('app');
+    expect(target.slug).toBe('app');
+  });
+
+  test('marks a target with no appname as skipped', () => {
+    const [target] = parseVeracodeTargets('web::src');
+    expect(target).toEqual({
+      label: 'web',
+      slug: 'web',
+      appname: '',
+      paths: ['src'],
+      skipped: true,
+    });
+  });
+
+  test('marks a target with no paths as skipped', () => {
+    const [target] = parseVeracodeTargets('web:my-app:');
+    expect(target).toEqual({
+      label: 'web',
+      slug: 'web',
+      appname: 'my-app',
+      paths: [],
+      skipped: true,
+    });
+  });
+
+  test('drops a 4th+ colon-delimited field rather than folding it into paths', () => {
+    const [target] = parseVeracodeTargets('web:my-app:src:extra');
+    expect(target.paths).toEqual(['src']);
+  });
+
+  test('ignores blank entries between semicolons', () => {
+    expect(parseVeracodeTargets('web:my-app:src;;')).toHaveLength(1);
+  });
+
+  test('empty string produces no targets', () => {
+    expect(parseVeracodeTargets('')).toEqual([]);
+  });
+});
+
+describe('buildZipFilename', () => {
+  test('builds a "veracode-<slug>.zip" filename', () => {
+    expect(buildZipFilename('web')).toBe('veracode-web.zip');
+  });
+});
+
+describe('buildVersion', () => {
+  test('builds "sha-<sha>-<label>", using the raw label rather than its slug', () => {
+    expect(buildVersion('abc1234', 'my app')).toBe('sha-abc1234-my app');
+  });
+});
+
+describe('buildUploadArgs', () => {
+  test('builds the Veracode wrapper CLI args', () => {
+    expect(
+      buildUploadArgs({
+        vid: 'vid-1',
+        vkey: 'vkey-1',
+        appname: 'my-app',
+        filepath: 'veracode-web.zip',
+        version: 'sha-abc1234-web',
+      }),
+    ).toEqual([
+      '-vid',
+      'vid-1',
+      '-vkey',
+      'vkey-1',
+      '-action',
+      'uploadandscan',
+      '-appname',
+      'my-app',
+      '-createprofile',
+      'false',
+      '-autoscan',
+      'true',
+      '-filepath',
+      'veracode-web.zip',
+      '-version',
+      'sha-abc1234-web',
+    ]);
+  });
+});

package/src/veracode/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { runVeracodeScan } from './scan.js';
+
+const program = new Command();
+
+program
+  .command('scan')
+  .description('Upload and scan one or more app targets with Veracode')
+  .action(async () => {
+    const { exitCode } = await runVeracodeScan();
+    process.exit(exitCode);
+  });
+
+program.parse(process.argv);

package/src/veracode/fsops.js

@@ -0,0 +1,7 @@
+import fs from 'fs-extra';
+
+export const fsOps = {
+  exists: (p) => fs.existsSync(p),
+  mkdirp: (dir) => fs.mkdirpSync(dir),
+  removeSync: (p) => fs.removeSync(p),
+};

package/src/veracode/scan.js

@@ -0,0 +1,120 @@
+import path from 'path';
+import {
+  buildUploadArgs,
+  buildVersion,
+  buildZipFilename,
+  parseVeracodeTargets,
+  shortSha as computeShortSha,
+} from './args.js';
+import { veracode as defaultVeracode } from './veracode.js';
+import { fsOps as defaultFsOps } from './fsops.js';
+
+export const DEFAULT_WRAPPER_JAR = 'veracode-wrapper/VeracodeJavaAPI.jar';
+export const DEFAULT_WRAPPER_URL =
+  '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';
+
+// Zips one target's paths and submits them as their 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.
+export async function scanOne(target, ctx) {
+  const { vid, vkey, shortSha, wrapperJar, veracode, fsops, log } = ctx;
+  const { label, appname, paths, slug, skipped } = target;
+
+  if (skipped) {
+    log(
+      `Target '${label}' is missing an appname or paths in VERACODE_TARGETS — skipping.`,
+    );
+    return { label, slug, exitCode: 1 };
+  }
+
+  const zipFile = buildZipFilename(slug);
+  fsops.removeSync(zipFile);
+
+  const zipped = await veracode.zip(zipFile, paths);
+  if (!zipped.ok) {
+    log(`Failed to zip paths for '${label}' — skipping its Veracode scan.`);
+    fsops.removeSync(zipFile);
+    return { label, slug, exitCode: 1 };
+  }
+
+  const version = buildVersion(shortSha, label);
+  const args = buildUploadArgs({
+    vid,
+    vkey,
+    appname,
+    filepath: zipFile,
+    version,
+  });
+
+  const uploaded = await veracode.uploadAndScan(wrapperJar, args);
+  fsops.removeSync(zipFile);
+
+  if (!uploaded.ok) {
+    log(`ERROR: Veracode scan submission failed for '${label}'.`);
+    return { label, slug, exitCode: 1 };
+  }
+
+  return { label, slug, exitCode: 0 };
+}
+
+export async function runVeracodeScan({
+  vid = process.env.VERACODE_API_ID || '',
+  vkey = process.env.VERACODE_API_KEY || '',
+  targetsEnv = process.env.VERACODE_TARGETS || '',
+  buildCmd = process.env.VERACODE_BUILD_CMD || '',
+  commit = process.env.BITBUCKET_COMMIT || 'local',
+  wrapperJar = process.env.VERACODE_WRAPPER_JAR || DEFAULT_WRAPPER_JAR,
+  wrapperUrl = process.env.VERACODE_WRAPPER_URL || DEFAULT_WRAPPER_URL,
+  veracode = defaultVeracode,
+  fsops = defaultFsOps,
+  log = console.log,
+} = {}) {
+  if (!vid || !vkey) {
+    log(
+      'ERROR: VERACODE_API_ID / VERACODE_API_KEY not set — cannot run Veracode scan.',
+    );
+    return { exitCode: 1, results: [] };
+  }
+  if (!targetsEnv) {
+    log('ERROR: VERACODE_TARGETS not set — cannot run Veracode scan.');
+    log(
+      '       Expected: label:appname:path1,path2,...[;label2:appname2:path1,...]',
+    );
+    return { exitCode: 1, results: [] };
+  }
+
+  // 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. Its exit code isn't
+  // gated on here, matching the pipeline step it's ported from — a failure
+  // will simply surface as a failed upload for every target below.
+  if (buildCmd) {
+    log('Running VERACODE_BUILD_CMD...');
+    await veracode.runBuildCmd(buildCmd);
+  }
+
+  // Cached across builds on self-hosted runners; downloaded once.
+  if (!fsops.exists(wrapperJar)) {
+    fsops.mkdirp(path.dirname(wrapperJar));
+    await veracode.download(wrapperUrl, wrapperJar);
+  }
+
+  const sha = computeShortSha(commit);
+  const results = [];
+  for (const target of parseVeracodeTargets(targetsEnv)) {
+    results.push(
+      await scanOne(target, {
+        vid,
+        vkey,
+        shortSha: sha,
+        wrapperJar,
+        veracode,
+        fsops,
+        log,
+      }),
+    );
+  }
+
+  const exitCode = results.some((r) => r.exitCode !== 0) ? 1 : 0;
+  return { exitCode, results };
+}

package/src/veracode/scan.test.js

@@ -0,0 +1,246 @@
+import { describe, expect, jest, test } from '@jest/globals';
+import { scanOne, runVeracodeScan, DEFAULT_WRAPPER_JAR } from './scan.js';
+
+function makeFakeVeracode(overrides = {}) {
+  return {
+    download: jest.fn().mockResolvedValue({ ok: true }),
+    runBuildCmd: jest.fn().mockResolvedValue({ ok: true }),
+    zip: jest.fn().mockResolvedValue({ ok: true }),
+    uploadAndScan: jest.fn().mockResolvedValue({ ok: true }),
+    ...overrides,
+  };
+}
+
+function makeFakeFsops(overrides = {}) {
+  return {
+    exists: jest.fn().mockReturnValue(true),
+    mkdirp: jest.fn(),
+    removeSync: jest.fn(),
+    ...overrides,
+  };
+}
+
+const baseCtx = (overrides = {}) => ({
+  vid: 'vid-1',
+  vkey: 'vkey-1',
+  shortSha: 'abc1234',
+  wrapperJar: DEFAULT_WRAPPER_JAR,
+  veracode: makeFakeVeracode(),
+  fsops: makeFakeFsops(),
+  log: jest.fn(),
+  ...overrides,
+});
+
+describe('scanOne', () => {
+  test('zips, uploads and cleans up a normal target', async () => {
+    const veracode = makeFakeVeracode();
+    const fsops = makeFakeFsops();
+    const ctx = baseCtx({ veracode, fsops });
+
+    const result = await scanOne(
+      {
+        label: 'web',
+        slug: 'web',
+        appname: 'my-app',
+        paths: ['services/web'],
+        skipped: false,
+      },
+      ctx,
+    );
+
+    expect(result).toEqual({ label: 'web', slug: 'web', exitCode: 0 });
+    expect(veracode.zip).toHaveBeenCalledWith('veracode-web.zip', [
+      'services/web',
+    ]);
+    expect(veracode.uploadAndScan).toHaveBeenCalledWith(
+      DEFAULT_WRAPPER_JAR,
+      expect.arrayContaining([
+        '-appname',
+        'my-app',
+        '-version',
+        'sha-abc1234-web',
+      ]),
+    );
+    expect(fsops.removeSync).toHaveBeenCalledWith('veracode-web.zip');
+  });
+
+  test('skips a target missing an appname or paths', async () => {
+    const veracode = makeFakeVeracode();
+    const ctx = baseCtx({ veracode });
+
+    const result = await scanOne(
+      { label: 'web', slug: 'web', appname: '', paths: [], skipped: true },
+      ctx,
+    );
+
+    expect(result).toEqual({ label: 'web', slug: 'web', exitCode: 1 });
+    expect(veracode.zip).not.toHaveBeenCalled();
+  });
+
+  test('returns exitCode 1 and skips upload when zipping fails', async () => {
+    const veracode = makeFakeVeracode({
+      zip: jest.fn().mockResolvedValue({ ok: false }),
+    });
+    const fsops = makeFakeFsops();
+    const ctx = baseCtx({ veracode, fsops });
+
+    const result = await scanOne(
+      {
+        label: 'web',
+        slug: 'web',
+        appname: 'my-app',
+        paths: ['services/web'],
+        skipped: false,
+      },
+      ctx,
+    );
+
+    expect(result).toEqual({ label: 'web', slug: 'web', exitCode: 1 });
+    expect(veracode.uploadAndScan).not.toHaveBeenCalled();
+    expect(fsops.removeSync).toHaveBeenCalledWith('veracode-web.zip');
+  });
+
+  test('returns exitCode 1 when the upload fails, but still cleans up the zip', async () => {
+    const veracode = makeFakeVeracode({
+      uploadAndScan: jest.fn().mockResolvedValue({ ok: false }),
+    });
+    const fsops = makeFakeFsops();
+    const ctx = baseCtx({ veracode, fsops });
+
+    const result = await scanOne(
+      {
+        label: 'web',
+        slug: 'web',
+        appname: 'my-app',
+        paths: ['services/web'],
+        skipped: false,
+      },
+      ctx,
+    );
+
+    expect(result).toEqual({ label: 'web', slug: 'web', exitCode: 1 });
+    expect(fsops.removeSync).toHaveBeenCalledWith('veracode-web.zip');
+  });
+});
+
+describe('runVeracodeScan', () => {
+  test('fails fast when credentials are missing', async () => {
+    const log = jest.fn();
+    const result = await runVeracodeScan({
+      vid: '',
+      vkey: '',
+      targetsEnv: 'web:my-app:src',
+      log,
+    });
+
+    expect(result).toEqual({ exitCode: 1, results: [] });
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining('VERACODE_API_ID / VERACODE_API_KEY not set'),
+    );
+  });
+
+  test('fails fast when VERACODE_TARGETS is missing', async () => {
+    const log = jest.fn();
+    const result = await runVeracodeScan({
+      vid: 'vid-1',
+      vkey: 'vkey-1',
+      targetsEnv: '',
+      log,
+    });
+
+    expect(result).toEqual({ exitCode: 1, results: [] });
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining('VERACODE_TARGETS not set'),
+    );
+  });
+
+  test('runs VERACODE_BUILD_CMD before packaging when set', async () => {
+    const veracode = makeFakeVeracode();
+    const fsops = makeFakeFsops();
+
+    await runVeracodeScan({
+      vid: 'vid-1',
+      vkey: 'vkey-1',
+      targetsEnv: 'web:my-app:src',
+      buildCmd: 'npm run build',
+      veracode,
+      fsops,
+      log: jest.fn(),
+    });
+
+    expect(veracode.runBuildCmd).toHaveBeenCalledWith('npm run build');
+  });
+
+  test('downloads the wrapper jar only when not already cached', async () => {
+    const veracode = makeFakeVeracode();
+    const fsops = makeFakeFsops({ exists: jest.fn().mockReturnValue(false) });
+
+    await runVeracodeScan({
+      vid: 'vid-1',
+      vkey: 'vkey-1',
+      targetsEnv: 'web:my-app:src',
+      veracode,
+      fsops,
+      log: jest.fn(),
+    });
+
+    expect(veracode.download).toHaveBeenCalledWith(
+      expect.stringContaining('vosp-api-wrappers-java'),
+      DEFAULT_WRAPPER_JAR,
+    );
+  });
+
+  test('skips the download when the wrapper jar already exists', async () => {
+    const veracode = makeFakeVeracode();
+    const fsops = makeFakeFsops({ exists: jest.fn().mockReturnValue(true) });
+
+    await runVeracodeScan({
+      vid: 'vid-1',
+      vkey: 'vkey-1',
+      targetsEnv: 'web:my-app:src',
+      veracode,
+      fsops,
+      log: jest.fn(),
+    });
+
+    expect(veracode.download).not.toHaveBeenCalled();
+  });
+
+  test('scans every target and reports the worst outcome', async () => {
+    const veracode = makeFakeVeracode({
+      uploadAndScan: jest
+        .fn()
+        .mockResolvedValueOnce({ ok: true })
+        .mockResolvedValueOnce({ ok: false }),
+    });
+    const fsops = makeFakeFsops();
+
+    const result = await runVeracodeScan({
+      vid: 'vid-1',
+      vkey: 'vkey-1',
+      targetsEnv: 'web:my-app:apps/web;worker:my-worker:apps/worker',
+      veracode,
+      fsops,
+      log: jest.fn(),
+    });
+
+    expect(result.results.map((r) => r.label)).toEqual(['web', 'worker']);
+    expect(result.exitCode).toBe(1);
+  });
+
+  test('exits 0 when every target scans successfully', async () => {
+    const veracode = makeFakeVeracode();
+    const fsops = makeFakeFsops();
+
+    const result = await runVeracodeScan({
+      vid: 'vid-1',
+      vkey: 'vkey-1',
+      targetsEnv: 'web:my-app:apps/web',
+      veracode,
+      fsops,
+      log: jest.fn(),
+    });
+
+    expect(result.exitCode).toBe(0);
+  });
+});

package/src/veracode/veracode.js

@@ -0,0 +1,33 @@
+import { $ } from 'zx';
+
+// Thin wrappers around the external commands the Veracode step shells out to,
+// so scan.js can inject a fake in tests. Every call uses nothrow: a non-zero
+// exit is meaningful data here (a failed build/zip/upload), not an
+// exceptional case.
+export const veracode = {
+  async download(url, dest) {
+    const result = await $({
+      nothrow: true,
+      quiet: true,
+    })`curl -sSL ${url} -o ${dest}`;
+    return { ok: result.exitCode === 0 };
+  },
+
+  // Runs the consumer-supplied VERACODE_BUILD_CMD via `sh -c` so its own
+  // shell operators (&&, |, ...) are honored, mirroring the pipeline's
+  // `eval "${VERACODE_BUILD_CMD}"`.
+  async runBuildCmd(cmd) {
+    const result = await $({ nothrow: true })`sh -c ${cmd}`;
+    return { ok: result.exitCode === 0 };
+  },
+
+  async zip(zipFile, paths) {
+    const result = await $({ nothrow: true })`zip -r ${zipFile} ${paths}`;
+    return { ok: result.exitCode === 0 };
+  },
+
+  async uploadAndScan(jarPath, args) {
+    const result = await $({ nothrow: true })`java -jar ${jarPath} ${args}`;
+    return { ok: result.exitCode === 0 };
+  },
+};