{
  "markdown": "# Kelan: AI-Native SAST/DAST & Zero-Trust Security Platform\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)\n[![Rust 2021](https://img.shields.io/badge/rust-2021-orange.svg)](https://www.rust-lang.org/)\n[![eBPF Kernel Security](https://img.shields.io/badge/eBPF-Linux--Kernel-red.svg)](https://ebpf.io/)\n[![Post-Quantum Cryptography](https://img.shields.io/badge/PQC-ML--KEM--768%20%7C%20Kyber-purple.svg)](https://csrc.nist.gov/projects/post-quantum-cryptography)\n[![Ollama Powered](https://img.shields.io/badge/LLM-Ollama%20Local-green.svg)](https://ollama.ai/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**Kelan** is a privacy-first, local-first security platform combining AST-aware Static Application Security Testing (**SAST**), dynamic agentic vulnerability scanning (**DAST**), and a Post-Quantum Zero-Trust Network Shield powered by eBPF and ML-KEM-768.\n\nBy running entirely on local LLMs via Ollama, **Kelan ensures zero code or network telemetry ever leaves your environment**.\n\n---\n\n## 📑 Table of Contents\n\n- [Key Features](#-key-features)\n- [Architecture Overview](#-architecture-overview)\n  - [1. SAST Engine (`kelan scan`)](#1-sast-engine-kelan-scan)\n  - [2. DAST Engine (`kelan dast`)](#2-dast-engine-kelan-dast)\n  - [3. Zero-Trust & Post-Quantum Shield](#3-zero-trust--post-quantum-shield)\n- [Installation & Setup](#-installation--setup)\n  - [System Requirements](#system-requirements)\n  - [Environment Setup](#environment-setup)\n  - [Local LLM Models](#local-llm-models)\n- [CLI Reference & Usage](#-cli-reference--usage)\n  - [Interactive Mode](#interactive-mode)\n  - [SAST Command (`kelan scan`)](#sast-command-kelan-scan)\n  - [DAST Command (`kelan dast`)](#dast-command-kelan-dast)\n  - [CI/CD Integration](#cicd-integration)\n- [Repository Structure](#-repository-structure)\n- [Reporting Formats](#-reporting-formats)\n  - [Terminal Report](#terminal-report)\n  - [JSON Report Schema](#json-report-schema)\n- [License](#-license)\n\n---\n\n## 🚀 Key Features\n\n* **Zero Code Leakage**: Uses local Ollama models (`qwen2.5-coder`, `gemma4`) for vulnerability analysis. Proprietary code and dynamic payloads are never sent to external cloud APIs.\n* **AST-Aware Semantic Chunker**: Parses multi-language source code (Python, JavaScript, TypeScript) using Tree-sitter into scope-aware code units (functions, classes) to bypass arbitrary token window limits.\n* **Hybrid Deterministic + AI DAST**: Combines async web crawling, deterministic heuristic pattern matchers (SQL errors, reflected XSS, marker echo, header audits), and multi-family payload bypass suites with optional LLM summary generation.\n* **WAF & Filter Bypass Suite**: Probes targets using 68+ payload variants across XSS, SQLi, Command Injection, Path Traversal, and SSTI (percent-encoding, double-encoding, HTML entities, Unicode, null-bytes, comment breaks).\n* **Post-Quantum Network Enforcement**: Implements ML-KEM-768 (Kyber768) handshakes paired with eBPF kernel maps to enforce zero-trust network packet filtering at ring 0.\n* **CI/CD Native**: Supports configurable severity thresholds (`--ci-gate high`) and structured JSON output for automated build pipeline failure and SIEM/dashboard ingestion.\n\n---\n\n## 🏗 Architecture Overview\n\n```\n                                +-----------------------------------+\n                                |            KELAN CLI              |\n                                |     (kelan scan / kelan dast)     |\n                                +-----------------+-----------------+\n                                                  |\n                    +-----------------------------+-----------------------------+\n                    |                                                           |\n                    v                                                           v\n       +-------------------------+                                 +-------------------------+\n       |   SAST Pipeline         |                                 |   DAST Pipeline         |\n       |   (kelan/scanner/)      |                                 |   (kelan/dast/)         |\n       +------------+------------+                                 +------------+------------+\n                    |                                                           |\n      +-------------+-------------+                               +-------------+-------------+\n      |                           |                               |                           |\n      v                           v                               v                           v\n+-----------+               +-----------+                   +-----------+               +-----------+\n| Tree-     |               | Local     |                   | Async BFS |               | Heuristic |\n| sitter    |               | Ollama    |                   | Crawler   |               | Evidence  |\n| Chunker   |               | LLM       |                   | & Prober  |               | Grader    |\n+-----------+               +-----------+                   +-----------+               +-----------+\n                                                                                              |\n                                                                                              v\n                                                                                    +-------------------+\n                                                                                    | Payload Bypass    |\n                                                                                    | Engine (68+ sets) |\n                                                                                    +-------------------+\n```\n\n### 1. SAST Engine (`kelan scan`)\n* **Tree-Sitter Chunking**: Traverses codebases and extracts syntactically complete functions and classes instead of slicing raw lines.\n* **Prompt Schema Enforcement**: Formats requests into structured JSON schemas (`SCANNER_JSON_SCHEMA`) enforcing root cause analysis and CWE mapping.\n* **Strict Noise Reduction**: Instructs the model to dismiss code style or linting rules and focus exclusively on injection, state manipulation, logic bypass, and cryptographic flaws.\n\n### 2. DAST Engine (`kelan dast`)\n* **Async BFS Crawler**: Spiders origin-scoped HTML pages, identifying forms, input elements, hidden parameters, and URL query keys.\n* **Bypass Probe Generator**: Generates encoding variants (raw, HTML entities, percent-encoding, double-encoding, comment breaking, null-byte injection).\n* **Deterministic Graders**: Evaluates evidence without LLM hallucination:\n  * **XSS**: Verifies unencoded reflection of payload markers in HTTP 200 responses.\n  * **SQLi**: Matches SQL engine syntax and database exception strings.\n  * **Command Injection**: Detects unique echo marker reflection in response bodies.\n  * **Path Traversal**: Matches `/etc/passwd` or system file signatures.\n  * **IDOR**: Measures structural response deltas across distinct resource IDs.\n* **LLM Narrative Enrichment**: Optionally invokes Ollama to refine titles and remediation steps without altering underlying evidence or findings.\n\n### 3. Zero-Trust & Post-Quantum Shield\n* **PQC Handshake**: Uses Kyber768 (ML-KEM-768) post-quantum key encapsulation for initial session negotiation.\n* **eBPF Enforcement**: Syncs authenticated identity states to eBPF kernel maps to perform line-rate packet drops for unauthenticated network traffic.\n\n---\n\n## 📦 Installation & Setup\n\n### System Requirements\n* **OS**: Linux / macOS\n* **Python**: 3.10+\n* **Rust Toolchain**: 1.75+ (for eBPF & PQC modules)\n* **Ollama**: Installed and running locally (`http://localhost:11434`)\n\n### Environment Setup\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/kelan-security/kelan.git\n   cd kelan\n   ```\n\n2. **Create and Activate Virtual Environment**:\n   ```bash\n   python3 -m venv .venv\n   source .venv/bin/activate\n   ```\n\n3. **Install Dependencies and Package**:\n   ```bash\n   pip install --upgrade pip\n   pip install -r requirements.txt\n   pip install -e .\n   ```\n\n### Local LLM Models\n\nPull your preferred model via Ollama:\n\n```bash\n# Recommended for code analysis & speed (4.7 GB)\nollama pull qwen2.5-coder:latest\n\n# Alternative general-purpose model (9.6 GB)\nollama pull gemma4:latest\n```\n\n### Running `kelan` CLI Commands\n\nIf running `kelan scan` returns `zsh: command not found: kelan`, use one of the following methods:\n\n#### Option 1: Activate the Virtual Environment (Recommended)\nRun this command in your terminal:\n```bash\nsource .venv/bin/activate\n```\nOnce activated, your terminal prompt will show `(.venv)` and you can run `kelan` directly from anywhere:\n```bash\nkelan scan\n```\n\n#### Option 2: Run via Virtual Environment Path Directly\nWithout activating `.venv`, call the executable using its relative path:\n```bash\n.venv/bin/kelan scan\n```\n\n#### Optional: Make `kelan` Globally Available in Shell\nIf you want `kelan` to work anywhere without having to activate `.venv` every time, add an alias to your Zsh configuration (`~/.zshrc`):\n```bash\necho 'alias kelan=\"$(pwd)/.venv/bin/kelan\"' >> ~/.zshrc\nsource ~/.zshrc\n```\nAfter doing this, typing `kelan scan` or `kelan dast` will work in any shell window!\n\n---\n\n## ⚙️ CLI Reference & Usage\n\n### Interactive Mode\n\nRunning `kelan scan` without arguments launches an interactive prompt guiding target, limit, and model selection:\n\n```bash\nkelan scan\n```\n\n```text\n🎯 Enter target directory to scan [default: .]: kelan/api\n⚡ Enter chunk limit (0 for all) [default: 10]: 5\n\n🧠 Available local models:\n  1. qwen2.5-coder:latest  ← recommended\n  2. gemma4:latest\n\nSelect a model (1-2) or type name [default: qwen2.5-coder:latest]: 1\n```\n\n### SAST Command (`kelan scan`)\n\n| Flag | Type | Default | Description |\n|---|---|---|---|\n| `--target` | `path` | `.` | Target directory to scan |\n| `--limit` | `int` | `10` | Maximum AST chunks to analyze (`0` for all) |\n| `--model` | `string` | `qwen2.5-coder:latest` | Local Ollama model name |\n| `--concurrency` | `int` | `2` | Number of parallel chunk evaluations |\n| `--timeout` | `float` | `180.0` | Per-chunk timeout in seconds |\n| `--json` | `path` | `None` | Write full analysis results to a JSON file |\n| `--no-limit` | `flag` | `False` | Analyze every chunk in the target directory |\n\n#### Examples\n```bash\n# Scan production API directory with 20-chunk limit\nkelan scan --target kelan/api --limit 20 --model qwen2.5-coder:latest\n\n# Full repository scan with JSON report output\nkelan scan --target . --no-limit --json sast_report.json\n```\n\n### DAST Command (`kelan dast`)\n\n| Flag | Type | Default | Description |\n|---|---|---|---|\n| `--target` | `url` | *Required* | Target seed URL |\n| `--model` | `string` | `qwen2.5-coder:latest` | Local Ollama model for narrative enrichment |\n| `--crawl` | `flag` | `False` | Spider origin-scoped pages before probing |\n| `--max-pages` | `int` | `15` | Maximum pages to spider when `--crawl` is enabled |\n| `--max-depth` | `int` | `3` | Maximum crawl depth |\n| `--bypass` | `flag` | `False` | Enable multi-family encoding bypass payloads (68+ probes) |\n| `--vectors` | `string` | `xss,sqli,cmdi,traversal,ssti` | Comma-separated list of vulnerability vectors |\n| `--delay` | `float` | `0.5` | Politeness delay between requests (seconds) |\n| `--json` | `path` | `None` | Path to save JSON report |\n| `--ci-gate` | `string` | `None` | Threshold to fail build (`critical`, `high`, `medium`, `low`) |\n| `--no-llm` | `flag` | `False` | Run deterministic heuristic evaluation only (no LLM call) |\n\n#### Examples\n```bash\n# Basic single-page endpoint audit\nkelan dast --target http://localhost:8080\n\n# Comprehensive web crawl with bypass probes & JSON report\nkelan dast --target http://localhost:8080 --crawl --max-pages 20 --bypass --json dast_report.json\n\n# CI Pipeline run: fail build if HIGH or CRITICAL flaws exist\nkelan dast --target http://staging.internal/ --crawl --bypass --ci-gate high\n```\n\n### CI/CD Integration\n\nExample GitHub Actions workflow snippet (`.github/workflows/security-scan.yml`):\n\n```yaml\nname: Kelan Security Audit\n\non:\n  push:\n    branches: [ main, master ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  security-audit:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Set up Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n\n      - name: Start Ollama Service\n        run: |\n          curl -fsSL https://ollama.com/install.sh | sh\n          ollama serve &\n          sleep 5\n          ollama pull qwen2.5-coder:latest\n\n      - name: Install Kelan\n        run: |\n          python -m venv .venv\n          source .venv/bin/activate\n          pip install -r requirements.txt\n          pip install -e .\n\n      - name: Run SAST Audit\n        run: |\n          source .venv/bin/activate\n          kelan scan --target kelan/api --no-limit --json sast_report.json\n\n      - name: Run DAST Audit with CI Gate\n        run: |\n          source .venv/bin/activate\n          kelan dast --target http://localhost:8080 --crawl --bypass --json dast_report.json --ci-gate high\n\n      - name: Upload Scan Artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: security-reports\n          path: |\n            sast_report.json\n            dast_report.json\n```\n\n---\n\n## 📁 Repository Structure\n\n```text\nkelan/\n├── pyproject.toml              # PEP 621 build config & console_scripts entry\n├── requirements.txt            # Python dependencies\n├── kelan-scan                  # Convenience shell wrapper\n├── kelan/                      # Main Python package\n│   ├── ai/                     # Local LLM integration\n│   │   ├── ollama_client.py    # Async HTTP client for Ollama API\n│   │   └── prompts.py          # Trust-engine prompt definitions\n│   ├── api/                    # Security management API\n│   │   ├── server.py           # FastAPI management endpoints\n│   │   ├── middleware/         # Auth & rate-limiting middleware\n│   │   └── routes/             # API route handlers\n│   ├── dast/                   # Dynamic Application Security Testing\n│   │   ├── agent.py            # Legacy single-target DAST agent\n│   │   ├── bypass.py           # Multi-family payload bypass engine\n│   │   ├── cli.py              # DAST CLI command handler\n│   │   ├── crawler.py          # Async BFS spider & HTML form parser\n│   │   ├── heuristics.py       # Deterministic evidence graders\n│   │   ├── llm.py              # LLM finding summarizer & narrative writer\n│   │   ├── pipeline.py         # End-to-end DAST scan orchestrator\n│   │   └── report.py           # Finding/Report dataclasses & CI gate logic\n│   ├── enforcement/            # Kernel & eBPF enforcement\n│   │   └── ebpf_bridge.py      # Kernel packet filtering bridge\n│   ├── protocol/               # Post-Quantum cryptography & handshake\n│   │   ├── crypto.py           # Kyber768 ML-KEM wrapper\n│   │   └── handshake.py        # AITP handshake state machine\n│   └── scanner/                # Static Application Security Testing\n│       ├── analyzer.py         # VulnerabilityAnalyzer using Ollama\n│       ├── chunker.py          # Tree-sitter AST semantic chunker\n│       ├── cli.py              # SAST CLI command handler\n│       ├── entrypoint.py       # Top-level 'kelan' CLI dispatcher\n│       └── prompts.py          # SAST system prompt & JSON schema\n└── tests/                      # Suite of unit & integration tests\n    ├── dummy_server.py         # Intentionally vulnerable DAST target server\n    ├── sample.py               # SAST test fixture\n    └── unit/                   # Automated pytest suite\n```\n\n---\n\n## 📊 Reporting Formats\n\n### Terminal Report\n\n```text\n========================================================================\n🛡️  KELAN DAST AGENT REPORT\n========================================================================\nTarget:          http://localhost:8080\nModel:           qwen2.5-coder:latest\nFindings:        3\n========================================================================\n\n[HIGH] CWE-79 — Reflected Cross-Site Scripting (XSS)\n  URL:         http://localhost:8080/\n  Param:       search (GET)\n  Evidence:    payload reflected unencoded in response (HTTP 200): <script>alert(1)</script>\n  Remediation: Context-aware output encoding + CSP; input allowlist validation.\n------------------------------------------------------------------------\n\n[HIGH] CWE-639 — Broken Object Level Authorization (BOLA/IDOR)\n  URL:         http://localhost:8080/api/user\n  Param:       id (GET)\n  Evidence:    Two different object IDs returned distinct (142 vs 138 byte) responses without authentication.\n  Remediation: Enforce server-side authorization per object.\n------------------------------------------------------------------------\n\n[MEDIUM] CWE-693 — Missing Content-Security-Policy header\n  URL:         http://localhost:8080/\n  Param:       - (GET)\n  Evidence:    response omits content-security-policy\n  Remediation: Set CSP, HSTS, X-Frame-Options, X-Content-Type-Options.\n------------------------------------------------------------------------\n========================================================================\n```\n\n### JSON Report Schema\n\nSaved when passing `--json report.json`:\n\n```json\n{\n  \"tool\": \"kelan-dast\",\n  \"target\": \"http://localhost:8080\",\n  \"model\": \"qwen2.5-coder:latest\",\n  \"started_at\": \"2026-08-05T11:05:23.123456+00:00\",\n  \"finished_at\": \"2026-08-05T11:05:45.654321+00:00\",\n  \"meta\": {},\n  \"risk_summary\": \"The application exhibits critical reflected XSS and unauthenticated BOLA endpoints.\",\n  \"stats\": {\n    \"severities\": { \"CRITICAL\": 0, \"HIGH\": 2, \"MEDIUM\": 1, \"LOW\": 0, \"INFO\": 0 },\n    \"categories\": { \"xss\": 1, \"idor\": 1, \"header\": 1 },\n    \"cwes\": { \"CWE-79\": 1, \"CWE-639\": 1, \"CWE-693\": 1 }\n  },\n  \"findings\": [\n    {\n      \"url\": \"http://localhost:8080/\",\n      \"method\": \"GET\",\n      \"param\": \"search\",\n      \"category\": \"xss\",\n      \"title\": \"Reflected Cross-Site Scripting (XSS)\",\n      \"evidence\": \"payload reflected unencoded in response (HTTP 200): <script>alert(1)</script>\",\n      \"remediation\": \"Context-aware output encoding + CSP; input allowlist validation.\",\n      \"cwe\": \"CWE-79\",\n      \"severity\": \"HIGH\",\n      \"payload\": \"<script>alert(1)</script>\",\n      \"variant\": \"raw\",\n      \"confidence\": \"strong\",\n      \"detected_at\": \"2026-08-05T11:05:30.000000+00:00\"\n    }\n  ]\n}\n```\n\n---\n\n## 📜 License\n\nDistributed under the **MIT License**. See `LICENSE` for details.\n",
  "bytes": 18539,
  "sha": "d614b87f2fde59bfeb18bcd3065e990c6405eac7ecedf0d0301af468613a5f6b",
  "repo_slug": "tanush-jain/kelan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tanush_jain_kelan_d19d0686/readme"
}