Snyk Delta CLI

Common errors

• Error: SNYK_TOKEN environment variable not set. Please set the SNYK_TOKEN environment variable.

  cause The required Snyk API token is missing from the environment variables, preventing authentication with the Snyk API.
  fix Set `SNYK_TOKEN` (e.g., `export SNYK_TOKEN="your_snyk_api_token"`) in your shell or CI/CD environment before executing `snyk-delta`.

• Error: Could not find project with ID <project-uuid> in organization <org-uuid>.

  cause The specified `--baselineProject` or `--baselineOrg` ID does not match an existing Snyk project or organization, or the `SNYK_TOKEN` lacks the necessary permissions to access them.
  fix Double-check the Snyk Organization and Project IDs for accuracy. Ensure the provided `SNYK_TOKEN` has the required read permissions for the specified resources.

• Error: Snyk Code comparison requires 'Code Consistent Ignores' feature enabled in your Snyk organization.

  cause The Snyk organization where the project resides does not have the 'Code Consistent Ignores' feature enabled, which is a prerequisite for accurate Snyk Code delta comparisons.
  fix Enable 'Code Consistent Ignores' in your Snyk Organization settings. Refer to Snyk documentation or contact Snyk support for assistance in enabling this feature.

• Error: Unsupported Snyk product type for delta comparison: IaC.

  cause The `snyk-delta` tool was executed with a Snyk Infrastructure as Code (IaC) project, a product type it explicitly does not support.
  fix Refrain from using `snyk-delta` for IaC projects. This tool's functionality is limited to Open Source, Container, and Code vulnerability types.

Warnings

• gotcha The `snyk-delta` repository is in maintenance mode. No new features are being developed; only bug and security fixes will be delivered. Contributions for small features are welcome, but breaking changes will not be accepted.
  Fix: Be aware that the tool's functionality will remain stable, but new capabilities aligning with future Snyk product developments may not be implemented directly within this tool.
• breaking Use of `snyk-delta` requires a Snyk Business or Enterprise account due to its reliance on Snyk API access for baseline comparisons. Free or Developer accounts are not supported.
  Fix: Ensure your Snyk account is at the Business or Enterprise tier. Refer to Snyk documentation for account plan details and feature parity.
• gotcha The `SNYK_TOKEN` environment variable must be set with a valid Snyk API token, preferably from a service account. Failure to do so will result in authentication errors during API calls.
  Fix: Set the `SNYK_TOKEN` environment variable in your environment (e.g., `export SNYK_TOKEN=your-token`) before running `snyk-delta`. Obtain a service account token for CI/CD environments for enhanced security and manageability.
• gotcha Snyk IaC (Infrastructure as Code) scanning is explicitly not supported by `snyk-delta`. Attempting to use it for IaC will result in an error or incorrect behavior.
  Fix: Do not use `snyk-delta` for Snyk IaC projects. This tool is specifically designed for Open Source, Container, and Code findings. Consider alternative methods for delta comparison of IaC findings if available within the Snyk platform.
• gotcha For Snyk Code comparison, the 'Code Consistent Ignores' feature must be enabled in your Snyk organization. Without this feature, the Code delta functionality may not work as expected or produce unreliable results.
  Fix: Verify and enable the 'Code Consistent Ignores' feature in your Snyk organization settings. Consult Snyk documentation for instructions on feature enablement and its impact on Snyk Code scans.

Install

• npm install snyk-delta npm
• yarn add snyk-delta yarn
• pnpm add snyk-delta pnpm

Imports

• run
  wrong:

  const run = require('snyk-delta').run;

  correct:

  import { run } from 'snyk-delta';

  Primarily for programmatic execution of the CLI's main logic, though `snyk-delta` is most commonly run directly as a command-line utility.
• getOssDelta
  wrong:

  import { ossDelta } from 'snyk-delta';

  correct:

  import { getOssDelta } from 'snyk-delta';

  Exports the core logic for comparing Open Source and Container vulnerability deltas. This function facilitates programmatic integration for custom analyses.
• getCodeDelta
  wrong:

  const codeDelta = require('snyk-delta').codeDelta;

  correct:

  import { getCodeDelta } from 'snyk-delta';

  Provides the programmatic interface for comparing Snyk Code SARIF outputs to identify new code analysis findings. Requires 'Code Consistent Ignores' feature.
• SnykDeltaOptions

  import type { SnykDeltaOptions } from 'snyk-delta';

  TypeScript type definition for the configuration options used by snyk-delta's core comparison functions, such as baseline organization and project details.

Quickstart

Demonstrates programmatic usage of `getCodeDelta` to compare two local SARIF files, illustrating how to identify new Snyk Code findings and exit with appropriate status codes based on the comparison result. Requires `SNYK_TOKEN` and `SNYK_ORG_ID`.

import { getCodeDelta } from 'snyk-delta';
import * as fs from 'fs';
import * as path from 'path';

const SNYK_TOKEN = process.env.SNYK_TOKEN ?? ''; // Ensure SNYK_TOKEN is set
const ORG_ID = process.env.SNYK_ORG_ID ?? 'YOUR_SNYK_ORG_ID'; // Replace with your Snyk Organization ID

async function compareSnykCodeResults() {
  if (!SNYK_TOKEN || ORG_ID === 'YOUR_SNYK_ORG_ID') {
    console.error('Error: Please set SNYK_TOKEN and SNYK_ORG_ID environment variables or replace placeholder.');
    process.exit(1);
  }

  // Create dummy SARIF files for demonstration if they don't exist
  const baselineSarifPath = path.join(__dirname, 'baseline.sarif.json');
  const currentSarifPath = path.join(__dirname, 'current.sarif.json');

  if (!fs.existsSync(baselineSarifPath)) {
    fs.writeFileSync(baselineSarifPath, JSON.stringify({"runs": []}, null, 2));
  }
  if (!fs.existsSync(currentSarifPath)) {
    // In a real scenario, this would be generated by `snyk code test --sarif > current.sarif.json`
    fs.writeFileSync(currentSarifPath, JSON.stringify({"runs": []}, null, 2));
  }

  try {
    const options = {
      baselineOrg: ORG_ID,
      // Optional: target a specific baseline project, otherwise `snyk-delta` attempts to find one
      // baselineProject: 'your-baseline-project-uuid', 
      // Optional: recommended for Code Analysis projects
      // projectName: 'owner/repo', 
      // targetReference: 'main', 
      // api: 'https://api.snyk.io/api/v1', // Snyk API endpoint, default value
    };

    console.log('Comparing Snyk Code results...');
    const deltaReport = await getCodeDelta(baselineSarifPath, currentSarifPath, options, SNYK_TOKEN);

    if (deltaReport.newFindings.length > 0) {
      console.log(`\nFound ${deltaReport.newFindings.length} new code findings:\n`);
      deltaReport.newFindings.forEach(finding => {
        const location = finding.locations[0]?.physicalLocation;
        const filePath = location?.artifactLocation?.uri || 'unknown file';
        const lineNumber = location?.region?.startLine || 'unknown line';
        console.log(`  - [${finding.ruleId}] ${finding.message.text} (${filePath}:${lineNumber})`);
      });
      process.exit(1); // Exit with 1 if new findings are present
    } else {
      console.log('\nNo new code findings introduced. Exiting with 0.');
      process.exit(0); // Exit with 0 if no new findings
    }
  } catch (error) {
    console.error('An error occurred during delta comparison:', error);
    process.exit(2); // Exit with 2 on error
  }
}

compareSnykCodeResults();