kaanan 0.3.0

AI-driven SAST, UAT documentation, and VAPT CLI tool

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

pip install kaanan

---

Quick Start

Step 1 — Scaffold your config

kaanan init

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

Step 2 — Edit .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

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

Step 4 — Generate UAT documentation

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

Step 5 — Run VAPT against your live application

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

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

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

# 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

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