vigil-scanner 0.1.2

AI-powered multi-agent security scanner for detecting security vulnerabilities within a given github codebase

🛡️ Vigil

AI-Powered Security Scanner for Codebases

---

Vigil is a multi-agent AI security scanner that combines static analysis (Semgrep) with LLM verification to find real vulnerabilities in your code — and filter out the noise.

The Problem: Traditional static analysis tools generate hundreds of warnings. 80% are false positives. Developers stop reading them.

The Solution: Vigil uses an AI verifier agent to analyze each finding with Chain-of-Thought reasoning, filtering out false alarms and keeping only real threats.

✨ Key Features

• AI-Verified Findings — LLM analyzes each vulnerability with a 4-step security framework
• 86% Accuracy — Benchmarked on 100 real-world code samples with near-zero missed threats
• Multi-Provider LLM Support — Groq (free), Google Gemini, OpenAI, or local Ollama
• GitHub URL Scanning — Point it at any public repo and scan instantly
• CISO Executive Summary — AI-generated security report for stakeholders
• Interactive Setup — First-run wizard configures everything for you
• Docker Ready — Run anywhere with a single container

🚀 Quick Start

Install

pip install vigil-scanner

Requires Python 3.11 – 3.13. If your default Python is 3.14+, use one of these:

# Windows
py -3.12 -m pip install vigil-scanner

# Or use pipx (recommended for CLI tools)
pipx install vigil-scanner --python 3.12

# Or use Docker (no Python needed)
docker run -e LLM_PROVIDER=groq -e GROQ_API_KEY=your_key vigil scan <repo-url>

Scan a Repository

# Scan a remote GitHub repo
vigil scan https://github.com/username/repo

# Scan a local project
vigil scan ./my-project

On first run, Vigil will ask you to choose an LLM provider:

🛡️ Welcome to Vigil!

Available LLM Providers:

  1. Groq  —  Free cloud API (recommended)
  2. Google Gemini  —  Free tier available
  3. Ollama / LMStudio  —  Local & free
  4. OpenAI  —  Paid (GPT-4o)

Select provider (number): 1
Enter your Groq API key: gsk_xxxxx
 Configuration saved!

Reconfigure Anytime

vigil init

🐳 Docker

# Build
docker build -t vigil .

# Scan with cloud LLM
docker run -e LLM_PROVIDER=groq -e GROQ_API_KEY=your_key \
  vigil scan https://github.com/username/repo

# Scan with local Ollama (using docker compose)
docker compose up -d
docker compose exec ollama ollama pull llama3
docker compose run vigil scan https://github.com/username/repo

🏗️ Architecture

Vigil uses a LangGraph multi-agent pipeline with three specialized nodes:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Scanner    │────►│   Verifier   │────►│   Reporter   │
│  (Semgrep)   │     │  (LLM + CoT) │     │  (LLM)       │
│              │     │              │     │              │
│ Static       │     │ AI verifies  │     │ Generates    │
│ analysis     │     │ each finding │     │ executive    │
│ rules        │     │ with Chain-  │     │ summary &    │
│              │     │ of-Thought   │     │ fix advice   │
└──────────────┘     └──────────────┘     └──────────────┘
     Finds              Filters              Reports
   candidates        false positives      to the team

Verification Strategy

The Verifier agent uses:

• Chain-of-Thought (CoT) reasoning — 4-step analysis framework (data flow → defenses → CWE mapping → verdict)
• Few-Shot examples — Calibrated with real vulnerability patterns
• Batch processing — 10 findings per LLM call for token efficiency
• Confidence thresholds — Low-confidence dismissals are overridden (security-first)

📊 Benchmark Results

Tested on 100 real-world code samples from the Code Vulnerability Labeled Dataset:

Metric	Score
Accuracy	86%
False Negative Rate	2%
False Positive Rate	~14%
Missed Threats	1 out of 100

⚙️ Configuration

Vigil supports configuration through environment variables or the ~/.vigil/.env file:

Variable	Description	Default
LLM_PROVIDER	groq, google, openai, ollama	ollama
GROQ_API_KEY	Groq API key	—
GOOGLE_API_KEY	Google Gemini API key	—
OPENAI_API_KEY	OpenAI API key	—
OLLAMA_BASE_URL	Ollama endpoint URL	http://localhost:11434
OLLAMA_MODEL	Model name for Ollama	llama3

🛠️ Development

# Clone the repo
git clone https://github.com/yugan243/security-scanner.git
cd security-scanner

# Install dependencies
poetry install

# Run locally
poetry run vigil scan ./my-project

# Run benchmarks
poetry run python -m tests.benchmark

📝 License

MIT License — see LICENSE for details.

---

Built by Yugan Nimsara ❤️ with the help of Antigravity