Skip to main content

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:

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:
Initialize the client in your code:

Custom API Base URL

If you are using a self-hosted VulnZap instance:

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

Retrieving Security Assistant Results

Stopping Security Assistant

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

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

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:

Retrieving Scan Results

Get Completed Scan by Job ID

Get Latest Cached Commit Scan

Event Handling

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

Event Types

Update Event

Emitted during scan progress with status updates.

Completed Event

Emitted when a scan finishes successfully.

Error Event

Emitted when errors occur during scanning or SSE connection.