I built a self-hosted AI pipeline that clones a Java or Kotlin repository, resolves the full transitive dependency tree, checks every dependency against the OSV and NVD vulnerability databases, and generates an actionable security report — complete with BOM-aware upgrade recommendations and the exact build file lines to change. It runs as a Docker container with a built-in web UI and scan history. The code is open source.

GitHub: github.com/crewwithravi/scanner

What is VulnHawk?

VulnHawk is a personal research project I built to explore multi-agent AI architectures applied to software supply chain security. The idea is straightforward:

1. You submit — a GitHub repository URL or a list of Maven/Gradle dependency coordinates (via the API or web UI)
2. VulnHawk resolves — the full transitive dependency tree using mvn dependency:tree or gradle dependencies, then batch-queries the OSV and NVD vulnerability databases
3. AI interprets — a CrewAI agent pipeline reads the vulnerability data, checks whether each dep is BOM-managed, reviews changelogs, and searches the source code for affected APIs
4. You receive — a structured 10-section Markdown report with CVE IDs, severity ratings, and the exact version bump to make in your pom.xml or build.gradle

The key design principle: the vulnerability data is always real. The AI interprets and recommends — it never fabricates CVE IDs or version numbers.

Why I Built It

As someone working in enterprise application development — and currently pursuing a Master's in Data Science — I wanted a project that sits at the intersection of production engineering and applied AI. Dependency auditing was the right target: it is tedious, repetitive, and full of decisions that look simple but are surprisingly subtle.

The subtlest problem is the BOM trap. In any Spring Boot project, libraries like embedded Tomcat, Jackson, and Netty are not directly declared in pom.xml — their versions are managed by the Spring Boot BOM. If you bump them directly you break BOM consistency. The correct fix is to bump the Spring Boot parent version, which brings the safe library version automatically. Most vulnerability scanners miss this entirely and either give you the wrong fix or no fix at all.

VulnHawk detects this automatically and tells you exactly which parent version to change.

Key Features

Architecture: 4-Agent Pipeline

VulnHawk uses a sequential CrewAI pipeline — four specialised agents that hand structured data to the next in line. All data is fetched and computed from real sources before the AI layer ever sees it.

Agent 1  Repo Scanner          → detect Maven/Gradle, run dependency:tree
                                  output: [{group_id, artifact_id, version, scope, depth}]

Agent 2  Vulnerability Analyst → batch OSV query + NVD fallback per dep
                                  output: {vuln_count, vulnerabilities: [{id, severity, fix_version}]}

Agent 3  Upgrade Strategist    → BOM check → version lookup → changelog → code search
                                  output: upgrade plan with confidence score per dep

Agent 4  Report Generator      → 10-section Markdown report with exact build file changes

Every API response separates verified data (CVE IDs, CVSS scores, affected version ranges from OSV/NVD) from AI output (prose summaries, compatibility assessment, confidence scores). The LLM report is validated against the raw vulnerability data after generation — if it fails validation, VulnHawk silently falls back to a deterministic report builder.

Tech Stack

The Web UI

VulnHawk ships with a built-in web interface — no separate frontend build required. It includes:

• Dark theme with glass-morphism design matching the API aesthetic
• GitHub URL tab and dependency list tab — paste coordinates directly to scan without cloning
• Live progress bar showing which agent is currently running
• Rendered report with colour-coded severity badges (CRITICAL / HIGH / MEDIUM / LOW), sortable dependency table, and upgrade plan
• History panel — clock icon top-right — browse, reload, or delete any past scan
• Health indicator showing LLM backend connectivity

The frontend is pure HTML, JavaScript, and CSS served directly by FastAPI. Zero build step, zero npm.

API Endpoints

Interactive API documentation is auto-generated at /docs (Swagger UI).

Running It Yourself

The quickest way to try VulnHawk locally:

git clone https://github.com/crewwithravi/scanner.git
cd scanner
cp .env.example .env
# Add your GEMINI_API_KEY to .env

./deploy.sh

The deploy script handles everything — creates the .env interactively if it doesn't exist, builds the Docker image, starts the container, and waits for the health check. Then open http://localhost:8000 in your browser.

To scan without Docker:

pip install -r requirements.txt

LLM_VENDOR=google \
GEMINI_API_KEY=your-api-key \
GOOGLE_MODEL=gemini-2.0-flash \
uvicorn app.main:app --host 0.0.0.0 --port 8000

For full deployment options, scan history persistence, and Docker volume configuration, see the documentation on GitHub.

BOM-Aware Upgrades: How It Works

This is the part of VulnHawk I'm most proud of. For every vulnerable dependency, Agent 3 first checks whether it is managed by the Spring Boot BOM before recommending any version change. Here is what that looks like in the report:

⚠  DO NOT bump tomcat-embed-core directly — it is BOM-managed.

FIX: Upgrade spring-boot 3.2.5 → 3.3.10
     This automatically brings tomcat-embed-core 10.1.30 (≥ safe version).

pom.xml:       <spring-boot.version>3.3.10</spring-boot.version>
build.gradle:  id 'org.springframework.boot' version '3.3.10'

Libraries covered by the BOM resolver:

What's Next

• Support for Gradle multi-project builds — scan each subproject separately
• GitHub Actions integration — post scan results as PR comments
• Private repository support via GitHub token
• Scheduled background re-scans with email / Slack alerts when new CVEs are published for tracked repos
• SBOM export in CycloneDX format

Disclaimer

VulnHawk is an educational and experimental project built for learning and demonstration purposes. It is not production security software. Scan results are a useful starting point but may be incomplete — the OSV and NVD databases have known gaps, and AI-generated upgrade assessments should always be verified independently before being applied to production systems. Always consult a qualified security professional for critical decisions. Use at your own risk.

Full source code, deployment guide, and API docs:
github.com/crewwithravi/scanner

Licensed under MIT · Built with CrewAI, FastAPI, and OSV