Vulnerability Testing

/**
 * Test a project for vulnerabilities
 * @param root - Path to project root directory
 * @param options - Test configuration options
 * @param callback - Optional callback function for results
 * @returns Promise resolving to test results
 */
function test(root: string, options?: TestOptions, callback?: Function): Promise<TestResult | TestResult[]>;

interface TestOptions {
  /** Organization ID for testing */
  org?: string;
  /** Specific manifest file to test */
  file?: string;
  /** Enable Docker container scanning */
  docker?: boolean;
  /** Enable Infrastructure as Code scanning */
  iac?: boolean;
  /** Enable source code analysis (SAST) */
  code?: boolean;
  /** Enable unmanaged C/C++ scanning */
  unmanaged?: boolean;
  /** Return results in JSON format */
  json?: boolean;
  /** Minimum severity threshold for reporting */
  severityThreshold?: 'low' | 'medium' | 'high' | 'critical';
  /** Control vulnerability path display */
  showVulnPaths?: 'none' | 'some' | 'all';
  /** Maximum number of vulnerability paths to show */
  maxVulnPaths?: number;
  /** Test all detected projects */
  allProjects?: boolean;
  /** Enable Yarn workspaces scanning */
  yarnWorkspaces?: boolean;
  /** Include development dependencies */
  dev?: boolean;
  /** Print dependency tree */
  'print-deps'?: boolean;
  /** Print dependency paths */
  'print-dep-paths'?: boolean;
  /** Skip dependency pruning for large projects */
  pruneRepeatedSubdependencies?: boolean;
  /** Exclude directories/files from scanning */
  exclude?: string;
  /** Project detection depth */
  detectionDepth?: number;
  /** Fail test execution on specific conditions */
  failOn?: 'all' | 'upgradable' | 'patchable';
  /** Target reference for Git projects */
  'target-reference'?: string;
  /** Remote repository URL */
  'remote-repo-url'?: string;
  /** Custom project name */
  'project-name'?: string;
  /** Policy file path */
  'policy-path'?: string;
  /** Ignore policy files */
  'ignore-policy'?: boolean;
  /** Trust policy files */
  'trust-policies'?: boolean;
  /** Enable experimental features */
  experimental?: boolean;
  /** Package manager override */
  packageManager?: SupportedPackageManagers;
}

interface TestResult {
  /** List of found vulnerabilities */
  vulnerabilities: Vulnerability[];
  /** Total number of dependencies analyzed */
  dependencyCount: number;
  /** License policy results */
  licensesPolicy?: LicensesPolicy;
  /** Detected package manager */
  packageManager: string;
  /** Target platform */
  platform: string;
  /** Project path */
  path: string;
  /** Project name */
  projectName: string;
  /** Human-readable summary */
  summary: string;
  /** Vulnerability summary counts */
  uniqueCount?: number;
  /** Dependency path information */
  dependencyPaths?: DependencyPath[];
  /** Remediation advice */
  remediation?: RemediationAdvice;
  /** Docker specific information */
  docker?: DockerMetadata;
  /** Display target file */
  displayTargetFile?: string;
  /** Found project type */
  foundProjectCount?: number;
}

interface Vulnerability {
  /** Unique vulnerability identifier */
  id: string;
  /** Vulnerability title */
  title: string;
  /** Detailed description */
  description: string;
  /** Severity level */
  severity: 'low' | 'medium' | 'high' | 'critical';
  /** Affected package name */
  packageName: string;
  /** Vulnerable package version */
  version: string;
  /** Versions that fix the vulnerability */
  fixedIn?: string[];
  /** Available patches */
  patches?: Patch[];
  /** Upgrade path to fix */
  upgradePath?: string[];
  /** When vulnerability was published */
  publicationTime?: string;
  /** When vulnerability was disclosed */
  disclosureTime?: string;
  /** CVE identifiers */
  identifiers?: Identifier[];
  /** CVSS score */
  cvssScore?: number;
  /** Vulnerability functions and methods */
  functions?: VulnFunction[];
  /** Dependency paths to vulnerability */
  from: string[];
  /** Exploit maturity */
  exploitMaturity?: 'mature' | 'proof-of-concept' | 'no-known-exploit';
  /** Language specific metadata */
  language?: string;
  /** Package manager specific data */
  packageManager?: string;
  /** Social trend score */
  socialTrendAlert?: boolean;
  /** Malicious package flag */
  malicious?: boolean;
}

interface RemediationAdvice {
  /** Unresolved vulnerabilities count */
  unresolved: number;
  /** Upgrade recommendations */
  upgrade: UpgradeRecommendation[];
  /** Patch recommendations */
  patch: PatchRecommendation[];
  /** Ignore recommendations */
  ignore: IgnoreRecommendation[];
  /** Pin recommendations for transitive dependencies */
  pin: PinRecommendation[];
}

const snyk = require('snyk');

// Basic vulnerability test
const result = await snyk.test('./my-project');
console.log(`Found ${result.vulnerabilities.length} vulnerabilities`);

// Test with options
const result = await snyk.test('./my-project', {
  org: 'my-org-id',
  severityThreshold: 'high',
  json: true,
  showVulnPaths: 'all'
});

// Test all projects in a monorepo
const results = await snyk.test('./monorepo', {
  allProjects: true,
  exclude: 'node_modules,dist'
});

// Test with callback pattern
snyk.test('./my-project', { json: true }, (error, result) => {
  if (error) {
    console.error('Test failed:', error);
  } else {
    console.log('Test completed:', result);
  }
});

# Basic usage
snyk test                                    # Test current directory
snyk test /path/to/project                   # Test specific path
snyk test --org=<org-id>                     # Test with organization

# Output options
snyk test --json                             # JSON output
snyk test --json-file-output=results.json   # Save JSON to file
snyk test --sarif                            # SARIF format output
snyk test --sarif-file-output=results.sarif # Save SARIF to file

# Filtering options
snyk test --severity-threshold=high          # Filter by severity
snyk test --fail-on=upgradable              # Fail conditions
snyk test --show-vulnerable-paths=all        # Show vulnerability paths

# Project options
snyk test --all-projects                     # Test all detected projects
snyk test --yarn-workspaces                  # Test Yarn workspaces
snyk test --file=package.json               # Test specific manifest
snyk test --exclude=node_modules,dist        # Exclude directories

# Scanning modes
snyk test --docker                           # Docker scanning mode
snyk test --iac                              # Infrastructure as Code mode
snyk test --code                             # Source code analysis mode
snyk test --unmanaged                        # Unmanaged (C/C++) mode

# Advanced options
snyk test --detection-depth=5                # Limit detection depth
snyk test --prune-repeated-subdependencies   # Prune large dependency trees
snyk test --print-deps                       # Print dependency information
snyk test --dev                              # Include dev dependencies

// Common error scenarios
try {
  const result = await snyk.test('./project');
} catch (error) {
  if (error.code === 'VULNS') {
    // Vulnerabilities found (expected behavior)
    console.log('Vulnerabilities detected:', error.message);
  } else if (error.code === 'NO_SUPPORTED_MANIFESTS') {
    // No supported manifest files found
    console.log('No supported package files found');
  } else if (error.code === 'MISSING_NODE_MODULES') {
    // Dependencies not installed
    console.log('Please run npm install first');
  } else {
    // Other errors
    console.error('Test failed:', error.message);
  }
}

// Automatic package manager detection based on manifest files
const manifestFiles = {
  'package.json': 'npm',
  'yarn.lock': 'yarn', 
  'pnpm-lock.yaml': 'pnpm',
  'pom.xml': 'maven',
  'build.gradle': 'gradle',
  'requirements.txt': 'pip',
  'Gemfile': 'rubygems',
  'composer.json': 'composer',
  'go.mod': 'gomodules',
  'project.json': 'nuget'
};

// Override detection
await snyk.test('./project', {
  packageManager: 'yarn'
});

interface Patch {
  /** Patch identifier */
  id: string;
  /** Patch file URLs */
  urls: string[];
  /** Applicable version range */
  version: string;
  /** Patch modification time */
  modificationTime: string;
  /** Patch comments */
  comments: string[];
}

interface Identifier {
  /** Identifier type (CVE, CWE, etc.) */
  type: string;
  /** Identifier value */
  value: string;
}

interface VulnFunction {
  /** Function/method name */
  functionId: FunctionId;
  /** Function version */
  version: string[];
}

interface FunctionId {
  /** Function class name */
  className?: string;
  /** Function name */
  functionName: string;
}

interface DependencyPath {
  /** Path from root to vulnerability */
  path: string[];
}

interface UpgradeRecommendation {
  /** Path to vulnerable dependency */
  path: string[];
  /** Current version */
  version: string;
  /** Recommended upgrade version */
  upgradeTo: string;
  /** Issues fixed by upgrade */
  issues: string[];
}

interface LicensesPolicy {
  /** License policy results */
  licenseViolations: LicenseViolation[];
  /** Total license issues */
  totalLicenseIssues: number;
}

interface DockerMetadata {
  /** Base image name */
  baseImage: string;
  /** Base image tag */
  baseImageTag: string;
  /** Platform architecture */
  platform: string;
}

interface PatchRecommendation {
  /** Patch identifier */
  id: string;
  /** Patch URLs */
  urls: string[];
  /** Patch version */
  version: string;
  /** Modification timestamp */
  modificationTime: string;
  /** Patch comments */
  comments: string[];
}

interface IgnoreRecommendation {
  /** Ignore rule ID */
  id: string;
  /** Ignore reason */
  reason: string;
  /** Expiration date */
  expires?: string;
  /** Ignore path pattern */
  path?: string;
}

interface PinRecommendation {
  /** Dependency to pin */
  name: string;
  /** Version to pin to */
  version: string;
  /** Pin reason */
  reason: string;
}

interface LicenseViolation {
  /** License name */
  license: string;
  /** Package name */
  packageName: string;
  /** Package version */
  version: string;
  /** Violation severity */
  severity: 'low' | 'medium' | 'high';
  /** Violation instructions */
  instructions: string;
}

interface Dependency {
  /** Package name */
  name: string;
  /** Package version */
  version: string;
  /** Dependencies of this package */
  dependencies?: Record<string, Dependency>;
}