VulnScan — AI-Powered Vulnerability Intelligence Scanner

Scan any GitHub repository for vulnerable dependencies, get AI-generated severity analysis and remediation steps — in your terminal.

📋 TL;DR

Problem: dependency vulnerability scanners return noisy CVE lists with no sense of real-world exploitability. Solution: VulnScan detects dependencies across 7 ecosystems, cross-references OSV.dev, and has an LLM generate exploitability analysis plus exact remediation steps. Output: terminal report, JSON, or GitHub-native SARIF — CI-ready.

 ██▀███  ▓█████▄▄▄█████▓ ██▀███  ▓█████ 
▓██ ▒ ██▒▓█   ▀▓  ██▒ ▓▒▓██ ▒ ██▒▓█   ▀ 
▓██ ░▄█ ▒▒███  ▒ ▓██░ ▒░▓██ ░▄█ ▒▒███   
▒██▀▀█▄  ▒▓█  ▄░ ▓██▓ ░ ▒██▀▀█▄  ▒▓█  ▄ 
░██▓ ▒██▒░▒████▒ ▒██▒ ░ ░██▓ ▒██▒░▒████▒
░ ▒▓ ░▒▓░░░ ▒░ ░ ▒ ░░   ░ ▒▓ ░▒▓░░░ ▒░ 
 VulnScan — AI-Powered Vulnerability Intelligence Scanner v1.0

🔑 Key Features

🔍 Dependency Detection — Automatically finds requirements.txt, package-lock.json, go.mod, pom.xml, Gemfile.lock, Cargo.lock and more across 7 ecosystems (Python, Node, Go, Maven, Ruby, NuGet, Rust)
🗄️ CVE Database Lookup — Queries OSV.dev (Google's open vulnerability database, backed by NVD, GitHub Advisories, PyPA, npm, Go, Rust)
🤖 AI-Powered Analysis — DeepSeek, OpenAI GPT-4o mini, Anthropic Claude, or local Ollama models generate real-world exploitability assessments + exact fix steps
🎯 Focus Areas — Filter results to security, performance, privacy, supply_chain concerns
📊 Multi-Format Output — text (terminal), json, and sarif (GitHub-native, Semgrep-compatible)
📤 CI/CD Ready — GitHub Actions integration, SARIF upload, exit codes for CI gates
🪶 Lightweight — pure Python, no framework, ~600 lines of core code

⚡ Quick Start

# Clone
git clone https://github.com/glatinone/vulnscan.git
cd vulnscan

# Install
pip install -r requirements.txt

# Copy and edit config
cp .env.example .env
# → Add your GITHUB_TOKEN and LLM_API_KEY to .env

# Scan
python vulnscan.py --repo owner/project

Run with AI Analysis (recommended)

# Requires LLM_API_KEY — DeepSeek is the default provider (cheapest & fast)
python vulnscan.py --repo owner/project

🔧 Configuration

VulnScan loads configuration from three sources — in priority order:

1. CLI flags (highest priority)

python vulnscan.py \
  --repo owner/project \
  --token ghp_xxxxxxxxxxxxxxxxxxxx \
  --llm-api-key sk-xxxxxxxxxxxxxxxxxxxx \
  --model deepseek \
  --format sarif \
  --output results.sarif

2. Environment variables (`.env` file)

# Required
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# LLM API keys (pick one based on your provider)
LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx       # DeepSeek (default provider)
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx     # OpenAI
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx      # Anthropic

# Optional
NVD_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   # Higher NVD rate limits

3. `.env` file setup

cp .env.example .env
# Edit .env with your tokens

📖 Usage

Basic Scan

python vulnscan.py --repo owner/project
python vulnscan.py --repo https://github.com/owner/project

With Focus Areas

# Security + supply chain focus
python vulnscan.py --repo owner/project \
  --focus security \
  --focus supply_chain

Available focus areas: security, performance, privacy, supply_chain

Output Formats

# Terminal (default)
python vulnscan.py --repo owner/project

# JSON (for automation / piping)
python vulnscan.py --repo owner/project --format json -o report.json

# SARIF (GitHub Security tab — Semgrep-compatible)
python vulnscan.py --repo owner/project --format sarif -o results.sarif

🤖 Multi-LLM Support

VulnScan is provider-agnostic. Set up one or more:

Provider	Model	Environment Variable	Flag
DeepSeek (default)	deepseek-chat	`LLM_API_KEY`	`--model deepseek`
OpenAI	GPT-4o mini	`OPENAI_API_KEY`	`--model openai`
Anthropic	Claude Sonnet	`ANTHROPIC_API_KEY`	`--model anthropic`
Ollama (local)	any installed model	(no key needed)	`--model ollama`

Ollama example (no API key)

# Terminal 1: start Ollama
ollama serve
ollama pull llama3.2

# Terminal 2: run VulnScan
python vulnscan.py --repo owner/project \
  --model ollama \
  --ollama-url http://localhost:11434

📦 Supported Ecosystems

Ecosystem	Files Detected	PURL scheme
Python / pip	`requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`	`pkg:pypi/`
Node.js / npm	`package.json`, `package-lock.json`	`pkg:npm/`
Go	`go.mod`, `go.sum`	`pkg:go/`
Maven / Java	`pom.xml`	`pkg:maven/`
Ruby / gem	`Gemfile`, `Gemfile.lock`	`pkg:gem/`
NuGet / .NET	`packages.config`, `*.csproj`	`pkg:nuget/`
Rust / Cargo	`Cargo.toml`, `Cargo.lock`	`pkg:cargo/`

🏗️ Architecture

vulnscan/
├── vulnscan.py           # CLI entry point + orchestration
├── requirements.txt
├── README.md
├── .env.example         # Environment variable template
└── src/
    ├── __init__.py
    ├── config.py          # CLI args + env var loader
    ├── github_client.py  # GitHub REST API (dependency file discovery)
    ├── parser.py          # Multi-ecosystem manifest parsers
    ├── scanner.py         # OSV.dev vulnerability database client
    ├── analyzer.py        # Multi-LLM AI analysis adapter
    └── reporter.py        # Text / JSON / SARIF output formatter

Data flow:

CLI args + env vars
  → config.py (resolve target, tokens, model, output)
  → github_client.py (fetch dependency manifest files from GitHub)
  → parser.py (extract packages per ecosystem)
  → scanner.py (query OSV.dev for each package → CVE/vulnerability records)
  → analyzer.py (optionally send vulnerabilities to LLM → enriched analysis)
  → reporter.py (format: text / JSON / SARIF → print or write file)

🚀 GitHub Actions Integration

# .github/workflows/vulnscan.yml
name: VulnScan

on:
  push:
    branches: [main, master]
  pull_request:

jobs:
  vulnscan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install VulnScan
        run: pip install -r requirements.txt

      - name: Run VulnScan
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          python vulnscan.py \
            --repo ${{ github.repository }} \
            --model deepseek \
            --focus security \
            --focus supply_chain \
            --format sarif \
            --output vulnscan.sarif

      - name: Upload SARIF to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: vulnscan.sarif
          category: "vulnscan/vulnerability-scan"

Note: The SARIF upload step requires GitHub Advanced Security enabled on the repository.

📋 Example Output

============================================================
🔍  VULNSCAN — AI-Powered Vulnerability Report
============================================================
📦  Repository   : owner/project
⏱️   Scan Time    : 2026-04-30 22:00 UTC
🔎   Vulnerabilities found: 3
💻  Language     : Python  |  ⭐ 1240
🎯   Focus Hits   : 2 (security, supply-chain)

────────────────────────────────────────────────────────────
🎯  FOCUS AREA FINDINGS (2)
────────────────────────────────────────────────────────────
  🔴 CRITICAL  CVE-2024-21538
  📦 requests@2.31.0 (pip)
  📁 requirements.txt
  🎯 CVSS 9.1 CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H
  ✅ Fix available: upgrade to 2.32.0
  💡 Requests < 2.32.0 allows CRLF injection via absolute
     URL in urllib3. Always validate/sanitize user-supplied
     URLs before passing to requests. Upgrade immediately.
  🔗 https://nvd.nist.gov/vuln/detail/CVE-2024-21538

  🟠 HIGH  CVE-2023-32681
  📦 urllib3@2.0.0 (pip)
  📁 requirements.txt
  🎯 CVSS 7.5 CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N
  ✅ Fix available: upgrade to 2.1.1
  💡 In urllib3 < 2.1.1, a proxy header injection flaw
     allows request smuggling. If your app proxies HTTP
     traffic, upgrade ASAP. Otherwise, still patch.
  🔗 https://nvd.nist.gov/vuln/detail/CVE-2023-32681

────────────────────────────────────────────────────────────
📋  ALL VULNERABILITIES (1)
────────────────────────────────────────────────────────────
  🟡 MEDIUM  CVE-2024-37890
  📦 pillow@10.2.0 (pip)
  📁 requirements.txt
  🎯 CVSS 6.5
  ✅ Fix available: upgrade to 10.3.0
  💡 Pillow < 10.3.0 has a bounds-check bypass in PNG
     processing. An attacker can trigger excessive memory
     via a crafted image. Low exploitability if image
     uploads are sandboxed.
  🔗 https://nvd.nist.gov/vuln/detail/CVE-2024-37890

============================================================
Generated by VulnScan | MIT License
============================================================

🛡️ Security Notes

No private repo access required — uses only public GitHub API endpoints
Tokens stay local — never sent anywhere except GitHub and your chosen LLM provider
Read-only — VulnScan never modifies repositories
SARIF format integrates with GitHub's Code Scanning alerts
CVSS scoring — uses NVD-standard CVSS 3.1 vector strings for severity

📋 Roadmap

Post results as GitHub PR comment (--post-comment)
Team config file (~/.vulnscan.yaml)
Periodic re-scan with diff alerts (--watch)
Rich TUI dashboard for interactive exploration
PyPI package distribution (pip install vulnscan)
Container image (docker run glatinone/vulnscan)
[ ]sbom input mode (--sbom)

🎯 Why This Project

Built as a portfolio project demonstrating:

API integration (GitHub REST, OSV.dev, multiple LLM providers)
Clean architecture (thin client → parser → scanner → analyzer → reporter)
CLI design (argparse, env vars, ANSI output, exit codes)
Error handling (auth, rate limits, network failures, malformed manifests)
Security domain knowledge (CVE, CVSS scoring, PURL, SARIF, SAST)
Extensibility (add ecosystems, LLMs, output formats without touching core logic)
CI/CD integration (GitHub Actions, SARIF, exit code gating)

License

MIT — Kiell Tampubolon

Navigation Menu

Repository files navigation

VulnScan — AI-Powered Vulnerability Intelligence Scanner

📋 TL;DR

🔑 Key Features

⚡ Quick Start

Run with AI Analysis (recommended)

🔧 Configuration

1. CLI flags (highest priority)

2. Environment variables (`.env` file)

3. `.env` file setup

📖 Usage

Basic Scan

With Focus Areas

Output Formats

🤖 Multi-LLM Support

Ollama example (no API key)

📦 Supported Ecosystems

🏗️ Architecture

🚀 GitHub Actions Integration

📋 Example Output

🛡️ Security Notes

📋 Roadmap

🎯 Why This Project

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
.env.example		.env.example
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
THREAT_MODEL.md		THREAT_MODEL.md
requirements.txt		requirements.txt
vulnscan.py		vulnscan.py

Latest commit

History

Folders and files

Repository files navigation

VulnScan — AI-Powered Vulnerability Intelligence Scanner

📋 TL;DR

🔑 Key Features

⚡ Quick Start

Run with AI Analysis (recommended)

🔧 Configuration

1. CLI flags (highest priority)

2. Environment variables (.env file)

3. .env file setup

📖 Usage

Basic Scan

With Focus Areas

Output Formats

🤖 Multi-LLM Support

Ollama example (no API key)

📦 Supported Ecosystems

🏗️ Architecture

🚀 GitHub Actions Integration

📋 Example Output

🛡️ Security Notes

📋 Roadmap

🎯 Why This Project

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2. Environment variables (`.env` file)

3. `.env` file setup