🛡️ DepGuard AI

AI-powered dependency security & compatibility analyzer Analyze upgrades, detect breaking changes, check CVEs, and generate rich Markdown reports.

---

✨ Features

• SemVer classification — AUTO detects MAJOR / MINOR / PATCH / pre-release upgrades
• Release notes fetching — PyPI, GitHub Releases, npm registry, CHANGELOG.md scraping
• LLM reasoning — Pluggable local (Ollama, LM Studio, llama.cpp) or cloud (Claude API) backends
• CVE checking — OSV.dev + NVD + GitHub Advisory Database
• Rich Markdown reports — CVE tables, before/after code examples, migration guides
• CLI mode — Analyze a .txt file of upgrades
• GitHub PR mode — Parse PR diffs and auto-detect dependency changes
• Webhook mode — Flask server for GitHub Actions integration

---

🚀 Quick Start

1. Install

git clone https://github.com/your-org/depguard
cd depguard
pip install -r requirements.txt

2. Configure

Edit config.yaml to choose your LLM backend:

llm:
  provider: ollama   # ollama | lmstudio | llamacpp | claude
  ollama:
    model: mistral   # or llama3, codellama, deepseek-coder

3. Start Ollama (recommended)

ollama pull mistral
ollama serve

4. Analyze

# From a text file
python main.py analyze tests/fixtures/sample_deps.diff

# From a GitHub PR URL
python main.py pr https://github.com/owner/repo/pull/123

# From a PR number
python main.py pr 123 --repo owner/repo

---

📥 Input Formats

Text File Mode

Create a .txt file with one upgrade per line:

# package_name  old_version  new_version
requests        2.28.0       2.31.0
flask           2.3.0        3.0.0
django          3.2.0        4.2.0
pydantic        1.10.0       2.0.0

python main.py analyze my_upgrades.txt --verbose

GitHub PR Mode

# Using full URL
python main.py pr https://github.com/owner/repo/pull/456

# Using PR number + repo
python main.py pr 456 --repo owner/repo

Set GITHUB_TOKEN for higher rate limits and GitHub Advisory access:

export GITHUB_TOKEN=ghp_xxxx

---

🤖 LLM Backends

Configure in config.yaml → llm.provider:

Provider	Config Key	Notes
Ollama (recommended)	ollama	Free, local, run ollama serve
LM Studio	lmstudio	OpenAI-compat on port 1234
llama.cpp server	llamacpp	OpenAI-compat on port 8080
Claude API	claude	Cloud, requires ANTHROPIC_API_KEY

Override provider at runtime

python main.py analyze deps.txt --provider claude
python main.py analyze deps.txt --provider lmstudio

Ollama model options

ollama pull mistral         # General purpose, fast
ollama pull llama3          # Strong reasoning
ollama pull codellama       # Code-focused
ollama pull deepseek-coder  # Excellent for code analysis

---

🛡️ CVE Sources

Source	Key Required	Notes
OSV.dev	No	Primary, always queried
GitHub Advisory DB	GITHUB_TOKEN	GraphQL API
NVD (NIST)	Optional NVD_API_KEY	Auto-queried with key

export GITHUB_TOKEN=ghp_xxxx
export NVD_API_KEY=xxxx-xxxx  # Optional, increases NVD rate limit

---

📄 Report Format

Reports are saved to ./reports/ as Markdown:

## 📦 `requests`: 2.28.0 → 2.31.0

### 🏷️ Update Type
🟢 PATCH — Patch version bump (0 → 31) — bug/security fix, likely safe

### 📋 Release Notes Summary
_(Source: github_releases)_

### 🔍 Change Analysis
**Breaking Changes:** No ✅
**Reasoning:** This is a patch release focusing on security fixes...

### 🔧 Migration Guide
No code changes required for this patch upgrade...

### 🛡️ Security & CVE Analysis
| CVE ID | Severity | CVSS | Status | Description |
|--------|----------|------|--------|-------------|
| CVE-2023-32681 | 🟡 MEDIUM | 6.1 | ✅ Fixed in new version | Requests forwards... |

### ✅ Recommendation: **UPGRADE**
Safe patch upgrade with security fix. Recommend immediate upgrade.

---

🔗 GitHub Actions Webhook

Start the webhook server

export GITHUB_TOKEN=ghp_xxxx
export WEBHOOK_SECRET=your_secret
python main.py webhook --port 5000

GitHub Actions workflow

# .github/workflows/depguard.yml
name: DepGuard Dependency Check
on:
  pull_request:
    paths:
      - 'requirements*.txt'
      - 'pyproject.toml'
      - 'package.json'

jobs:
  depguard:
    runs-on: ubuntu-latest
    steps:
      - name: Notify DepGuard
        run: |
          curl -X POST https://your-server.com/webhook \
            -H "X-GitHub-Event: pull_request" \
            -H "X-Hub-Signature-256: sha256=${{ secrets.WEBHOOK_SECRET }}" \
            -d '{"action":"opened","pull_request":{"number":${{ github.event.pull_request.number }}},"repository":{"full_name":"${{ github.repository }}"}}'

---

🗂️ Project Structure

depguard/
├── main.py                  # CLI entrypoint (Click)
├── config.yaml              # All configuration
├── requirements.txt
├── README.md
│
├── core/
│   ├── parser.py            # Parse txt files and GitHub PR diffs
│   ├── semver_classifier.py # SemVer classification
│   ├── release_fetcher.py   # PyPI / GitHub / npm / CHANGELOG
│   ├── cve_checker.py       # OSV + NVD + GitHub Advisory
│   ├── report_generator.py  # Markdown report builder
│   └── pipeline.py          # Orchestrates the full pipeline
│
├── llm/
│   ├── __init__.py          # Provider factory
│   ├── base.py              # BaseLLMProvider + prompt engineering
│   ├── ollama_provider.py   # Ollama integration
│   ├── lmstudio_provider.py # LM Studio / llama.cpp
│   └── claude_provider.py   # Anthropic Claude API
│
├── github/
│   ├── pr_parser.py         # GitHub PR diff extraction
│   └── webhook_handler.py   # Flask webhook server
│
└── tests/
    ├── test_parser.py
    ├── test_cve_checker.py
    └── fixtures/
        └── sample_deps.txt

---

🧪 Running Tests

pip install pytest
pytest tests/ -v

---

⚙️ Environment Variables

Variable	Required	Description
GITHUB_TOKEN	Optional	GitHub API token (higher rate limits + Advisory DB)
ANTHROPIC_API_KEY	If using Claude	Anthropic API key
NVD_API_KEY	Optional	NVD API key (higher rate limits)
WEBHOOK_SECRET	If using webhook	GitHub webhook HMAC secret

---

📋 CLI Reference

Usage: python main.py [COMMAND] [OPTIONS]

Commands:
  analyze    Analyze dependency upgrades from a TXT file
  pr         Analyze dependency changes in a GitHub Pull Request
  webhook    Start the GitHub Actions webhook server

Options for 'analyze':
  -c, --config PATH      Path to config.yaml [default: config.yaml]
  -o, --output PATH      Output Markdown report path
  -v, --verbose          Show detailed per-step output
  -p, --provider TEXT    Override LLM provider

Options for 'pr':
  -r, --repo TEXT        GitHub repo (owner/name)
  -c, --config PATH      Path to config.yaml
  -o, --output PATH      Output Markdown report path
  -v, --verbose          Show detailed per-step output
  -p, --provider TEXT    Override LLM provider

---

📝 License

MIT