Metadata-Version: 2.4
Name: kaanan
Version: 0.1.9
Summary: AI-driven SAST 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
Dynamic: license-file

# 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 using large language models (LLMs) and produces a detailed, shareable PDF report.

---

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

- AI-powered SAST 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**
- 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 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 — Open the PDF report

By default, the report is saved as `kaanan_report.pdf` in your current directory. Open it 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=s-...        # 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. One extension per line. Lines starting with `#` are ignored.

```
# Scan only these extensions
.py
.js
.ts
.java
```

If this file is absent, Kaanan uses these defaults: `.py .js .ts .java .go .php .rb .cs .cpp .c`

---

## PDF Report Contents

Each generated report includes:

- **Severity summary** — CRITICAL / HIGH / MEDIUM / LOW counts
- **Per-file findings** with CWE ID and OWASP Top 10 2021 category
- **Exact vulnerable code snippet** with line number
- **Impact assessment** — real-world consequences of exploitation
- **Actionable remediation** — concrete fix with corrected code examples

---

## Project Structure

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

---

## Commands

```bash
kaanan --help                      # Show setup guide
kaanan init                        # Scaffold .env + whitelist
kaanan scan --help                 # Show scan options
kaanan scan --dir PATH             # Run a SAST scan
kaanan scan --dir PATH --output F  # Scan and save report to file F
```

---

## Examples

```bash
# Scan your entire project
kaanan scan --dir .

# Scan only the src folder, save report with date stamp
kaanan scan --dir ./src --output ./reports/$(date +%Y%m%d)_scan.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
```

---

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