Node.js SDK

Complete guide to using the VulnZap JavaScript/TypeScript client library

Overview

The VulnZap client library allows you to integrate vulnerability scanning directly into your Node.js applications and tools.

Installation

Install the VulnZap client library using npm:

npm install @vulnzap/client

Setup and Configuration

Prerequisites

• Node.js 18 or higher
• VulnZap API key from your dashboard

Basic Setup

Set your API key as an environment variable:

export VULNZAP_API_KEY=your_api_key_here

Initialize the client in your code:

import { VulnzapClient } from "@vulnzap/client";

const client = new VulnzapClient({
  apiKey: process.env.VULNZAP_API_KEY!
});

Custom API Base URL

If you are using a self-hosted VulnZap instance:

const client = new VulnzapClient({
  apiKey: process.env.VULNZAP_API_KEY!,
  baseUrl: "https://custom.vulnzap.com"
});

Security Assistant

The Security Assistant is designed for AI coding agents and development environments that need real-time security feedback. It monitors a directory for file changes and automatically performs incremental vulnerability scans.

How It Works

1. Watches a specified directory recursively for file changes
2. Automatically excludes common non-code files (node_modules, .git, .md, .DS_Store, .lock files)
3. Tracks whether files are new or modified
4. Sends changed files to the backend for incremental scanning
5. Maintains session state with automatic timeout management

Basic Usage

import { VulnzapClient } from "@vulnzap/client";

const client = new VulnzapClient({
  apiKey: process.env.VULNZAP_API_KEY!
});

const sessionId = `session_${Date.now()}`;

const started = client.securityAssistant({
  dirPath: "./src",
  sessionId: sessionId,
  timeout: 60000
});

if (started) {
  console.log("Security assistant started successfully");
} else {
  console.log("Failed to start security assistant");
}

Retrieving Security Assistant Results

const results = await client.getIncrementalScanResults(sessionId);

if (results.success) {
  console.log("Scan findings:", results.data);
} else {
  console.error("Error:", results.error);
}

Stopping Security Assistant

const finalResults = await client.stopSecurityAssistant(sessionId);

if (finalResults.success) {
  console.log("Session stopped. Final results:", finalResults.data);
}

Commit Scanning

Scan individual commits for vulnerabilities. This is ideal for CI/CD pipelines and pre-commit hooks.

Results are delivered through event handlers (“update”, “completed”, “error”) or can be retrieved later using getCompletedCommitScan(jobId).

Basic Commit Scan

import { VulnzapClient } from "@vulnzap/client";

const client = new VulnzapClient({
  apiKey: process.env.VULNZAP_API_KEY!
});

client.on("update", (event) => {
  console.log("Progress:", event.message);
});

client.on("completed", (event) => {
  console.log("Scan completed:", event.data);
});

client.on("error", (event) => {
  console.error("Scan error:", event.message);
});

const response = await client.scanCommit({
  commitHash: "abc123def456",
  repository: "owner/repo",
  branch: "main",
  files: [
    {
      path: "src/app.js",
      content: "const express = require('express');\nconst app = express();"
    },
    {
      path: "src/utils.js",
      content: "module.exports = { helper: () => {} };"
    }
  ],
  userIdentifier: "[e-mail]"
});

console.log("Scan initiated:", response.data.jobId);

const jobId = response.data.jobId;
const results = await client.getCompletedCommitScan(jobId);
console.log("Scan results:", results);

Repository Scanning

Scan an entire repository for vulnerabilities. The backend will clone and analyze the repository.

Results are delivered through event handlers (“update”, “completed”, “error”) or can be retrieved later using getCompletedCommitScan(jobId).

Basic Repository Scan

import { VulnzapClient } from "@vulnzap/client";

const client = new VulnzapClient({
  apiKey: process.env.VULNZAP_API_KEY!
});

client.on("update", (event) => {
  console.log("Scan progress:", event.message);
});

client.on("completed", (event) => {
  console.log("Repository scan completed");
  console.log("Findings:", event.data);
});

const response = await client.scanRepository({
  repository: "owner/repo",
  branch: "main",
  userIdentifier: "[e-mail]"
});

console.log("Repository scan started:", response.data.jobId);

const jobId = response.data.jobId;
const results = await client.getCompletedCommitScan(jobId);
console.log("Scan results:", results);

Incremental Scanning

Incremental scanning is primarily used through the Security Assistant, which automatically monitors directories and scans changed files. However, you can also retrieve incremental scan results manually.

Using Security Assistant for Incremental Scanning

The recommended approach is to use the Security Assistant, which handles file watching and incremental scanning automatically:

import { VulnzapClient } from "@vulnzap/client";
import * as fs from "fs";
import * as path from "path";

const client = new VulnzapClient({
  apiKey: process.env.VULNZAP_API_KEY!,
});

const testDir = path.join(__dirname, "my_project");
const sessionId = "session_1";

if (!fs.existsSync(testDir)) {
  fs.mkdirSync(testDir);
}

console.log("Starting security assistant...");
const started = client.securityAssistant({
  sessionId: sessionId,
  dirPath: testDir,
  timeout: 60000
});

console.log("Watcher started:", started);

console.log("Creating a file...");
fs.writeFileSync(path.join(testDir, "test.js"), "console.log('hello world')");

await new Promise(resolve => setTimeout(resolve, 2000));

console.log("Fetching incremental results...");
const results = await client.getIncrementalScanResults(sessionId);
console.log("Incremental results:", results);

Retrieving Scan Results

Get Completed Scan by Job ID

const scanResults = await client.getCompletedCommitScan(jobId);

console.log("Job ID:", scanResults.jobId);
console.log("Status:", scanResults.status);
console.log("Progress:", scanResults.progress);
console.log("Results:", scanResults.results);
console.log("Started at:", new Date(scanResults.startedAt));
console.log("Completed at:", new Date(scanResults.completedAt));

Get Latest Cached Commit Scan

const cachedScan = await client.getLatestCachedCommitScan("owner/repo");

if (cachedScan) {
  console.log("Cached scan found");
  console.log("Job ID:", cachedScan.jobId);
  console.log("Timestamp:", new Date(cachedScan.timestamp));
  console.log("Status:", cachedScan.status);
  console.log("Resolved:", cachedScan.resolved);
  console.log("Results:", cachedScan.results);
} else {
  console.log("No cached scan found for this repository");
}

Event Handling

The VulnZap client emits three types of events during scanning operations.

Event Types

Update Event

Emitted during scan progress with status updates.

client.on("update", (event) => {
  console.log("Job ID:", event.jobId);
  console.log("Message:", event.message);
  console.log("Data:", event.data);
});

Completed Event

Emitted when a scan finishes successfully.

client.on("completed", (event) => {
  console.log("Scan completed for job:", event.jobId);
  console.log("Final results:", event.data);
});

Error Event

Emitted when errors occur during scanning or SSE connection.

client.on("error", (event) => {
  console.error("Error in job:", event.jobId);
  console.error("Error message:", event.message);
});