vulncheck-sdk

🛡️ VulnCheck SDK

The definitive TypeScript/JavaScript SDK for the VulnCheck API

Comprehensive vulnerability intelligence at your fingertips
Access enriched CVE data, threat intelligence, and security tooling with full TypeScript support and production-ready error handling.

🚀 Quick Start

# Install the SDK
npm install vulncheck-sdk

# Or with yarn
yarn add vulncheck-sdk

import { VulnCheckClient } from 'vulncheck-sdk';

// Initialize the client
const client = new VulnCheckClient({
  apiKey: process.env.VULNCHECK_API_KEY,
  timeout: 30000,
  cache: true
});

// Get CVE details
const cve = await client.getCVE('CVE-2021-44228');
console.log(`${cve.id}: ${cve.descriptions[0].value}`);

// Search for Apache vulnerabilities
const apacheVulns = await client.getCVEsByCPE('cpe:2.3:a:apache:http_server:*');
console.log(`Found ${apacheVulns.data.length} Apache vulnerabilities`);

// Check npm package vulnerabilities
const npmVulns = await client.getCVEsByPURL('pkg:npm/lodash@4.17.20');
console.log(`Found ${npmVulns.data.cves.length} CVEs in lodash@4.17.20`);

📋 Table of Contents

• Features
• Installation
• Authentication
• API Coverage
• Usage Examples
• Advanced Features
• Error Handling
• Testing
• TypeScript Support
• Contributing
• License

✨ Features

🔧 Production Ready

• Full TypeScript support with comprehensive type definitions
• ESM & CommonJS compatible for maximum compatibility
• Comprehensive error handling with specific error types
• Automatic retries with exponential backoff for resilience
• Rate limiting protection with built-in retry logic

🎯 Complete API Coverage

• CVE Data Retrieval - Get enriched vulnerability details
• CPE & PURL Lookups - Search by component identifiers
• Index Management - Access vulnerability databases
• Backup & Bulk Data - Download complete datasets
• Threat Intelligence - Security rules and IP/DNS intel
• Utility Endpoints - OpenAPI specs and metadata

🛡️ Developer Experience

• Zero-config setup with intelligent defaults
• Comprehensive validation for all inputs
• Detailed error messages with actionable information
• Cursor-based pagination for efficient data access
• 100% test coverage with integration tests

📦 Installation

# Using npm
npm install vulncheck-sdk

# Using yarn
yarn add vulncheck-sdk

# Using pnpm
pnpm add vulncheck-sdk

Requirements

• Node.js 16+ or modern browser
• Deno 1.0+ (full ES module support)
• VulnCheck API key (get yours here)

Deno Support

This SDK is fully compatible with Deno runtime. Import directly from npm:

import { VulnCheckClient } from "npm:vulncheck-sdk@^0.1.3";

const client = new VulnCheckClient({
  apiKey: Deno.env.get("VULNCHECK_API_KEY")!
});

// Works exactly the same as Node.js
const cve = await client.getCVE('CVE-2021-44228');

🔐 Authentication

Environment Variables (Recommended)

# .env file
VULNCHECK_API_KEY=your_api_key_here
VULNCHECK_BASE_URL=https://api.vulncheck.com  # optional

import { VulnCheckClient } from 'vulncheck-sdk';

const client = new VulnCheckClient({
  apiKey: process.env.VULNCHECK_API_KEY!
});

Direct Configuration

const client = new VulnCheckClient({
  apiKey: 'your-api-key-here',
  baseURL: 'https://api.vulncheck.com', // optional
  timeout: 30000,                       // optional
  retryAttempts: 3,                     // optional
  cache: true                           // optional
});

🎯 API Coverage

CVE Data Retrieval

// Get specific CVE details
const cve = await client.getCVE('CVE-2021-44228');

// Get CVEs from specific index
const cves = await client.getCVEsFromIndex('vulncheck-nvd2', { limit: 100 });

CPE & PURL Lookups

// Find CVEs by CPE
const cpeResults = await client.getCVEsByCPE('cpe:2.3:a:apache:*');

// Find CVEs by Package URL
const purlResults = await client.getCVEsByPURL('pkg:npm/lodash@4.17.20');

// Search CPEs by criteria
const cpeSearch = await client.searchCPEs({ 
  vendor: 'apache', 
  product: 'http_server' 
});

Index Management

// List available indexes
const indexes = await client.getIndexes();

// Query specific index
const indexData = await client.queryIndex('adobe', { limit: 50 });

Backup & Bulk Data

// List available backups
const backups = await client.getBackups();

// Download backup data
const backupData = await client.downloadBackup('vulncheck-nvd2');

Threat Intelligence

// Get security rules
const rules = await client.getInitialAccessRules('malware');

// Get IP intelligence
const ipIntel = await client.getIPsByTags('malicious');

// Get DNS intelligence
const dnsIntel = await client.getDNSByTags('phishing');

Utility Endpoints

// Get OpenAPI specification
const apiSpec = await client.getOpenAPISpec();

💡 Usage Examples

Security Monitoring Dashboard

import { VulnCheckClient } from 'vulncheck-sdk';

class SecurityMonitor {
  private client: VulnCheckClient;

  constructor(apiKey: string) {
    this.client = new VulnCheckClient({ apiKey });
  }

  async checkPackageVulnerabilities(packageUrl: string) {
    try {
      const result = await this.client.getCVEsByPURL(packageUrl);
      
      return {
        package: packageUrl,
        vulnerabilities: result.data.cves.length,
        fixedIn: result.data.vulnerabilities.map(v => v.fixed_version),
        riskLevel: this.calculateRiskLevel(result.data.cves.length)
      };
    } catch (error) {
      console.error(`Error checking ${packageUrl}:`, error.message);
      return null;
    }
  }

  private calculateRiskLevel(vulnCount: number): 'low' | 'medium' | 'high' {
    if (vulnCount === 0) return 'low';
    if (vulnCount <= 2) return 'medium';
    return 'high';
  }
}

// Usage
const monitor = new SecurityMonitor(process.env.VULNCHECK_API_KEY!);
const result = await monitor.checkPackageVulnerabilities('pkg:npm/express@4.17.1');

Vulnerability Intelligence Pipeline

import { VulnCheckClient, CVEDetails } from 'vulncheck-sdk';

class VulnIntelligence {
  private client: VulnCheckClient;

  constructor(apiKey: string) {
    this.client = new VulnCheckClient({ apiKey });
  }

  async getHighSeverityVulns(limit: number = 100): Promise<CVEDetails[]> {
    const results = await this.client.getCVEsFromIndex('vulncheck-kev', { limit });
    
    return results.data.filter(cve => {
      // Filter for high severity vulnerabilities
      return cve.cisaExploitAdd || cve.vulncheckKEVExploitAdd;
    });
  }

  async enrichCVEData(cveId: string) {
    const cve = await this.client.getCVE(cveId);
    
    return {
      id: cve.id,
      description: cve.descriptions[0]?.value || 'No description',
      severity: cve.cisaVulnerabilityName ? 'CRITICAL' : 'HIGH',
      published: new Date(cve.published),
      exploitAvailable: !!cve.cisaExploitAdd,
      references: cve.references.map(ref => ref.url)
    };
  }
}

Automated Compliance Checking

import { VulnCheckClient } from 'vulncheck-sdk';

class ComplianceChecker {
  private client: VulnCheckClient;

  constructor(apiKey: string) {
    this.client = new VulnCheckClient({ apiKey });
  }

  async auditInfrastructure(components: string[]) {
    const results = await Promise.all(
      components.map(async (component) => {
        try {
          const vulns = await this.client.getCVEsByCPE(component);
          return {
            component,
            vulnerabilities: vulns.data.length,
            compliant: vulns.data.length === 0
          };
        } catch (error) {
          return {
            component,
            vulnerabilities: -1,
            compliant: false,
            error: error.message
          };
        }
      })
    );

    return {
      totalComponents: components.length,
      compliantComponents: results.filter(r => r.compliant).length,
      totalVulnerabilities: results.reduce((sum, r) => sum + Math.max(0, r.vulnerabilities), 0),
      results
    };
  }
}

🚀 Advanced Features

Pagination with Cursors

// Paginate through large datasets
let cursor: string | undefined;
const allResults = [];

do {
  const page = await client.getCVEsByCPE('cpe:2.3:a:apache:*', { 
    limit: 100, 
    cursor 
  });
  
  allResults.push(...page.data);
  cursor = page._meta.next_cursor;
} while (cursor);

console.log(`Retrieved ${allResults.length} total vulnerabilities`);

Error Handling with Retries

import { 
  VulnCheckClient, 
  VulnCheckRateLimitError,
  VulnCheckAuthError 
} from 'vulncheck-sdk';

const client = new VulnCheckClient({
  apiKey: process.env.VULNCHECK_API_KEY!,
  retryAttempts: 5,  // Retry up to 5 times
  timeout: 60000     // 60 second timeout
});

try {
  const cve = await client.getCVE('CVE-2021-44228');
  console.log('Success:', cve.id);
} catch (error) {
  if (error instanceof VulnCheckRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
  } else if (error instanceof VulnCheckAuthError) {
    console.error('Authentication failed. Check your API key.');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Batch Operations

// Process multiple CVEs efficiently
const cveIds = ['CVE-2021-44228', 'CVE-2021-45046', 'CVE-2021-45105'];

const results = await Promise.allSettled(
  cveIds.map(id => client.getCVE(id))
);

results.forEach((result, index) => {
  if (result.status === 'fulfilled') {
    console.log(`${cveIds[index]}: ${result.value.descriptions[0]?.value}`);
  } else {
    console.error(`${cveIds[index]}: ${result.reason.message}`);
  }
});

🚨 Error Handling

The SDK provides comprehensive error handling with specific error types:

Error Types

import {
  VulnCheckError,           // Base error class
  VulnCheckAuthError,       // 401 authentication errors
  VulnCheckRateLimitError,  // 429 rate limiting errors
  VulnCheckNotFoundError,   // 404 not found errors
  VulnCheckValidationError, // 400 validation errors
  VulnCheckServerError      // 5xx server errors
} from 'vulncheck-sdk';

Error Handling Patterns

try {
  const cve = await client.getCVE('CVE-2021-44228');
} catch (error) {
  if (error instanceof VulnCheckRateLimitError) {
    // Handle rate limiting
    const retryAfter = error.retryAfter || 5000;
    await new Promise(resolve => setTimeout(resolve, retryAfter));
    // Retry the request
  } else if (error instanceof VulnCheckAuthError) {
    // Handle authentication error
    console.error('Check your API key');
  } else if (error instanceof VulnCheckValidationError) {
    // Handle validation error
    console.error('Invalid input:', error.message);
  } else {
    // Handle other errors
    console.error('Unexpected error:', error.message);
  }
}

🧪 Testing

Running Tests

# Unit tests
npm test

# Integration tests (requires API key)
npm run test:integration

# All tests
npm run test:all

# Watch mode
npm run test:watch

Setting up Integration Tests

# Create .env file
echo "VULNCHECK_API_KEY=your_api_key_here" > .env

# Run integration tests
npm run test:integration

Test Coverage

The SDK includes comprehensive test coverage:

• ✅ Unit tests for all client methods
• ✅ Integration tests against live API
• ✅ Error handling tests for all error scenarios
• ✅ Type validation tests for TypeScript compatibility
• ✅ Performance tests for rate limiting and timeouts

🔷 TypeScript Support

Full Type Safety

import { VulnCheckClient, CVEDetails, PURLResults } from 'vulncheck-sdk';

// All methods are fully typed
const client = new VulnCheckClient({ apiKey: 'key' });

// TypeScript knows the exact shape of responses
const cve: CVEDetails = await client.getCVE('CVE-2021-44228');
const purlResult: PURLResults = await client.getCVEsByPURL('pkg:npm/lodash@4.17.20');

// Intellisense works perfectly
console.log(cve.id);                    // ✅ TypeScript knows this exists
console.log(cve.descriptions[0].value); // ✅ Nested properties are typed
console.log(purlResult.data.cves);      // ✅ Array types are correct

Generic Types

// Generic response type for custom processing
import { VulnCheckResponse } from 'vulncheck-sdk';

type CustomData = {
  id: string;
  name: string;
};

// Type-safe custom endpoint handling
const customResponse: VulnCheckResponse<CustomData> = await client.queryIndex('custom-index');

🎨 Configuration Options

interface VulnCheckClientConfig {
  apiKey: string;           // Required: Your VulnCheck API key
  baseURL?: string;         // Optional: API base URL (default: https://api.vulncheck.com)
  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
  retryAttempts?: number;   // Optional: Max retry attempts (default: 3)
  cache?: boolean;          // Optional: Enable response caching (default: false)
}

📖 API Reference

Client Methods

Method	Description	Returns
getCVE(id)	Get CVE details by ID	Promise<CVEDetails>
getCVEsFromIndex(index, options?)	Get CVEs from specific index	Promise<CVESearchResults>
getCVEsByCPE(cpe, options?)	Find CVEs by CPE	Promise<CVESearchResults>
getCVEsByPURL(purl, options?)	Find CVEs by Package URL	Promise<PURLResults>
searchCPEs(criteria, options?)	Search CPEs by criteria	Promise<CPESearchResults>
getIndexes()	List available indexes	Promise<IndexList>
queryIndex(name, options?)	Query specific index	Promise<IndexResults>
getBackups()	List available backups	Promise<BackupList>
downloadBackup(name)	Download backup data	Promise<BackupData>
getInitialAccessRules(rules)	Get security rules	Promise<SecurityRules>
getIPsByTags(filter, options?)	Get IP intelligence	Promise<IPIntelligence>
getDNSByTags(filter, options?)	Get DNS intelligence	Promise<DNSIntelligence>
getOpenAPISpec()	Get OpenAPI specification	Promise<OpenAPIDocument>

Response Types

All responses follow the VulnCheck API format:

interface VulnCheckResponse<T> {
  _benchmark: number;
  _meta: {
    timestamp: string;
    index: string;
    limit: number;
    total_documents: number;
    sort: string;
    next_cursor?: string;
  };
  data: T[];
}

🌟 Examples Repository

Check out our examples repository for real-world usage patterns:

• 🔍 Security Scanning Tools
• 📊 Vulnerability Dashboards
• 🤖 Automated Compliance Checking
• 📈 Threat Intelligence Feeds
• 🔔 Alert Systems

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/vulncheck/vulncheck-sdk.git
cd vulncheck-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run integration tests (requires API key)
npm run test:integration

Development Commands

npm run build        # Build the project
npm run dev          # Watch mode development
npm run test         # Run unit tests
npm run test:all     # Run all tests
npm run lint         # Run linting
npm run typecheck    # Run TypeScript checks

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🆘 Support

• 📚 Documentation: API Documentation
• 💬 Community: Discord Server
• 🐛 Bug Reports: GitHub Issues
• 📧 Email Support: [e-mail]

🎯 Roadmap

• WebSocket Support for real-time updates
• CLI Tool for command-line usage
• Browser Optimization for frontend applications
• GraphQL Support for flexible queries
• Caching Layer for improved performance
• Plugin System for custom extensions

Made with ❤️ by hrbrmstr

🌐 Website • 📖 Docs • 💬 Discord • 🐦 Twitter