@elastic/synthetics 1.24.4 → 1.26.0

package/src/cli.ts

@@ -74,6 +74,7 @@ const {
   match,
   fields,
   maintenanceWindows,
+  certificateErrorSpkiAllowlist,
 } = getCommonCommandOpts();
 
 program
@@ -128,6 +129,7 @@ program
     '--ignore-https-errors',
     'ignores any HTTPS errors in sites being tested, including ones related to unrecognized certs or signatures. This can be insecure!'
   )
+  .addOption(certificateErrorSpkiAllowlist)
   .option(
     '--quiet-exit-code',
     'always return 0 as an exit code status, regardless of test pass / fail. Only return > 0 exit codes on internal errors where the suite could not be run'
@@ -232,6 +234,7 @@ program
   .addOption(match)
   .addOption(params)
   .addOption(playwrightOpts)
+  .addOption(certificateErrorSpkiAllowlist)
   .addOption(configOpt)
   .addOption(maintenanceWindows)
   .action(async cmdOpts => {

package/src/common_types.ts

@@ -64,6 +64,10 @@ export type NetworkConditions = {
   latency: number;
 };
 
+export type APIDriver = {
+  request: APIRequestContext;
+};
+
 export type Driver = {
   browser: ChromiumBrowser;
   context: ChromiumBrowserContext;
@@ -208,6 +212,16 @@ type GrepOptions = {
   match?: string;
 };
 
+/**
+ * PEM certificates (or Buffers) used to build Chromium's SPKI certificate-error
+ * allowlist. This does not add a CA to Chromium's trust store: matching
+ * certificates bypass certificate validation errors.
+ */
+export type CertificateErrorSpkiAllowlist =
+  | string
+  | Buffer
+  | Array<string | Buffer>;
+
 type BaseArgs = {
   params?: Params;
   screenshots?: ScreenshotOptions;
@@ -217,6 +231,7 @@ type BaseArgs = {
   outfd?: number;
   wsEndpoint?: string;
   pauseOnError?: boolean;
+  certificateErrorSpkiAllowlist?: CertificateErrorSpkiAllowlist;
   playwrightOptions?: PlaywrightOptions;
   quietExitCode?: boolean;
   throttling?: MonitorConfig['throttling'];
@@ -256,6 +271,13 @@ export type RunOptions = BaseArgs & {
   grepOpts?: GrepOptions;
 };
 
+export type APIRunOptions = BaseArgs & {
+  network?: boolean;
+  environment?: string;
+  reporter?: BuiltInReporterName | ReporterInstance;
+  grepOpts?: GrepOptions;
+};
+
 export type PushOptions = Partial<ProjectSettings> &
   Partial<BaseArgs> & {
     auth: string;
@@ -289,6 +311,13 @@ export type SyntheticsConfig = {
   monitor?: MonitorConfig;
   project?: ProjectSettings;
   proxy?: ProxySettings;
+  certificateErrorSpkiAllowlist?: CertificateErrorSpkiAllowlist;
+};
+
+/** Runner Payload types */
+export type APIJourneyResult = Partial<Journey> & {
+  networkinfo?: PluginOutput['networkinfo'];
+  stepsresults?: Array<StepResult>;
 };
 
 /** Runner Payload types */
@@ -330,6 +359,11 @@ export type JourneyEndResult = JourneyStartResult &
     options: RunOptions;
   };
 
+export type APIJourneyEndResult = JourneyStartResult &
+  APIJourneyResult & {
+    options: RunOptions;
+  };
+
 export type StepEndResult = StepResult;
 
 export type ProxySettings = {

package/src/core/certs.ts

@@ -0,0 +1,122 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2020-present, Elastic NV
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+import { X509Certificate, createHash } from 'crypto';
+import { CertificateErrorSpkiAllowlist } from '../common_types';
+import { warn } from '../helpers';
+
+const PEM_CERTIFICATE_RE =
+  /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g;
+
+/**
+ * Normalize user-provided PEM certificates (string, Buffer, or an array of
+ * either) into a flat list of PEM strings. Each entry may itself be a bundle
+ * that contains more than one certificate.
+ */
+export function normalizeCertificateErrorSpkiAllowlist(
+  certificates?: CertificateErrorSpkiAllowlist
+): string[] {
+  if (certificates == null) {
+    return [];
+  }
+  const entries = Array.isArray(certificates) ? certificates : [certificates];
+  return entries
+    .map(entry => (Buffer.isBuffer(entry) ? entry.toString('utf-8') : entry))
+    .filter((entry): entry is string => Boolean(entry && entry.trim()));
+}
+
+/**
+ * Split a PEM bundle into the individual certificates it contains. Node's
+ * `X509Certificate` only parses the first certificate of a bundle, so we have
+ * to slice them apart ourselves to support full chains / multiple CAs.
+ */
+export function splitPemCertificates(pem: string): string[] {
+  return pem.match(PEM_CERTIFICATE_RE) ?? [];
+}
+
+/**
+ * Compute the base64 encoded SHA-256 fingerprint of a certificate's
+ * SubjectPublicKeyInfo (SPKI). This is the exact value Chromium expects in the
+ * `--ignore-certificate-errors-spki-list` switch.
+ */
+export function getSpkiFingerprint(pem: string): string {
+  const der = new X509Certificate(pem).publicKey.export({
+    type: 'spki',
+    format: 'der',
+  });
+  return createHash('sha256').update(der).digest('base64');
+}
+
+/**
+ * Describe an entry that failed to parse as a certificate for use in a
+ * warning message. A raw file path (e.g. from a typo'd
+ * `certificateErrorSpkiAllowlist` entry that didn't match an existing file) is
+ * shown as-is since that's the actionable detail; inline PEM content is not,
+ * to avoid dumping key material to the console.
+ */
+function describeInvalidCertificateEntry(candidate: string): string {
+  if (candidate.includes('-----BEGIN CERTIFICATE-----')) {
+    return 'an inline PEM certificate';
+  }
+  const preview =
+    candidate.length > 80 ? `${candidate.slice(0, 80)}...` : candidate;
+  return `"${preview}"`;
+}
+
+/**
+ * Build the list of SPKI fingerprints for all supplied certificates. Chromium
+ * uses this list to bypass certificate errors for matching presented
+ * certificates; it does not establish CA trust. Invalid certificates are
+ * skipped, with a warning, so a single bad entry never aborts the whole run
+ * but also never fails silently - a `certificateErrorSpkiAllowlist` entry that
+ * doesn't resolve to a real file and isn't valid PEM (e.g. a typo'd path)
+ * would otherwise never be allowlisted, and matching endpoints would keep
+ * failing certificate validation with no indication why.
+ */
+export function getSpkiFingerprints(
+  certificates?: CertificateErrorSpkiAllowlist
+): string[] {
+  const fingerprints = new Set<string>();
+  for (const entry of normalizeCertificateErrorSpkiAllowlist(certificates)) {
+    const pemCertificates = splitPemCertificates(entry);
+    // Fall back to treating the whole entry as a single certificate when no
+    // PEM boundary markers are present.
+    const candidates = pemCertificates.length > 0 ? pemCertificates : [entry];
+    for (const certificate of candidates) {
+      try {
+        fingerprints.add(getSpkiFingerprint(certificate));
+      } catch (e) {
+        warn(
+          `certificateErrorSpkiAllowlist: could not parse ${describeInvalidCertificateEntry(
+            certificate
+          )} as a certificate - it will not be allowlisted and matching endpoints may still fail certificate validation (${
+            e.message
+          })`
+        );
+      }
+    }
+  }
+  return [...fingerprints];
+}

package/src/core/gatherer.ts

@@ -32,7 +32,13 @@ import {
 } from 'playwright-core';
 import { PluginManager } from '../plugins';
 import { log } from './logger';
-import { Driver, NetworkConditions, RunOptions } from '../common_types';
+import { getSpkiFingerprints } from './certs';
+import {
+  APIDriver,
+  Driver,
+  NetworkConditions,
+  RunOptions,
+} from '../common_types';
 
 // Default timeout for Playwright actions and Navigations
 const DEFAULT_TIMEOUT = 50000;
@@ -56,10 +62,31 @@ export class Gatherer {
       log(`Gatherer: connecting to WS endpoint: ${wsEndpoint}`);
       Gatherer.browser = await chromium.connect(wsEndpoint);
     } else {
+      /**
+       * Chromium on Linux has its own NSS trust store. This flag does not add
+       * a CA to that store: it bypasses certificate errors only when a
+       * presented certificate's SPKI matches one of the supplied fingerprints.
+       * It is narrower than `ignoreHTTPSErrors`, but is not CA trust.
+       */
+      const spkiFingerprints = getSpkiFingerprints(
+        options.certificateErrorSpkiAllowlist
+      );
+      if (spkiFingerprints.length > 0) {
+        log(
+          `Gatherer: bypassing certificate errors for ${spkiFingerprints.length} allowlisted SPKI fingerprint(s)`
+        );
+      }
       Gatherer.browser = await chromium.launch({
         ...playwrightOptions,
         args: [
           ...(playwrightOptions?.headless ? ['--disable-gpu'] : []),
+          ...(spkiFingerprints.length > 0
+            ? [
+                `--ignore-certificate-errors-spki-list=${spkiFingerprints.join(
+                  ','
+                )}`,
+              ]
+            : []),
           ...(playwrightOptions?.args ?? []),
         ],
       });
@@ -71,9 +98,19 @@ export class Gatherer {
     });
   }
 
-  static async setupDriver(options: RunOptions): Promise<Driver> {
-    await Gatherer.launchBrowser(options);
+  static async setupDriver<T extends 'browser' | 'api' = 'browser'>(
+    options: RunOptions,
+    journeyType: T = 'browser' as T
+  ): Promise<T extends 'api' ? APIDriver : Driver> {
     const { playwrightOptions } = options;
+
+    if (journeyType === 'api') {
+      const request = await apiRequest.newContext({ ...playwrightOptions });
+      return { request } as T extends 'api' ? APIDriver : Driver;
+    }
+
+    await Gatherer.launchBrowser(options);
+
     const context = await Gatherer.browser.newContext({
       ...playwrightOptions,
       userAgent: await Gatherer.getUserAgent(playwrightOptions?.userAgent),
@@ -96,7 +133,13 @@ export class Gatherer {
     const page = await context.newPage();
     const client = await context.newCDPSession(page);
     const request = await apiRequest.newContext({ ...playwrightOptions });
-    return { browser: Gatherer.browser, context, page, client, request };
+    return {
+      browser: Gatherer.browser,
+      context,
+      page,
+      client,
+      request,
+    } as T extends 'api' ? APIDriver : Driver;
   }
 
   static async getUserAgent(userAgent?: string) {
@@ -136,14 +179,22 @@ export class Gatherer {
    * Starts recording all events related to the v8 devtools protocol
    * https://chromedevtools.github.io/devtools-protocol/v8/
    */
-  static async beginRecording(driver: Driver, options: RunOptions) {
+  static async beginRecording(driver: Driver | APIDriver, options: RunOptions) {
     log('Gatherer: started recording');
     const { network, metrics } = options;
     Gatherer.pluginManager = new PluginManager(driver);
     Gatherer.pluginManager.registerAll(options);
-    const plugins = [await Gatherer.pluginManager.start('browserconsole')];
-    network && plugins.push(await Gatherer.pluginManager.start('network'));
-    metrics && plugins.push(await Gatherer.pluginManager.start('performance'));
+    const plugins = [];
+    if ('browser' in driver) {
+      plugins.push(await Gatherer.pluginManager.start('browserconsole'));
+      network && plugins.push(await Gatherer.pluginManager.start('network'));
+      metrics &&
+        plugins.push(await Gatherer.pluginManager.start('performance'));
+    } else {
+      // Network is the only data source for API journeys, so always capture
+      // it regardless of `options.network`.
+      plugins.push(await Gatherer.pluginManager.start('network'));
+    }
     await Promise.all(plugins);
     return Gatherer.pluginManager;
   }
@@ -153,10 +204,12 @@ export class Gatherer {
     await Gatherer.pluginManager.unregisterAll();
   }
 
-  static async dispose(driver: Driver) {
+  static async dispose(driver: Driver | APIDriver) {
     log(`Gatherer: closing all contexts`);
     await driver.request.dispose();
-    await driver.context.close();
+    if ('context' in driver) {
+      await driver.context.close();
+    }
   }
 
   static async stop() {

package/src/core/globals.ts

@@ -26,7 +26,7 @@
 import Runner from './runner';
 
 /**
- * Use a gloabl Runner which would be accessed by the runtime and
+ * Use a global Runner which would be accessed by the runtime and
  * required to handle the local vs global invocation through CLI
  */
 const SYNTHETICS_RUNNER = Symbol.for('SYNTHETICS_RUNNER');

package/src/core/index.ts

@@ -24,6 +24,10 @@
  */
 
 import {
+  APIJourney,
+  APIJourneyCallback,
+  APIJourneyOptions,
+  APIJourneyWithAnnotations,
   Journey,
   JourneyCallback,
   JourneyOptions,
@@ -60,6 +64,30 @@ export const journey = createJourney() as JourneyWithAnnotations;
 journey.skip = createJourney('skip');
 journey.only = createJourney('only');
 
+const createAPIJourney = (type?: 'skip' | 'only') =>
+  wrapFnWithLocation(
+    (
+      location: Location,
+      options: APIJourneyOptions | string,
+      callback: APIJourneyCallback
+    ) => {
+      log(`API Journey register: ${JSON.stringify(options)}`);
+      if (typeof options === 'string') {
+        options = { name: options, id: options };
+      }
+      const j = new APIJourney(options, callback, location);
+      if (type) {
+        j[type] = true;
+      }
+      runner._addJourney(j);
+      return j;
+    }
+  );
+
+export const apiJourney = createAPIJourney() as APIJourneyWithAnnotations;
+apiJourney.skip = createAPIJourney('skip');
+apiJourney.only = createAPIJourney('only');
+
 const createStep = (type?: 'skip' | 'soft' | 'only') =>
   wrapFnWithLocation(
     (location: Location, name: string, callback: VoidCallback) => {

package/src/core/runner.ts

@@ -25,7 +25,7 @@
 
 import { join } from 'path';
 import { mkdir, rm, writeFile } from 'fs/promises';
-import { Journey } from '../dsl/journey';
+import { Journey, JourneyCallbackOpts } from '../dsl/journey';
 import { Step } from '../dsl/step';
 import { reporters, Reporter } from '../reporters';
 import {
@@ -44,6 +44,7 @@ import {
   JourneyResult,
   StepResult,
   PushOptions,
+  APIDriver,
 } from '../common_types';
 import { PerformanceManager, filterBrowserMessages } from '../plugins';
 import { Gatherer } from './gatherer';
@@ -66,7 +67,7 @@ export interface RunnerInfo {
    */
   readonly currentJourney: Journey | undefined;
   /**
-   * All registerd journeys
+   * All registered journeys
    */
   readonly journeys: Journey[];
 }
@@ -78,7 +79,7 @@ export default class Runner implements RunnerInfo {
   #journeys: Journey[] = [];
   #hooks: SuiteHooks = { beforeAll: [], afterAll: [] };
   #screenshotPath = join(CACHE_PATH, 'screenshots');
-  #driver?: Driver;
+  #driver?: Driver | APIDriver;
   #browserDelay = -1;
   #hookError: Error | undefined;
   #monitor?: Monitor;
@@ -210,18 +211,22 @@ export default class Runner implements RunnerInfo {
   async #runStep(step: Step, options: RunOptions): Promise<StepResult> {
     log(`Runner: start step (${step.name})`);
     const { metrics, screenshots, filmstrips, trace } = options;
-    /**
-     * URL needs to be the first navigation request of any step
-     * Listening for request solves the case where `about:blank` would be
-     * reported for failed navigations
-     */
-    const captureUrl = req => {
-      if (!step.url && req.isNavigationRequest()) {
-        step.url = req.url();
-      }
-      this.#driver.context.off('request', captureUrl);
-    };
-    this.#driver.context.on('request', captureUrl);
+
+    if ('context' in this.#driver) {
+      /**
+       * URL needs to be the first navigation request of any step
+       * Listening for request solves the case where `about:blank` would be
+       * reported for failed navigations
+       */
+      const captureUrl = req => {
+        if (!step.url && req.isNavigationRequest()) {
+          step.url = req.url();
+        }
+        'context' in this.#driver &&
+          this.#driver.context.off('request', captureUrl);
+      };
+      this.#driver.context.on('request', captureUrl);
+    }
 
     const data: StepResult = {};
     const traceEnabled = trace || filmstrips;
@@ -240,30 +245,32 @@ export default class Runner implements RunnerInfo {
       step.status = 'failed';
       step.error = error;
     } finally {
-      /**
-       * Collect all step level metrics and trace events
-       */
-      if (metrics) {
-        data.pagemetrics = await (
-          Gatherer.pluginManager.get('performance') as PerformanceManager
-        ).getMetrics();
-      }
-      if (traceEnabled) {
-        const traceOutput = await Gatherer.pluginManager.stop('trace');
-        Object.assign(data, traceOutput);
-      }
-      /**
-       * Capture screenshot for the newly created pages
-       * via popup or new windows/tabs
-       *
-       * Last open page will get us the correct screenshot
-       */
-      const pages = this.#driver.context.pages();
-      const page = pages[pages.length - 1];
-      if (page) {
-        step.url ??= page.url();
-        if (screenshots && screenshots !== 'off') {
-          await this.captureScreenshot(page, step);
+      if ('context' in this.#driver) {
+        /**
+         * Collect all step level metrics and trace events
+         */
+        if (metrics) {
+          data.pagemetrics = await (
+            Gatherer.pluginManager.get('performance') as PerformanceManager
+          ).getMetrics();
+        }
+        if (traceEnabled) {
+          const traceOutput = await Gatherer.pluginManager.stop('trace');
+          Object.assign(data, traceOutput);
+        }
+        /**
+         * Capture screenshot for the newly created pages
+         * via popup or new windows/tabs
+         *
+         * Last open page will get us the correct screenshot
+         */
+        const pages = this.#driver.context.pages();
+        const page = pages[pages.length - 1];
+        if (page) {
+          step.url ??= page.url();
+          if (screenshots && screenshots !== 'off') {
+            await this.captureScreenshot(page, step);
+          }
         }
       }
     }
@@ -310,22 +317,24 @@ export default class Runner implements RunnerInfo {
 
   async #startJourney(journey: Journey, options: RunOptions) {
     journey._startTime = monotonicTimeInSeconds();
-    this.#driver = await Gatherer.setupDriver(options);
+    this.#driver = await Gatherer.setupDriver(options, journey.type);
     await Gatherer.beginRecording(this.#driver, options);
-    /**
-     * For each journey we create the screenshots folder for
-     * caching all screenshots and clear them at end of each journey
-     */
-    await mkdir(this.#screenshotPath, { recursive: true });
+    if (journey.type === 'browser') {
+      /**
+       * For each journey we create the screenshots folder for
+       * caching all screenshots and clear them at end of each journey
+       */
+      await mkdir(this.#screenshotPath, { recursive: true });
+    }
     const params = options.params;
     this.#reporter?.onJourneyStart?.(journey, {
       timestamp: getTimestamp(),
       params,
     });
     /**
-     * Exeucute the journey callback which registers the steps for current journey
+     * Execute the journey callback which registers the steps for current journey
      */
-    journey.cb({ ...this.#driver, params, info: this });
+    journey.cb({ ...this.#driver, params, info: this } as JourneyCallbackOpts);
   }
 
   async #endJourney(
@@ -335,24 +344,34 @@ export default class Runner implements RunnerInfo {
   ) {
     // Enhance the journey results
     const pOutput = await Gatherer.pluginManager.output();
-    const bConsole = filterBrowserMessages(
-      pOutput.browserconsole,
-      journey.status
-    );
-    await this.#reporter?.onJourneyEnd?.(journey, {
-      browserDelay: this.#browserDelay,
-      timestamp: getTimestamp(),
-      options,
-      networkinfo: pOutput.networkinfo,
-      browserconsole: bConsole,
-    });
+    const isBrowserJourney = journey.type === 'browser';
+    const bConsole = isBrowserJourney
+      ? filterBrowserMessages(pOutput.browserconsole, journey.status)
+      : undefined;
+    if (isBrowserJourney) {
+      await this.#reporter?.onJourneyEnd?.(journey, {
+        browserDelay: this.#browserDelay,
+        timestamp: getTimestamp(),
+        options,
+        networkinfo: pOutput.networkinfo,
+        browserconsole: bConsole,
+      });
+    } else {
+      await this.#reporter?.onJourneyEnd?.(journey, {
+        timestamp: getTimestamp(),
+        options,
+        networkinfo: pOutput.networkinfo,
+      });
+    }
     await Gatherer.endRecording();
     await Gatherer.dispose(this.#driver);
     // clear screenshots cache after each journey
-    await rm(this.#screenshotPath, { recursive: true, force: true });
+    if (isBrowserJourney) {
+      await rm(this.#screenshotPath, { recursive: true, force: true });
+    }
     return Object.assign(result, {
       networkinfo: pOutput.networkinfo,
-      browserconsole: bConsole,
+      ...(isBrowserJourney ? { browserconsole: bConsole } : {}),
       ...journey,
     });
   }
@@ -438,6 +457,7 @@ export default class Runner implements RunnerInfo {
       privateLocations: options.privateLocations,
       params: options.params,
       playwrightOptions: options.playwrightOptions,
+      certificateErrorSpkiAllowlist: options.certificateErrorSpkiAllowlist,
       screenshot: options.screenshots,
       tags: options.tags,
       alert: options.alert,
@@ -516,9 +536,9 @@ export default class Runner implements RunnerInfo {
     const { dryRun, grepOpts } = options;
 
     // collect all journeys with `.only` annotation and skip the rest
-    const onlyJournerys = this.#journeys.filter(j => j.only);
-    if (onlyJournerys.length > 0) {
-      this.#journeys = onlyJournerys;
+    const onlyJourneys = this.#journeys.filter(j => j.only);
+    if (onlyJourneys.length > 0) {
+      this.#journeys = onlyJourneys;
     } else {
       // filter journeys based on tags and skip annotations
       this.#journeys = this.#journeys.filter(
@@ -551,9 +571,16 @@ export default class Runner implements RunnerInfo {
 
   async _runJourneys(options: RunOptions) {
     const result: RunResult = {};
-    const browserStart = monotonicTimeInSeconds();
-    await Gatherer.launchBrowser(options);
-    this.#browserDelay = monotonicTimeInSeconds() - browserStart;
+    /**
+     * Only spin up a Chromium browser if at least one browser journey is
+     * scheduled to run. Pure API-journey suites skip launch entirely.
+     */
+    const hasBrowserJourneys = this.#journeys.some(j => j.type === 'browser');
+    if (hasBrowserJourneys) {
+      const browserStart = monotonicTimeInSeconds();
+      await Gatherer.launchBrowser(options);
+      this.#browserDelay = monotonicTimeInSeconds() - browserStart;
+    }
 
     for (const journey of this.#journeys) {
       const journeyResult: JourneyResult = this.#hookError
@@ -578,7 +605,7 @@ export default class Runner implements RunnerInfo {
     this.#journeys = [];
     this.#active = false;
     /**
-     * Clear all cache data stored for post processing by
+     * Clear all cache data stored for post-processing by
      * the current synthetic agent run
      */
     await rm(CACHE_PATH, { recursive: true, force: true });