Snyk Golang CLI Plugin

Common errors

• Error: Command failed: go mod graph

  cause The plugin couldn't execute `go mod graph` (or similar Go commands) successfully, likely due to a misconfigured Go environment, an invalid `go.mod` file, or missing Go installation.
  fix Ensure Go is correctly installed and accessible in your system's PATH. Verify that `go mod graph` runs without errors in your project directory. Check your `go.mod` for syntax errors or unresolvable modules.

• TypeError: Cannot read properties of undefined (reading 'dependencies')

  cause The `inspect` function returned an unexpected or incomplete result object, possibly due to a problem parsing the Go project's dependencies or an internal plugin error.
  fix Inspect the full `result` object returned by `inspect` to understand its structure. Ensure the project path and manifest file provided to `inspect` are correct. Enable debug logging for the plugin if available to get more detailed error information.

• Error: Cannot find module '@snyk/dep-graph'

  cause The internal dependency `@snyk/dep-graph` is missing, often due to an incomplete `npm install` or issues with module resolution.
  fix Run `npm install` or `yarn install` again in your project to ensure all dependencies are correctly installed. Clear your `node_modules` and package manager cache if the issue persists.

Warnings

• breaking The `inspect` function now generates PackageURLs (purl) by default. This changes the structure of the output object, adding a 'purl' field to package objects.
  Fix: If you do not wish to generate PackageURLs, you must explicitly disable this functionality by passing `{ configuration: { includePackageUrls: false } }` to the `inspect` function. Example: `inspect(cwd, 'go.mod', { configuration: { includePackageUrls: false } })`.
• gotcha This package is a plugin designed to be used with the Snyk CLI tool, not as a standalone application for direct vulnerability scanning. While it provides a programmatic API, its primary context is within the Snyk ecosystem.
  Fix: For end-user vulnerability scanning, ensure the Snyk CLI is installed globally (`npm install -g snyk`) and use it directly. This plugin is for integrating Snyk's Go dependency resolution into custom tools or the Snyk CLI itself.
• gotcha The plugin relies on Go's module system. Projects with complex `replace` directives in `go.mod` (especially those pointing to local paths) may lead to incorrect dependency graphs.
  Fix: Ensure your `go.mod` file and local `replace` directives are correctly configured and resolvable within the project context. Recent versions have improved handling, but edge cases may still exist. Verify the dependency graph output from the plugin.
• gotcha The package requires Node.js version 20 or higher. Running it with older Node.js versions will result in execution errors.
  Fix: Upgrade your Node.js environment to version 20 or newer. Use `nvm` or a similar tool to manage Node.js versions if you need to switch between different versions.

Install

• npm install snyk-go-plugin npm
• yarn add snyk-go-plugin yarn
• pnpm add snyk-go-plugin pnpm

Imports

• inspect
  wrong:

  const inspect = require('snyk-go-plugin').inspect;

  correct:

  import { inspect } from 'snyk-go-plugin';

  The `inspect` function is the primary API for programmatically scanning Go projects. The package ships with TypeScript types.
• InspectOptions

  import type { InspectOptions } from 'snyk-go-plugin';

  Type import for configuration options when calling the `inspect` function. Essential for TypeScript users.

Quickstart

This quickstart demonstrates how to use the `inspect` function to programmatically scan a Go project's dependencies and output the results, including how to configure options like PackageURL generation.

import { inspect } from 'snyk-go-plugin';
import * as path from 'path';

async function scanGoProject(projectDir: string) {
  try {
    console.log(`Scanning Go project in: ${projectDir}`);
    // The 'go.mod' file is often used as the manifest file, or Gopkg.lock/vendor/vendor.json
    const result = await inspect(
      projectDir,
      'go.mod',
      { 
        // Optionally disable PackageURL generation if not needed
        configuration: { includePackageUrls: true },
        // Other options can be passed here, e.g., debug: true
      }
    );
    console.log('Snyk Go Plugin inspection result:');
    console.dir(result, { depth: null });
    if (result.package.dependencies) {
        console.log(`Found ${Object.keys(result.package.dependencies).length} direct dependencies.`);
    }
  } catch (error) {
    console.error('Error during Snyk Go Plugin inspection:', error);
    process.exit(1);
  }
}

// Example usage: scan the current directory as a Go project
scanGoProject(process.cwd());