Node.js SDK

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

Watches a specified directory recursively for file changes
Automatically excludes common non-code files (node_modules, .git, .md, .DS_Store, .lock files)
Tracks whether files are new or modified
Sends changed files to the backend for incremental scanning
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: "user@example.com"
});

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: "user@example.com"
});

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);
});

Getting Started

Core Features

Integration

Resources

Overview

Installation

Setup and Configuration

Prerequisites

Basic Setup

Custom API Base URL

Security Assistant

How It Works

Basic Usage

Retrieving Security Assistant Results

Stopping Security Assistant

Commit Scanning

Basic Commit Scan

Repository Scanning

Basic Repository Scan

Incremental Scanning

Using Security Assistant for Incremental Scanning

Retrieving Scan Results

Get Completed Scan by Job ID

Get Latest Cached Commit Scan

Event Handling

Event Types

Update Event

Completed Event

Error Event

​Overview

​Installation

​Setup and Configuration

​Prerequisites

​Basic Setup

​Custom API Base URL

​Security Assistant

​How It Works

​Basic Usage

​Retrieving Security Assistant Results

​Stopping Security Assistant

​Commit Scanning

​Basic Commit Scan

​Repository Scanning

​Basic Repository Scan

​Incremental Scanning

​Using Security Assistant for Incremental Scanning

​Retrieving Scan Results

​Get Completed Scan by Job ID

​Get Latest Cached Commit Scan

​Event Handling

​Event Types

​Update Event

​Completed Event

​Error Event

Overview

Installation

Setup and Configuration

Prerequisites

Basic Setup

Custom API Base URL

Security Assistant

How It Works

Basic Usage

Retrieving Security Assistant Results

Stopping Security Assistant

Commit Scanning

Basic Commit Scan

Repository Scanning

Basic Repository Scan

Incremental Scanning

Using Security Assistant for Incremental Scanning

Retrieving Scan Results

Get Completed Scan by Job ID

Get Latest Cached Commit Scan

Event Handling

Event Types

Update Event

Completed Event

Error Event