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

# zenveil explain

> Get a plain-language AI explanation of any security finding — what it is, why it matters, and how to fix it.

<Info>
  `zenveil explain` requires a **Pro** plan. Run `zenveil upgrade` to unlock it, or `zenveil whoami` to check your current plan.
</Info>

## Overview

`zenveil explain` uses Claude to generate a detailed, developer-friendly explanation of a specific finding. It streams the response to your terminal in real time.

## Usage

```bash theme={null}
zenveil explain <finding_id>
```

## Arguments

| Argument     | Description                        |
| ------------ | ---------------------------------- |
| `finding_id` | The finding ID (e.g., `ZV-A1B2C3`) |

## Examples

```bash theme={null}
# Explain a finding
zenveil explain ZV-A1B2C3
```

## Sample output

```
Explaining ZG-E5F6: Token stored in browser storage

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What this is:
Your application is storing an authentication token in localStorage at
src/auth/login.js:8. Specifically, the code reads:

  localStorage.setItem('auth_token', token);

Why it matters:
localStorage is accessible by any JavaScript running on the same
origin — including injected scripts from XSS vulnerabilities, browser
extensions, and third-party analytics scripts. If an attacker finds
even a minor XSS vulnerability anywhere on your site, they can steal
this token, impersonate your user indefinitely, and bypass logout.

This maps to OWASP A02:2021 (Cryptographic Failures) and A07:2021
(Identification and Authentication Failures). It's one of the most
commonly exploited patterns in modern web applications.

Real-world impact:
In 2022, a major SaaS platform suffered a breach because tokens stored
in localStorage were exfiltrated via a third-party script. The attacker
maintained persistent access to 40,000 accounts for 3 months.

The fix:
Use an httpOnly, Secure, SameSite=Strict cookie issued by your server:

Server-side (Node.js/Express):
  res.cookie('session', token, {
    httpOnly: true,   // Cannot be read by JavaScript
    secure: true,     // HTTPS only
    sameSite: 'Strict', // No cross-origin sending
    maxAge: 3600000,  // 1 hour
  });

Client-side:
  // Remove the localStorage.setItem call entirely
  // The cookie is managed automatically by the browser

If you must use client-side storage (e.g., for a SPA with no server),
use sessionStorage instead of localStorage (clears on tab close) and
implement XSS protection rigorously.

Confidence: 80% · OWASP: A02:2021, A07:2021
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## What the explanation includes

Every explanation covers:

* **What this is** — plain-language description of the vulnerability
* **Why it matters** — real-world impact and attack scenarios
* **OWASP mapping** — exact category and year
* **The fix** — specific code changes for your language/framework
* **Confidence score** — how certain ZenVeil is about this finding

## Prerequisites

* Run `zenveil scan` first to populate the finding cache
* A **Pro** plan (run `zenveil upgrade` to subscribe)