kaanan 0.2.0

AI-driven SAST and VAPT CLI tool

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

pip install kaanan

---

Quick Start

Step 1 — Scaffold your config

kaanan init

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

Step 2 — Edit .env

KAANAN_API_KEY=your_api_key_here
KAANAN_MODEL=gpt-4o

Step 3 — Run a SAST scan

# 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

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

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

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

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