Vulnguard

Multi-language dependency security scanner and health monitor. Catch vulnerabilities before they catch you.

Overview

Vulnguard is a powerful CLI tool that scans your project dependencies across multiple package managers (npm, Maven, Gradle) and checks them against vulnerability databases to identify security issues before they reach production.

Features

🚀 NEW in v0.2.0: Dependency Health Intelligence System

The ONLY scanner that goes beyond CVEs!

• 🎯 Trust Score System: Comprehensive 0-100 scoring across 4 dimensions
  • Security (OpenSSF Scorecard integration)
  • Maintenance (Update frequency & activity)
  • Community (Downloads, stars, adoption)
  • Vulnerability Track (Historical security)
• 🔍 OpenSSF Scorecard Integration: Industry-first for npm scanners - analyzes security best practices
• 💡 Intelligent Insights: Auto-generated explanations like "Actively maintained with 70.3M weekly downloads"
• 🎨 Visual Trust Badges: ✓ TRUSTED, ⚠ MODERATE, ✗ HIGH RISK

Core Features

• Multi-Language Support: Scan npm (package.json), Maven (pom.xml), and Gradle (build.gradle) projects
• CVE Detection: Integration with OSV (Open Source Vulnerabilities) database for real-time vulnerability checking
• Beautiful CLI Output: Color-coded security scores and severity indicators
• Multiple Report Formats: Generate reports in JSON, Markdown, or interactive console format
• Batch Scanning: Scan entire project directories automatically
• Fast & Lightweight: Written in TypeScript with minimal dependencies

Installation

Global Installation

npm install -g vulnguard

Using npx (No Installation Required)

npx vulnguard scan

Local Development

git clone https://github.com/racha24/dependency-guardian.git
cd dependency-guardian
npm install
npm run build

Usage

Basic Scan

Scan the current directory:

vulnguard scan

Scan Specific File

vulnguard scan /path/to/package.json
vulnguard scan /path/to/pom.xml

Scan Entire Project

vulnguard scan /path/to/project

Options

vulnguard scan [options] [path]

Options:
  -f, --format <type>    Output format: console, json, markdown (default: "console")
  -o, --output <path>    Output file path (for json/markdown formats)
  -v, --verbose          Show detailed vulnerability information
  --dev                  Include dev dependencies in scan
  -h, --help             Display help

Examples

Verbose console output:

vulnguard scan . --verbose

Generate JSON report:

vulnguard scan . --format json --output report.json

Generate Markdown report:

vulnguard scan . --format markdown --output SECURITY.md

Include dev dependencies:

vulnguard scan . --dev --verbose

Output Example

══════════════════════════════════════════════════════════════════════
  Vulnguard - Security Scan Report
══════════════════════════════════════════════════════════════════════

Scan Time: 10/2/2025, 2:25:02 PM
Project: /Users/user/my-project

┌─────────────────────────┬───────┐
│ Metric                  │ Count │
├─────────────────────────┼───────┤
│ Total Dependencies      │ 25    │
│ Vulnerable Dependencies │ 3     │
│ Critical Issues         │ 1     │
│ High Issues             │ 2     │
│ Medium Issues           │ 4     │
│ Low Issues              │ 1     │
└─────────────────────────┴───────┘

⚠ Found 3 vulnerable dependencies:

📦 [email protected]
   Ecosystem: npm | Trust Score: 76/100 ⚠ MODERATE
   ├─ Security: 50/100
   ├─ Maintenance: 100/100
   ├─ Community: 85/100
   └─ Vulnerability Track: 85/100
   📊 Key Insights:
      • Actively maintained with frequent updates
      • Widely used (70.3M weekly downloads)

    HIGH  GHSA-8hc4-vh64-cxmj
   Server-Side Request Forgery in axios

──────────────────────────────────────────────────────────────────────
✓ Overall Health Score: 92/100 - Good
──────────────────────────────────────────────────────────────────────

Supported Package Managers

| Package Manager | File | Status | |----------------|------|--------| | npm | package.json | ✅ Supported | | Maven | pom.xml | ✅ Supported | | Gradle | build.gradle, build.gradle.kts | 🚧 Coming Soon | | Python pip | requirements.txt, Pipfile | 🚧 Coming Soon | | Rust Cargo | Cargo.toml | 🚧 Coming Soon |

Vulnerability Data Sources

• OSV (Open Source Vulnerabilities): Primary vulnerability database
• Supports CVE, GHSA, and other advisory IDs
• Real-time API queries for up-to-date information

Architecture

src/
├── cli.ts              # Main CLI entry point
├── parsers/            # Package file parsers
│   ├── npm-parser.ts
│   ├── maven-parser.ts
│   └── index.ts
├── scanners/           # Vulnerability scanners
│   ├── osv-scanner.ts
│   ├── vulnerability-scanner.ts
│   └── index.ts
├── reporters/          # Output formatters
│   ├── console-reporter.ts
│   ├── json-reporter.ts
│   ├── markdown-reporter.ts
│   └── index.ts
├── types/              # TypeScript interfaces
│   └── index.ts
└── utils/              # Helper functions
    └── file-finder.ts

Development

Setup

npm install

Build

npm run build

Run in Development

npm run dev  # Watch mode
npm start    # Run CLI

Testing

npm test

Linting

npm run lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

• [ ] Add Gradle parser support
• [ ] Add Python pip support
• [ ] Add Rust Cargo support
• [ ] Add GitHub Advisory database integration
• [ ] Add NVD API integration
• [ ] Implement caching for faster scans
• [ ] Add CI/CD integration (GitHub Actions, GitLab CI)
• [ ] Support for lock files (package-lock.json, yarn.lock)
• [ ] Add fix suggestions and auto-update capabilities
• [ ] Web dashboard for visualization

License

Apache 2.0 - see LICENSE file for details.

Support

• Report issues: GitHub Issues
• Documentation: Wiki

Acknowledgments

• OSV (Open Source Vulnerabilities) for vulnerability data
• The open-source security community

Stay secure! 🛡️