> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulnzap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
export VULNZAP_API_KEY=your_api_key_here
```

Initialize the client in your code:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
const results = await client.getIncrementalScanResults(sessionId);

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

### Stopping Security Assistant

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

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