# Kaanan — AI-Driven SAST & VAPT CLI

**Kaanan** is an open-source, AI-powered Static Application Security Testing (SAST) and Vulnerability Assessment & Penetration Testing (VAPT) command-line tool. It scans your source code for security vulnerabilities and generates detailed, shareable PDF reports. It also includes a UAT Documentation agent that classifies your codebase and produces structured documentation for QA engineers and testers.

---

## ⚠️ Disclaimer — Please Read Before Use

### 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`, 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 on the maintainer's PyPI
account. The malware targeted SSH keys, cloud credentials, API keys, and `.env` files. Kaanan has since
pinned its dependency to `litellm>=1.83.0`, which is the verified clean release. However, we cannot
guarantee that any third-party package will remain free of compromise in the future.

You are responsible for:
- Auditing the third-party packages installed in your environment
- Monitoring security advisories for all dependencies
- Rotating credentials immediately if any dependency in your environment is found to be compromised
- Verifying installed package versions against official GitHub releases before use

### 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, integrity, and security of third-party packages installed as dependencies
- Any supply chain compromise affecting packages that Kaanan depends upon, now or in the future

**Kaanan and its authors accept no liability** for data exposure, credential theft, model training on
your code, security incidents, financial loss, 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 — Security Scanning
- AI-powered Static Application Security Testing using any LiteLLM-compatible model
- Detects injection flaws, hardcoded secrets, broken auth, SSRF, IDOR, and more
- Maps findings to **CWE IDs** and **OWASP Top 10 2021**
- Generates a professional, self-contained **PDF report** with line-highlighted code snippets

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

### General
- Supports OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, and local Ollama models
- 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
```

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

### Step 2 — Edit `.env`

```env
KAANAN_API_KEY=your_api_key_here
KAANAN_MODEL=gpt-4o
```

### Step 3 — Run a SAST scan

```bash
# Scan the current directory
kaanan scan --dir .

# Scan a specific folder
kaanan scan --dir ./src

# Scan and save the report to a custom path
kaanan scan --dir ./src --output ./reports/security.pdf
```

### Step 4 — Generate UAT documentation

```bash
# Document the current directory
kaanan document scan --dir .

# Document a specific folder
kaanan document scan --dir ./src

# Document and save the report to a custom path
kaanan document scan --dir ./src --output ./reports/uat.pdf
```

### Step 5 — Open the PDF reports

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

Open either file with any PDF viewer.

---

## 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
KAANAN_API_KEY=sk-...   # Your provider API key
KAANAN_MODEL=gpt-4o     # LiteLLM model string
```

The `.env` file is read locally only. It is never uploaded or shared.

### `kaanan_whitelist.txt` (Optional)

Control which file extensions are scanned and documented. 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` |

---

## SAST Report Contents

Each generated security report includes:

- **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
- **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

Each generated UAT report includes:

- **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 (e.g. `data-testid = login-submit-btn`)
  - 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** — model, prompt, and completion token counts

---

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

---

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

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

---

## Project Structure

```
kaanan-project/
├── pyproject.toml
├── README.md
├── LICENSE
└── kaanan/
    ├── __init__.py
    ├── assets/
    │   └── logo.png
    ├── cli.py
    ├── config.py
    ├── scanner.py
    ├── report.py
    ├── doc_scanner.py
    └── doc_report.py
```

---

## Contributing

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

---

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