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

# How It Works

> Understanding VulnZap's Faraday multi-agent architecture

## Overview

VulnZap's **Faraday engine** represents a paradigm shift from rule-based scanning to intelligent, context-aware security analysis. Instead of rigid AST traversal, Faraday deploys specialized AI agents that collaborate like a human security team.

## Faraday: Multi-Agent Architecture

Faraday coordinates a team of specialized agents, each with distinct expertise:

<Steps>
  <Step title="Vulnerability Scanner Agent">
    **Deep code analysis across multiple layers**

    * Intra-file analysis: Single-file vulnerability detection
    * Inter-file analysis: Cross-file data flow tracking
    * Architectural analysis: System-wide security patterns
    * Hybrid approach: Traditional taint analysis + AI semantic reasoning
  </Step>

  <Step title="Context Validator Agent">
    **The game-changer—eliminates false positives**

    * Uses file system tools (grep, readFile, find) to cross-reference findings
    * Verifies vulnerabilities against actual code evidence
    * Understands sanitization, validation, and protection layers
    * Eliminates 90%+ of false positives through real-world context understanding
  </Step>

  <Step title="Scoring Agent">
    **Risk assessment and prioritization**

    * Assigns CVSS scores based on real exploitability
    * Calculates attack vectors and complexity
    * Considers authentication requirements
    * Evaluates business impact context
  </Step>

  <Step title="Remediation Agent">
    **Automated vulnerability fixing**

    * Generates production-ready patches with precise line boundaries
    * Understands code style and project conventions
    * Creates minimal, surgical fixes
    * Provides detailed fix explanations
  </Step>
</Steps>

<Info>
  All agents coordinate through Redis-backed memory, enabling parallel processing and intelligent task delegation.
</Info>

## MCP Tools for AI Agents

VulnZap provides 7 MCP tools that enable AI agents to perform vulnerability scanning during development:

### 1. vulnzap.scan\_diff

Fast, incremental, non-blocking scan on git diff:

```bash theme={null}
# Fire-and-forget: call and continue coding
vulnzap.scan_diff({ repo: ".", since: "HEAD" })
```

**Returns:**

* `scan_id` for polling
* ETA and file count
* Runs in background

### 2. vulnzap.status

Poll for scan results:

```bash theme={null}
# Check scan progress
vulnzap.status({ scan_id: "vz_91f..." })
# or
vulnzap.status({ latest: true })
```

**Returns:**

* `ready: true` when complete
* List of vulnerabilities found
* Severity counts

### 3. vulnzap.full\_scan

Baseline scan for entire repository:

```bash theme={null}
# Deep scan before push/deploy
vulnzap.full_scan({ repo: ".", mode: "baseline" })
```

**Takes:** 5-7 minutes average\
**Use:** Before serious push or deploy

### 4. vulnzap.report

Human-readable markdown report:

```bash theme={null}
# Generate report for PRs
vulnzap.report({ scan_id: "vz_91f...", format: "md" })
```

**Returns:** Markdown summary for PR descriptions

### 5. vulnzap.security\_assistant

Start file watcher for incremental security analysis:

```bash theme={null}
# Monitor directory
vulnzap.security_assistant({ path: "./src" })
```

**Returns:** Session ID for retrieving results

### 6. vulnzap.security\_assistant\_results

Retrieve results from active security assistant session:

```bash theme={null}
# Get findings
vulnzap.security_assistant_results({ session: "session_id" })
```

**Returns:** List of findings and scanned files

### 7. vulnzap.security\_assistant\_stop

Terminate security assistant session:

```bash theme={null}
# Stop session
vulnzap.security_assistant_stop({ session: "session_id" })
```

**Returns:** Final scan results

## Agent Workflow

Recommended workflow for AI coding agents:

<Steps>
  <Step title="Startup Check">
    Call `vulnzap.status({ latest: true })` to check for existing issues
  </Step>

  <Step title="While Coding">
    At checkpoints, call `vulnzap.scan_diff` and continue coding
  </Step>

  <Step title="Poll Status">
    Periodically call `vulnzap.status` with scan\_id
  </Step>

  <Step title="Fix Issues">
    If issues found, fix them and call `vulnzap.scan_diff` again
  </Step>

  <Step title="Before Push">
    Call `vulnzap.full_scan` once, poll until complete
  </Step>

  <Step title="Generate Report">
    Call `vulnzap.report` to attach to PRs
  </Step>
</Steps>

<Info>
  Scans are non-blocking. Agents can continue coding while scans run in the background.
</Info>

## How Faraday Works

Each agent leverages advanced language models to:

* **Understand code intent** beyond syntax
* **Reason about business logic** and security implications
* **Detect novel patterns** that rule-based scanners miss
* **Provide context-aware recommendations**

### Multi-Layer Analysis

**Example: SQL Injection Detection**

```javascript theme={null}
// Traditional scanner: Flags as vulnerability (may be false positive)
// Faraday: Multi-agent verification

const userId = req.params.id;
const query = `SELECT * FROM users WHERE id = ${userId}`;
db.execute(query);
```

**Vulnerability Scanner Agent:**

* Detects SQL injection pattern
* Identifies source: `req.params.id` (user-controlled)
* Identifies sink: `db.execute()` (SQL execution)

**Context Validator Agent:**

* Uses `grep` to find input validation
* Checks for ORM usage
* Verifies if parameterization exists elsewhere
* Confirms: Real vulnerability (no protections found)

**Scoring Agent:**

* User-reachable: Yes
* Authentication required: No
* Impact: High (data exfiltration)
* **Score: CRITICAL**

**Remediation Agent:**

* Generates fix:

```javascript theme={null}
const userId = req.params.id;
const query = 'SELECT * FROM users WHERE id = ?';
db.execute(query, [userId]); // ✅ Secure
```

### Multi-File Vulnerability Detection

Faraday traces data flow across file boundaries:

```javascript theme={null}
// auth.js
export function getToken(req) {
  return req.headers.authorization; // Source
}

// middleware.js  
import { getToken } from './auth.js';
export function validateUser(req) {
  const token = getToken(req); // Flow
  return jwt.verify(token, secret); // Sink - but safe
}

// Faraday understands the complete flow and validates safety
```

Traditional scanners analyze files in isolation. Faraday's agents understand cross-file relationships.

## Exploitability Ranking

Not all vulnerabilities are equal. VulnZap ranks by real-world risk:

### Critical (9.0-10.0)

* User-controlled input reaches dangerous sink
* No existing mitigations
* High impact (RCE, data exfiltration)
* Publicly accessible code path

### High (7.0-8.9)

* Partial user control or mitigations
* Significant impact
* Reachable from authenticated paths

### Medium (4.0-6.9)

* Limited user control
* Moderate impact
* Some mitigations in place

### Low (0.1-3.9)

* Minimal user control
* Low impact
* Multiple mitigations
* Theoretical exploitation

<Tip>
  Use `--min-severity high` to focus on critical issues first: `vulnzap scan --min-severity high`
</Tip>

## Patch Generation

VulnZap generates context-aware patches that preserve your code style:

### Style Preservation

**Original:**

```javascript theme={null}
const result=db.query(`SELECT * FROM users WHERE id=${id}`)
```

**VulnZap patch:**

```javascript theme={null}
const result=db.query('SELECT * FROM users WHERE id=?',[id])
```

Notice: No reformatting, preserves spacing/style.

### Framework-Aware Fixes

Different frameworks require different approaches:

<Tabs>
  <Tab title="Express.js">
    ```javascript theme={null}
    // Before
    res.send(userInput);

    // After (HTML context)
    res.send(escapeHtml(userInput));
    ```
  </Tab>

  <Tab title="Django">
    ```python theme={null}
    # Before
    return HttpResponse(user_input)

    # After
    from django.utils.html import escape
    return HttpResponse(escape(user_input))
    ```
  </Tab>

  <Tab title="Flask">
    ```python theme={null}
    # Before
    return f"<h1>{user_input}</h1>"

    # After
    from markupsafe import escape
    return f"<h1>{escape(user_input)}</h1>"
    ```
  </Tab>
</Tabs>

### Test Compatibility

VulnZap ensures patches don't break existing tests:

```javascript theme={null}
// Original function
function getUser(id) {
  return db.query(`SELECT * FROM users WHERE id=${id}`);
}

// Tests expect same return type
test('getUser returns user object', () => {
  const user = getUser(1);
  expect(user).toHaveProperty('id');
});

// VulnZap patch maintains compatibility
function getUser(id) {
  return db.query('SELECT * FROM users WHERE id=?', [id]);
  // Same return type, tests still pass ✅
}
```

## Performance & Results

### Scan Performance

| Metric                      | Faraday           | Traditional Scanners |
| --------------------------- | ----------------- | -------------------- |
| **Full repo scan**          | 5-7 minutes avg   | 30-120 minutes       |
| **False positive rate**     | \<5%              | 20-40%               |
| **Novel pattern detection** | ✅ Yes             | ❌ No                 |
| **Automated remediation**   | ✅ Working patches | ⚠️ Suggestions only  |
| **Multi-file analysis**     | ✅ Complete flow   | ⚠️ Limited           |

### Real-World Impact

**Traditional Scanner:**

```
Scan complete: 1,247 findings
├─ 892 false positives (71%)
├─ 312 low severity (25%)
└─ 43 actionable (4%)
Developer time: 8 hours triaging
```

**Faraday:**

```
Scan complete: 67 findings
├─ 3 false positives (4%)
├─ 52 with automated patches (78%)
└─ 67 actionable (100%)
Developer time: 45 minutes reviewing + applying fixes
```

<Info>
  Faraday's Context Validator Agent eliminates 90%+ of false positives by verifying findings against actual code evidence.
</Info>

## Privacy & Security

### Zero Data Retention

By default, VulnZap never stores your source code:

1. Code is analyzed in-memory
2. Only metadata is stored (file paths, line numbers, vulnerability types)
3. Analysis artifacts are immediately discarded
4. Optional: Enable code snippets for dashboard context

### Deployment Options

<CardGroup cols={3}>
  <Card title="Cloud" icon="cloud">
    Fully managed, no infrastructure required
  </Card>

  <Card title="VPC" icon="server">
    Deploy in your own AWS/GCP/Azure VPC
  </Card>

  <Card title="On-Premises" icon="building">
    Complete air-gapped deployment
  </Card>
</CardGroup>

See [Deployment Options](/team/deployment-options) for details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Security Coverage" icon="shield" href="/features/security-coverage">
    Learn what vulnerabilities VulnZap detects
  </Card>

  <Card title="Dashboard Guide" icon="chart-line" href="/features/dashboard">
    Explore dashboard features and workflows
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/integration/cli">
    Master command-line options
  </Card>

  <Card title="API Documentation" icon="code" href="/api-reference/introduction">
    Integrate programmatically
  </Card>
</CardGroup>