Metadata-Version: 2.4
Name: kaanan
Version: 0.3.0
Summary: AI-driven SAST, UAT documentation, and VAPT CLI tool
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12
Requires-Dist: python-dotenv>=1.0
Requires-Dist: litellm>=1.83.0
Requires-Dist: rich>=13.0
Requires-Dist: fpdf2>=2.7
Requires-Dist: httpx>=0.27
Dynamic: license-file

# Kaanan — AI-Driven SAST, UAT Documentation & VAPT CLI

**Kaanan** is an open-source, AI-powered security and documentation CLI tool. It combines Static Application Security Testing (SAST), UAT Documentation generation, and Vulnerability Assessment & Penetration Testing (VAPT) into a single command-line interface, powered by any LiteLLM-compatible language model.

---

## ⚠️ Disclaimer — Please Read Before Use

### VAPT Authorisation & Legal Responsibility

**By running `kaanan vapt`, you — the user — accept full and sole legal responsibility for all actions performed against the target system.**

The VAPT agent fires real HTTP attack payloads — including SQL injection strings, forged authentication tokens, path traversal sequences, SSRF probes, and other exploit vectors — against a live, running server. These are not simulated. They are real network requests with real potential to cause service disruption, data corruption, log pollution, rate-limit triggering, or unintended system state changes.

**You must have explicit, documented, written authorisation from the system owner before invoking `kaanan vapt` against any target.** Running VAPT against systems you do not own or have not been granted written permission to test is illegal in most jurisdictions, including but not limited to:

- The Computer Fraud and Abuse Act (CFAA) — United States
- The Computer Misuse Act 1990 — United Kingdom
- The Information Technology Act 2000 — India
- EU Directive 2013/40/EU on attacks against information systems
- Equivalent legislation in your jurisdiction

**Kaanan and its authors, contributors, and distributors accept zero liability for:**

- Any damage, disruption, data loss, or corruption caused to target systems
- Any legal consequences, civil claims, or criminal proceedings arising from unauthorised or negligent use of the VAPT feature
- Any data exposed, leaked, or compromised as a result of VAPT execution
- Any downstream consequences of vulnerability findings being acted upon incorrectly

By proceeding past the authorisation confirmation prompt displayed by `kaanan vapt`, you confirm that:

1. You own the target system, or hold documented written authorisation to perform penetration testing on it.
2. You accept full personal and legal responsibility for all HTTP requests sent by the VAPT agent.
3. You understand that the tool fires real attack payloads and that consequences are your responsibility alone.
4. You indemnify Kaanan, its authors, and contributors against any and all claims arising from your use of this tool.

**If you are unsure whether you have authorisation, you do not have authorisation. Do not proceed.**

---

### Data Privacy

Kaanan does **not** collect, store, transmit, or log your source code on its own servers. All file reading and processing happens locally on your machine. Kaanan's servers are never involved in the transmission of your code.

### Third-Party LLM Risk

Kaanan works by sending your source code to the LLM provider you configure — for example, OpenAI, Anthropic, Google, or a local Ollama instance. **Kaanan has no control over how those providers handle your data.** Many commercial API tiers may use your inputs to train or improve their models by default.

Before scanning production or proprietary code, you are strongly advised to:
- Review your LLM provider's data usage and privacy policy
- Opt out of training data collection if your provider offers it
- Use an enterprise or zero-data-retention API tier
- Use a local model (e.g. `ollama/llama3`) for maximum privacy

### Third-Party Dependency Risk

Kaanan relies on third-party open-source packages — including but not limited to `litellm`, `typer`, `rich`, `fpdf2`, `httpx`, and `python-dotenv` — to function. **Kaanan and its authors have no control over the security, integrity, or supply chain of these packages.**

As a real-world example, in March 2026, `litellm` versions `1.82.7` and `1.82.8` were found to contain a malicious credential-stealing payload introduced via a supply chain attack. Kaanan has since pinned its dependency to `litellm>=1.83.0`. However, no guarantee can be made that any third-party package will remain free of compromise in the future.

You are responsible for auditing, monitoring, and verifying the integrity of all packages installed in your environment.

### No Liability

By installing and using Kaanan, you acknowledge and accept all risks associated with transmitting your source code to third-party LLM providers, the behaviour and integrity of third-party packages, and any supply chain compromise affecting dependencies.

**Kaanan and its authors accept no liability** for data exposure, credential theft, model training on your code, security incidents, financial loss, system damage, legal consequences, or any other consequences — direct or indirect — arising from the use of this tool or any of its dependencies.

This tool is provided **"as is"**, without warranty of any kind, express or implied. **Use at your own risk.**

---

## Features

### SAST — Static Application Security Testing
- AI-powered scanning using any LiteLLM-compatible model
- Detects injection flaws, hardcoded secrets, broken authentication, SSRF, IDOR, path traversal, and more
- Maps findings to **CWE IDs** and **OWASP Top 10 2021**
- Generates a professional, self-contained **PDF report** with line-highlighted code snippets, impact assessments, and actionable remediation

### UAT Documentation Agent
- Classifies every file as **Backend**, **Frontend-Web**, **Frontend-App**, or **Non-Code**
- **Backend files**: extracts all endpoint routes, authentication requirements, request/response schemas, and a ready-to-run cURL command per endpoint
- **Frontend files**: extracts screen identity, testable element selectors (`data-testid`, `id`, etc.), user flows (trigger → resulting state), and API bindings linking UI actions to backend endpoints
- **Non-Code files**: skipped automatically with no LLM call
- Generates a structured **UAT PDF report** ready to share with QA engineers and testers

### VAPT — Vulnerability Assessment & Penetration Testing
- **Two-phase pipeline**: Phase 1 extracts the full API surface from source code using the doc scanner; Phase 2 attacks each discovered endpoint against the live running application.
- **Analyst-driven attack generation**: the LLM reasons about each endpoint's purpose, data flow, trust boundaries, and high-value targets before generating targeted payloads — not a generic checklist.
- **Covers**: SQL Injection, NoSQL Injection, BOLA/IDOR, Broken Authentication, Auth Bypass, Command Injection, Path Traversal, SSRF, XSS, Mass Assignment, LLM Prompt Injection, and Sensitive Data Exposure.
- **Baseline comparison**: fires a clean baseline request before any attack, then compares live HTTP responses (status codes, response body content, headers, timing) to confirm or rule out each vulnerability.
- **Full audit trail**: every attack attempt is recorded — confirmed or not — with the LLM analyst's written reasoning. The report is useful whether vulnerabilities are found or not.
- **Per-endpoint token budget**: `KAANAN_MAX_TOKENS_PER_API` sets a cumulative token spend limit per endpoint, preventing runaway costs and controlling scan depth.
- Generates a **VAPT PDF report** with target summary, per-endpoint attack logs, confirmed finding cards (evidence, impact, attack payload, remediation), and analyst reasoning for every tested vector.

### General
- Supports OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, and local Ollama models via LiteLLM
- Configurable file extension whitelist
- Zero telemetry — no data is sent to Kaanan's servers

---

## Installation

Requires **Python 3.10+**.

```bash
pip install kaanan
```

---

## Quick Start

### Step 1 — Scaffold your config

```bash
kaanan init
```

Creates a `.env` file and a `kaanan_whitelist.txt` in your current directory.

### Step 2 — Edit `.env`

```env
# Required for all modes
KAANAN_API_KEY=your_api_key_here
KAANAN_MODEL=gpt-4o

# Required for VAPT only — start your application before running kaanan vapt
# KAANAN_TARGET_IP=127.0.0.1
# KAANAN_TARGET_PORT=5000
# KAANAN_TARGET_FILE=app.py
# KAANAN_MAX_TOKENS_PER_API=10000
```

### Step 3 — Run a SAST scan

```bash
kaanan scan --dir ./src
kaanan scan --dir .   --output ./reports/security.pdf
```

### Step 4 — Generate UAT documentation

```bash
kaanan document scan --dir ./src
kaanan document scan --dir . --output ./reports/uat.pdf
```

### Step 5 — Run VAPT against your live application

```bash
# 1. Start your application first
python app.py   # or node index.js, uvicorn main:app, etc.

# 2. Uncomment and set VAPT vars in .env
# 3. Run VAPT
kaanan vapt --dir ./src
kaanan vapt --dir . --output ./reports/vapt.pdf
```

You will be prompted to confirm authorisation before any attack payload is fired. No requests are sent without your explicit confirmation.

### Step 6 — Open the PDF reports

| Report | Default output file |
|--------|-------------------|
| SAST Security Report | `kaanan_report.pdf` |
| UAT Documentation Report | `kaanan_uat_report.pdf` |
| VAPT Assessment Report | `kaanan_vapt_report.pdf` |

---

## Supported LLM Providers

| Provider       | `KAANAN_MODEL` value                                    |
|----------------|---------------------------------------------------------|
| OpenAI         | `gpt-4o` / `gpt-4o-mini` / `gpt-4-turbo`               |
| Anthropic      | `claude-3-5-sonnet-20241022` / `claude-3-opus-20240229` |
| Google         | `gemini/gemini-1.5-pro`                                 |
| Local (Ollama) | `ollama/llama3` / `ollama/mistral`                      |
| Azure OpenAI   | `azure/your-deployment-name`                            |
| AWS Bedrock    | `bedrock/anthropic.claude-3-sonnet`                     |

Full provider list: https://docs.litellm.ai/docs/providers

For local Ollama models, set `KAANAN_API_KEY=dummy` — no real key is required.

---

## Configuration

### `.env` File

Place a `.env` file in the directory where you run `kaanan`.

```env
# ── LLM Configuration (required for all modes) ──────────────────────────────
KAANAN_API_KEY=sk-...      # Your provider API key
KAANAN_MODEL=gpt-4o        # LiteLLM model string

# ── VAPT Configuration (required for kaanan vapt only) ──────────────────────
KAANAN_TARGET_IP=127.0.0.1           # IP where your application is running
KAANAN_TARGET_PORT=5000              # Port your application listens on
KAANAN_TARGET_FILE=app.py            # Entry-point file (e.g. app.py, index.js)
KAANAN_MAX_TOKENS_PER_API=10000      # Cumulative token budget per endpoint
```

**Important distinction:**
- `KAANAN_MAX_TOKENS_PER_API` is a **cumulative spend budget** — it tracks total prompt + completion tokens across all LLM calls made for a single endpoint and stops firing further attacks once that threshold is hit. It is not a per-response output cap.
- The internal per-response output caps are fixed constants (`ATTACK_GEN_MAX_TOKENS=2048`, `ANALYSIS_MAX_TOKENS=1200`) and are independent of your `.env` settings.

### `kaanan_whitelist.txt` (Optional)

Controls which file extensions are scanned. One extension per line. Lines starting with `#` are ignored.

```
# Backend
.py
.js
.ts
.java
# Frontend
.tsx
.jsx
.vue
.html
```

If this file is absent, Kaanan uses these defaults:

| Mode | Default extensions |
|------|--------------------|
| SAST | `.py .js .ts .java .go .php .rb .cs .cpp .c` |
| UAT Doc | All SAST defaults plus `.tsx .jsx .vue .html .svelte .dart .swift .kt` |
| VAPT | Same as UAT defaults (VAPT runs the doc scanner internally in Phase 1) |

---

## SAST Report Contents

- **Severity summary** — CRITICAL / HIGH / MEDIUM / LOW counts with overall risk rating
- **Per-file findings** with CWE ID and OWASP Top 10 2021 category
- **Exact vulnerable code snippet** with line number and surrounding context (highlighted)
- **Impact assessment** — real-world consequences of exploitation
- **Actionable remediation** — concrete fix with corrected code examples
- **Token usage summary** — model, prompt, and completion token counts

---

## UAT Documentation Report Contents

- **File classification summary** — Backend / Frontend-Web / Frontend-App / Non-Code counts
- **Backend endpoint cards** per file:
  - HTTP method badge and route path
  - Authentication requirements
  - Request payload with field names, types, and constraints
  - Response scenarios (success and error states)
  - Executable cURL command with mock data
- **Frontend screen blocks** per file:
  - Screen name and navigation route
  - Testable elements with selector type and value
  - Client-side validation rules per element
  - User flows — trigger action mapped to resulting UI state
  - API bindings — UI action mapped to the exact backend endpoint it calls
- **Token usage summary**

---

## VAPT Report Contents

- **Target summary** — URL, entry point, scan date, model, overall risk rating
- **Statistics grid** — endpoints tested, attacks fired, confirmed findings by severity
- **Confirmed vulnerability section** (endpoints with findings, sorted by severity):
  - Finding cards with severity badge, vector name, CWE ID, OWASP category
  - Evidence — specific observable proof from the live response
  - Attack payload — exact body or path mutation sent
  - Impact — real-world exploitation consequence
  - Remediation — concrete fix
  - Analyst reasoning — LLM's analytical justification for confirming the finding
- **Attack log per endpoint** — every attack attempt recorded regardless of outcome:
  - Vector, CWE, method, status change (baseline → attack), response time
  - Exact payload sent
  - Analyst reasoning explaining why the attack did or did not confirm a vulnerability
- **Tested endpoints section** — clean endpoints with their full attack logs
- **Token usage summary** — total tokens consumed across the entire VAPT scan

---

## Commands

```bash
kaanan --help                                    # Show setup guide
kaanan init                                      # Scaffold .env + whitelist
kaanan scan --help                               # Show SAST scan options
kaanan scan --dir PATH                           # Run a SAST security scan
kaanan scan --dir PATH --output FILE             # SAST scan with custom report path
kaanan document scan --help                      # Show UAT doc options
kaanan document scan --dir PATH                  # Generate UAT documentation
kaanan document scan --dir PATH --output FILE    # UAT docs with custom report path
kaanan vapt --help                               # Show VAPT options
kaanan vapt --dir PATH                           # Run VAPT against a live application
kaanan vapt --dir PATH --output FILE             # VAPT with custom report path
```

---

## Examples

```bash
# SAST — scan your entire project
kaanan scan --dir .

# SAST — scan only the src folder, save report with date stamp
kaanan scan --dir ./src --output ./reports/$(date +%Y%m%d)_sast.pdf

# UAT — document all backend and frontend files
kaanan document scan --dir ./src

# UAT — document and save to a custom path
kaanan document scan --dir ./src --output ./reports/$(date +%Y%m%d)_uat.pdf

# VAPT — start your app first, then run (authorisation prompt will appear)
python app.py &
kaanan vapt --dir ./src

# VAPT — save report to a custom path
kaanan vapt --dir ./src --output ./reports/$(date +%Y%m%d)_vapt.pdf

# Use a local Ollama model (no API key needed, maximum privacy)
# Set KAANAN_MODEL=ollama/llama3 and KAANAN_API_KEY=dummy in .env
kaanan scan --dir ./src
kaanan document scan --dir ./src
kaanan vapt --dir ./src
```

---

## Project Structure

```
kaanan-project/
├── pyproject.toml
├── README.md
├── LICENSE
└── kaanan/
    ├── __init__.py
    ├── assets/
    │   └── logo.png
    ├── cli.py            # CLI entry point — all commands
    ├── config.py         # KaananConfig + VaptConfig + loaders
    ├── scanner.py        # SAST engine
    ├── report.py         # SAST PDF report generator
    ├── doc_scanner.py    # UAT doc scanner
    ├── doc_report.py     # UAT PDF report generator
    ├── vapt_scanner.py   # VAPT engine (attack generation + analysis)
    └── vapt_report.py    # VAPT PDF report generator
```

---

## Contributing

Issues and pull requests are welcome. Please open an issue before submitting large changes.

---

## Publishing

```bash
# Test PyPI
pip install -i https://test.pypi.org/simple/ kaanan

# Production PyPI
pip install kaanan
```

---

*Kaanan is not affiliated with OpenAI, Anthropic, Google, or any LLM provider. All trademarks belong to their respective owners.*
