DEV Community

Cover image for Introducing Vulnfy: A Lightweight, Multi-Ecosystem Vulnerability Scanner for Your CI/CD Pipeline
wxwreak
wxwreak

Posted on Edited on

Introducing Vulnfy: A Lightweight, Multi-Ecosystem Vulnerability Scanner for Your CI/CD Pipeline

#python #security #opensource #devops

Hey DEV community!👋
As developers, we all know how crucial dependency and container security is. But let's be honest - sometimes heavy enterprise security tools are overkill for side projects, smaller apps, or quick sanity checks. I wanted something lightweight, fast and dead-simple to integrate into Github Actions without complex configurations.

That's why I build Vulnfy - an open-source, cross-platform dependency and container vulnerability scanner written in Python. It automatically detects project configuration and lock files across multiple langs, queries the OSV API in bulk, and alerts you instantly.

What Makes Vulnfy Different?

  • Multi-Ecosystem Support: Whether you're working with Python, Node.js, Go, PHP, Rust, or scanning Docker containers (Dockerfile, docker-compose.yml), Vulnfy has you covered.
  • Batch OSV API Integration: It efficiently checks packages in bulk using the OSV batch query API, keeping scans fast.
  • Instant Notify: Found a CVE? Vulnfy can automatically push security alerts directly to your Discord or Telegram channel.
  • CI/CD Native: It exits with a non-zero status code (sys.exit(1)) if vulnerabilities are detected, making it an ideal drop-in security gate for your pipelines.
  • Structured JSON Output: Exports clean, structured reports (security_report.json) for auditing or further processing.

Supported Ecosystems & Files

Ecosystem Files
Python requirements.txt, pyproject.toml
NPM package.json, package-lock.json
Go go.mod
PHP composer.lock
Rust Cargo.lock, Cargo.toml
Docker Dockerfile, docker-compose.yml

Quick Start & Installation

You can install Vulnfy quickly or pull it directly from Github:

pip install git+https://github.com/wxwreak/vulnfy.git
Enter fullscreen mode Exit fullscreen mode

Or run it locally with a simple command in your project directory:

vulnfy
Enter fullscreen mode Exit fullscreen mode

Github Actions Integration

Adding Vulnfy to your CI/CD workflow takes just a few lines. Create .github/workflows/scan.yaml:

name: Vulnfy Security Scan

on:
  push:
    branches: [ main ]
  workflow_dispatch:

jobs:
  vulnfy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

      - name: Install Vulnfy
        run: pip install git+https://github.com/wxwreak/vulnfy.git

      - name: Run Vulnfy Scanner
        env:
          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
        run: vulnfy --fail-on high
Enter fullscreen mode Exit fullscreen mode

Configuration & Alerts

Want to hook it up to Telegram or Discord? Just drop a vulnfy.yaml file into your root directory:

notifications:
  discord:
    enabled: true   # Set to true for Discord alerts
  telegram:
    enabled: false  # Set to true for Telegram alerts
Enter fullscreen mode Exit fullscreen mode

(And store your webhooks/tokens securely in Github Secrets/.env file).

🚀 Update: Tackling Alert Fatigue!
Huge thanks to the community feedback pointing out that lightweight tools must avoid alert fatigue. Based on that, I've just pushed a fresh update to Vulnfy featuring:1

  • .vulnignore Support: Easily suppress known or temporarily unfixable vulnerabilities by adding their IDs/CVEs to a .vulnignore file in your project's root directory. They won't block your CI or trigger chat notifications.
  • Strict Threshold Alerts: Notifications and CI failures now fire strictly when vulnerabilities match or exceed your configured --fail-on level, keeping clean or ignored codebases completely quiet.

Give it a Try!

Vulnfy is completely open-source, and i'm actively working on improving it.

  • Check out the repo on Github: wxwreak/vulnfy ⭐️
  • Let me know what you think in the comments below!

Top comments (3)

Collapse
 
alexshev profile image
Alex Shev •

A lightweight scanner earns trust when it is easy to run often and hard to ignore when it finds something real. The key is making the output actionable enough that CI failures do not turn into alert fatigue.

Collapse
 
wxwreak profile image
wxwreak •

Spot on feedback. You're absolutely right, making a tool 'actionable' is the only way to avoid alert fatigue.

I’ve just pushed an update to address exactly what you suggested:

  1. .vulnignore support: You can now create a .vulnignore file in your root directory to suppress known or unfixable vulnerabilities. They will be filtered out from CI checks and notifications.
  2. Refined Alert Logic: Notifications and CI failures now only trigger when vulnerabilities match or exceed the --fail-on threshold. This ensures your chats stay quiet when your codebase is clean (or only contains ignored/low-priority issues).

Thanks for the push to make the tool more production-ready!

Collapse
 
alexshev profile image
Alex Shev •

That is exactly the right direction. A vulnignore file is useful only if it is visible enough to review later, and threshold-based CI failures help keep the tool from becoming background noise. The next thing I would watch is whether ignored items carry an owner or expiry date, otherwise permanent exceptions tend to become a second vulnerability list.