go-flush 🚀

Go Module Dependency Health Checker - A powerful CLI tool that analyzes your Go project's dependencies for security vulnerabilities, outdated versions, and license compliance using real-time data from the OSV database.

✨ Features

• 🔒 Real Vulnerability Scanning - Uses the OSV (Open Source Vulnerability) database API - the same database GitHub Dependabot uses
• 📦 Version Update Detection - Identifies outdated packages with severity levels (major/minor/patch)
• 📜 License Detection - Automatically detects common open source licenses
• ⚡ Concurrent Analysis - Fast parallel processing with goroutines
• 🎨 Beautiful Output - Colored terminal output with progress bars
• 💯 Health Scoring - Overall dependency health score (0-100)
• 🎯 Real CVE Detection - Finds actual CVEs like CVE-2020-26160, CVE-2020-14040, etc.

🎬 The "Wow" Moment

When you run go-flush on a vulnerable project, it detects REAL CVEs:

🚨 Security Issues Found: 3
  • github.com/dgrijalva/jwt-go v3.2.0 - CVE-2020-26160
    Fix: upgrade to latest version
  • golang.org/x/text v0.3.0 - CVE-2020-14040
    Fix: upgrade to latest version

CVE-2020-26160 is an authentication bypass vulnerability that affected thousands of production systems!

📥 Installation

From Source

# Clone the repository
git clone https://github.com/DesmondSanctity/go-flush.git
cd go-flush

# Build the binary
go build -o go-flush main.go

# Optional: Install globally
go install

Quick Install

go install github.com/DesmondSanctity/go-flush@latest

🚀 Usage

Basic Usage

# Run in current directory (scans ./go.mod)
./go-flush

# Or if installed globally
go-flush

CLI Flags

# Scan a different directory
go-flush -path /path/to/project

# Output as JSON (for CI/CD integration)
go-flush -json

# Filter by vulnerability severity
go-flush -severity high

# Fail with exit code 1 if vulnerabilities found (CI/CD)
go-flush -fail-on-vuln

# Verbose output with detailed information
go-flush -verbose

Example Output

📦 Go Dependency Health Checker
══════════════════════════════════════════════════
🔍 Found 15 dependencies

Analyzing 100% [████████████████████████████████] (15/15)

✅ No security vulnerabilities found

📈 Outdated Packages: 3
  • github.com/gin-gonic/gin: v1.9.0 → v1.9.1 [patch]
  • github.com/spf13/cobra: v1.7.0 → v1.8.0 [minor]
  • golang.org/x/sys: v0.10.0 → v0.15.0 [minor]

📜 License Summary:
  • MIT: 8 packages
  • BSD-3-Clause: 5 packages
  • Apache-2.0: 2 packages

Health Score: 85/100
📋 Some updates recommended

🧪 Testing with Vulnerable Projects

We provide test data to demonstrate the tool's vulnerability detection:

# Test on the vulnerable sample project
go-flush -path testdata/vulnerable-project

# Expected: Will find CVE-2020-26160 and other real CVEs

🎯 Perfect for Demos & Live Coding

This tool is designed to be impressive in a 30-minute live coding session:

1. Start Strong: Show the final result finding real CVEs
2. Build Momentum: Walk through the code structure
3. The Wow Moment: Demonstrate OSV API integration
4. Finish Strong: Run on a real vulnerable project

🏗️ How It Works

1. Parse go.mod - Extracts direct dependencies
2. Concurrent Analysis - Processes up to 5 dependencies in parallel
3. Version Checking - Uses go list -m -json pkg@latest
4. Vulnerability Scanning - Queries OSV API for each package/version
5. License Detection - Pattern matching against known licenses
6. Health Scoring - Calculates overall project health

🔧 API Integration

OSV Database API

POST https://api.osv.dev/v1/query
{
  "package": {
    "name": "github.com/dgrijalva/jwt-go",
    "ecosystem": "Go"
  },
  "version": "v3.2.0"
}

Returns real CVEs with IDs, descriptions, severity levels, and fix recommendations.

📊 Health Score Calculation

Base Score: 100
- Vulnerabilities: -20 points each
- Outdated packages: -5 points each

90-100: 🎉 Excellent
70-89:  📋 Good (some updates recommended)
0-69:   ⚠️  Needs attention

🛠️ Development

Code Quality

This project maintains high code quality standards with multiple linters:

# Format code
make fmt

# Run all linters
make lint

# Run specific linters
make vet            # go vet
make staticcheck    # staticcheck
make golangci-lint  # golangci-lint

# Build
make build

# Run tests
make test

Linters Configured

• go fmt - Code formatting
• go vet - Suspicious constructs
• staticcheck - Advanced static analysis
• golangci-lint - Comprehensive linting (30+ linters)
  • errcheck, gosimple, ineffassign, unused
  • revive, misspell, gosec, goconst
  • gocyclo, gocognit, dupl, and more

See .golangci.yml for full configuration.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

All PRs must pass linting and tests.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OSV.dev - For the amazing vulnerability database API
• golang.org/x/mod - For go.mod parsing
• fatih/color - For beautiful colored output
• schollz/progressbar - For progress bars

🎓 Use Cases

• Security Audits - Regular dependency scanning
• CI/CD Integration - Automated vulnerability detection
• Live Demos - Show real security scanning capabilities
• Learning Tool - Understand Go module security
• Project Health Checks - Regular maintenance scanning

🚦 Exit Codes

• 0 - Success (no vulnerabilities or when not using -fail-on-vuln)
• 1 - Error or vulnerabilities found (when using -fail-on-vuln)

📞 Support

Found a bug? Have a feature request? Please open an issue.

---

Built with ❤️ for the Go community

Detecting real vulnerabilities, protecting real projects 🛡️