securegit 0.8.5

# Plugin Version Management and Update System

## Problem Statement

Security tools become outdated quickly. A plugin installed today may have:
- Critical security vulnerabilities discovered tomorrow
- New detection patterns added for emerging threats
- Bug fixes that reduce false positives
- Performance improvements

**Developer behavior risk:** Users install a plugin once and forget about it, running outdated security scanners that miss new threats or contain known vulnerabilities.

## Solution: Automated Version Tracking and Update Notifications

SecureGit implements a comprehensive plugin lifecycle management system to ensure users always run current, secure plugins.

## Plugin Manifest Format

Each plugin includes a `plugin.json` manifest with version and update information:

```json
{
  "name": "gitleaks",
  "version": "8.21.2",
  "api_version": "1.0.0",
  "description": "Detect hardcoded secrets using gitleaks",
  "author": "SecureGit Community",
  "license": "MIT",
  "homepage": "https://github.com/gitleaks/gitleaks",
  "repository": "https://github.com/gitleaks/gitleaks",
  "update_source": {
    "type": "github_releases",
    "repo": "gitleaks/gitleaks",
    "asset_pattern": "gitleaks_{version}_linux_x64.tar.gz"
  },
  "installed_date": "2026-01-29T22:00:00Z",
  "last_checked": "2026-01-29T22:00:00Z",
  "executable": "gitleaks",
  "requires": [],
  "platforms": ["linux", "darwin", "windows"],
  "tags": ["secrets", "credentials", "api-keys"],
  "severity_if_outdated": "high"
}
```

## Version Registry

SecureGit maintains a local version registry at `~/.config/securegit/plugin-versions.json`:

```json
{
  "plugins": {
    "gitleaks": {
      "installed_version": "8.21.2",
      "installed_date": "2026-01-29T22:00:00Z",
      "last_update_check": "2026-01-29T22:00:00Z",
      "latest_version": "8.21.2",
      "update_available": false,
      "security_advisory": null
    },
    "trivy-config": {
      "installed_version": "0.58.2",
      "installed_date": "2026-01-29T22:00:00Z",
      "last_update_check": "2026-01-29T22:00:00Z",
      "latest_version": "0.60.0",
      "update_available": true,
      "security_advisory": null,
      "changelog_summary": "Added support for Kubernetes 1.30, fixed false positives in Terraform scanning"
    },
    "semgrep": {
      "installed_version": "1.45.0",
      "installed_date": "2026-01-15T10:30:00Z",
      "last_update_check": "2026-01-29T22:00:00Z",
      "latest_version": "1.52.0",
      "update_available": true,
      "security_advisory": {
        "severity": "high",
        "cve": "CVE-2026-1234",
        "description": "Potential code execution via malicious rule files",
        "fixed_in": "1.50.0",
        "published": "2026-01-25T00:00:00Z"
      },
      "changelog_summary": "SECURITY: Fixed CVE-2026-1234 code execution vulnerability. Added 150 new security rules. Performance improvements for large codebases."
    }
  },
  "last_global_check": "2026-01-29T22:00:00Z",
  "check_interval_hours": 24
}
```

## Update Check Commands

### Check for Updates

```bash
# Check all plugins for updates
securegit plugin check-updates

# Check specific plugin
securegit plugin check-updates gitleaks

# Force check (ignore cache)
securegit plugin check-updates --force
```

**Output:**
```
Checking for plugin updates...

✓ gitleaks 8.21.2 - Up to date
⚠ trivy-config 0.58.2 - Update available: 0.60.0
  • Added support for Kubernetes 1.30
  • Fixed false positives in Terraform scanning

⚠ semgrep 1.45.0 - SECURITY UPDATE REQUIRED: 1.52.0
  🚨 CVE-2026-1234 (HIGH): Potential code execution via malicious rule files
  • Fixed in version 1.50.0
  • You are 7 versions behind
  • Changelog:
    - SECURITY: Fixed CVE-2026-1234 code execution vulnerability
    - Added 150 new security rules
    - Performance improvements for large codebases

2 updates available (1 security-critical)
Run 'securegit plugin update --all' to update
```

### Automatic Update Checks

SecureGit automatically checks for updates:
- On startup (if last check > 24 hours ago)
- Before each scan (if last check > 7 days ago)
- Can be configured in `~/.config/securegit/config.toml`

```toml
[plugins]
auto_update_check = true
update_check_interval_hours = 24
notify_on_security_updates = true
block_scan_if_critical_update = false  # Optional: refuse to scan with vulnerable plugins
```

### Update Notification Display

**On Scan Start:**
```
⚠ WARNING: 1 plugin has a security update available

semgrep 1.45.0 is affected by CVE-2026-1234 (HIGH severity)
Run 'securegit plugin update semgrep' to update to 1.52.0

Continuing with scan... (use --require-current-plugins to block)
```

**On Startup:**
```
SecureGit v0.1.0

ℹ 2 plugin updates available (1 security-critical)
  Run 'securegit plugin check-updates' for details
```

## Update Mechanism

### Update Single Plugin

```bash
# Update specific plugin
securegit plugin update gitleaks

# With confirmation prompt
securegit plugin update gitleaks --interactive

# Auto-approve
securegit plugin update gitleaks --yes
```

**Output:**
```
Updating gitleaks...
  Current version: 8.21.2
  Latest version:  8.22.0

Changelog:
  • Added detection for GitLab personal access tokens
  • Improved performance by 30%
  • Fixed false positives in JavaScript files

Download: https://github.com/gitleaks/gitleaks/releases/download/v8.22.0/gitleaks_8.22.0_linux_x64.tar.gz
Size: 8.2 MB

Proceed with update? [y/N]: y

Downloading... ████████████████████ 100%
Verifying checksum... ✓
Backing up current version... ✓
Installing new version... ✓
Testing plugin... ✓

Successfully updated gitleaks to 8.22.0
```

### Update All Plugins

```bash
# Update all plugins
securegit plugin update --all

# Security updates only
securegit plugin update --security-only

# Dry run (show what would be updated)
securegit plugin update --all --dry-run
```

### Automatic Updates

```toml
[plugins]
auto_update = false  # Disabled by default for stability
auto_update_security = true  # Auto-update security fixes only
auto_update_check_interval_hours = 6
```

With `auto_update_security = true`:
```
🔒 Security update available for semgrep (CVE-2026-1234)
   Automatically updating from 1.45.0 to 1.52.0...
   ✓ Update complete
```

## Changelog Summarization

SecureGit fetches and summarizes changelogs from multiple sources:

### Data Sources

1. **GitHub Releases API**
   - Release notes from `/repos/{owner}/{repo}/releases`
   - Parse markdown release notes

2. **Git Tags**
   - Compare git tags between versions
   - Extract commit messages

3. **CHANGELOG.md Files**
   - Parse structured changelog files
   - Follow Keep a Changelog format

4. **Security Advisories**
   - GitHub Security Advisories API
   - CVE databases
   - Vendor security bulletins

### Changelog Processing

**Raw Release Notes:**
```markdown
## What's Changed
* Add support for detecting Azure SAS tokens by @contributor1
* Fix panic when scanning binary files by @contributor2
* Bump dependencies to fix CVE-2026-5678
* Performance: reduce memory usage by 40%
* Add 50 new secret patterns from community submissions

**Full Changelog**: https://github.com/gitleaks/gitleaks/compare/v8.21.0...v8.22.0
```

**Summarized for User:**
```
gitleaks 8.22.0 Release Summary:

Security:
  • Fixed CVE-2026-5678 in dependencies

New Features:
  • Azure SAS token detection
  • 50 new secret detection patterns

Bug Fixes:
  • Prevented crash when scanning binary files

Performance:
  • 40% reduction in memory usage
```

### Smart Summarization

For plugins multiple versions behind, summarize all changes:

```bash
securegit plugin changelog semgrep
```

**Output:**
```
semgrep: Installed 1.45.0, Latest 1.52.0 (7 versions behind)

🚨 CRITICAL SECURITY UPDATES:
  v1.50.0 - Fixed CVE-2026-1234: Code execution via malicious rules

📊 Summary of changes from 1.45.0 to 1.52.0:

Security Fixes: 2
  • CVE-2026-1234: Remote code execution (v1.50.0)
  • CVE-2026-1235: Path traversal in rule loading (v1.48.0)

New Detection Rules: 215
  • Python: 45 new rules
  • JavaScript: 60 new rules
  • Go: 35 new rules
  • Java: 75 new rules

Performance Improvements:
  • 60% faster on large codebases (v1.51.0)
  • Reduced memory usage by 35% (v1.49.0)

Bug Fixes: 23
  • Fixed false positives in React hooks (v1.52.0)
  • Corrected regex matching edge cases (v1.47.0)
  • [...]

Breaking Changes: None

Recommendation: Update immediately due to security vulnerabilities
```

## Security Advisory Integration

### CVE Database Integration

SecureGit checks multiple security advisory sources:

1. **GitHub Security Advisories**
   ```
   GET /repos/{owner}/{repo}/security-advisories
   ```

2. **National Vulnerability Database (NVD)**
   ```
   GET https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch={plugin}
   ```

3. **OSV (Open Source Vulnerabilities)**
   ```
   GET https://api.osv.dev/v1/query
   ```

### Advisory Alert System

When a security advisory is detected:

**Email Notification (if configured):**
```
Subject: [SecureGit Security Alert] Critical Update for semgrep Plugin

A critical security vulnerability has been discovered in the semgrep plugin:

Plugin: semgrep
Installed Version: 1.45.0
Vulnerability: CVE-2026-1234
Severity: HIGH
Description: Potential code execution via malicious rule files

Your installation is affected.

Fixed in version: 1.50.0
Latest version: 1.52.0

Action Required:
Run: securegit plugin update semgrep

For more information:
https://github.com/semgrep/semgrep/security/advisories/GHSA-xxxx-xxxx-xxxx
```

**Terminal Banner:**
```
╔════════════════════════════════════════════════════════════════╗
║  🚨 SECURITY ALERT: Plugin Vulnerability Detected              ║
╟────────────────────────────────────────────────────────────────╢
║  Plugin:      semgrep v1.45.0                                  ║
║  Severity:    HIGH                                             ║
║  CVE:         CVE-2026-1234                                    ║
║  Impact:      Code execution via malicious rule files          ║
║  Fixed in:    v1.50.0                                          ║
║                                                                ║
║  Update now:  securegit plugin update semgrep                  ║
╚════════════════════════════════════════════════════════════════╝
```

### Advisory Severity Levels

```
CRITICAL - Active exploitation, immediate update required
HIGH     - Serious vulnerability, update within 24 hours
MEDIUM   - Security issue, update within 7 days
LOW      - Minor security concern, update at convenience
INFO     - Security-related information, no immediate action
```

## Plugin Deprecation and EOL

### Deprecation Warnings

```json
{
  "name": "old-scanner",
  "version": "2.0.0",
  "deprecated": true,
  "deprecation_reason": "Plugin has been superseded by new-scanner",
  "replacement": "new-scanner",
  "eol_date": "2026-06-01T00:00:00Z"
}
```

**Warning on Use:**
```
⚠ WARNING: Plugin 'old-scanner' is deprecated

This plugin will reach end-of-life on 2026-06-01 and will no longer
receive security updates.

Recommended replacement: new-scanner
Migration guide: https://docs.securegit.dev/migration/old-scanner-to-new-scanner

Install replacement:
  securegit plugin install new-scanner
```

### End-of-Life Enforcement

After EOL date:
```
❌ ERROR: Plugin 'old-scanner' has reached end-of-life

This plugin no longer receives security updates and cannot be used.

Please migrate to: new-scanner
  securegit plugin remove old-scanner
  securegit plugin install new-scanner
```

## Version Pinning

For CI/CD stability, allow version pinning:

```toml
[plugins.gitleaks]
enabled = true
version = "8.21.2"  # Pin to specific version
allow_auto_update = false
warn_if_outdated = true
```

With pinning:
```
ℹ Plugin 'gitleaks' is pinned to v8.21.2

A newer version (8.22.0) is available with security fixes.
Consider updating your pin or removing it.

To update pin:
  Edit ~/.config/securegit/config.toml
  Change: version = "8.22.0"
```

## Update Rollback

If an update causes issues, rollback is available:

```bash
# Rollback to previous version
securegit plugin rollback gitleaks

# Rollback to specific version
securegit plugin rollback gitleaks --to 8.21.2

# List available versions for rollback
securegit plugin versions gitleaks
```

**Output:**
```
Available versions for gitleaks:

  8.22.0 (current) - Installed 2026-01-29
  8.21.2 (backup)  - Previously installed
  8.21.1           - Available from registry
  8.21.0           - Available from registry
  [...]

Rollback to version: 8.21.2
```

## Community Plugin Registry Integration

### Registry Update Feed

Central registry provides update metadata:

```
GET https://registry.securegit.dev/api/v1/plugins/{name}/updates
```

**Response:**
```json
{
  "plugin": "gitleaks",
  "current_version": "8.22.0",
  "update_available": true,
  "security_updates": [],
  "changelog_summary": "Added Azure SAS token detection, 40% memory reduction",
  "release_date": "2026-01-28T00:00:00Z",
  "download_url": "https://github.com/gitleaks/gitleaks/releases/download/v8.22.0/gitleaks_8.22.0_linux_x64.tar.gz",
  "checksum": "sha256:abc123...",
  "signature": "..."
}
```

### Trust and Verification

All plugin updates are verified:
1. **Checksum verification** - SHA256 hash match
2. **GPG signature verification** - Signed by plugin author
3. **Registry signature** - Signed by SecureGit registry
4. **Reproducible builds** - Verify build reproducibility

```bash
securegit plugin verify gitleaks

Verifying gitleaks v8.22.0...
  ✓ Checksum matches registry
  ✓ GPG signature valid (key: 0x1234ABCD)
  ✓ Registry signature valid
  ✓ Build is reproducible
  ✓ No known vulnerabilities

Plugin is verified and safe to use.
```

## Configuration Options

Complete configuration in `~/.config/securegit/config.toml`:

```toml
[plugins]
# Update checking
auto_update_check = true
update_check_interval_hours = 24
check_on_startup = true
check_before_scan = false

# Automatic updates
auto_update = false
auto_update_security = true  # Security updates only
auto_update_interval_hours = 6

# Notifications
notify_updates_available = true
notify_security_advisories = true
notification_method = "terminal"  # terminal, email, webhook

# Security
block_scan_with_vulnerable_plugins = false
require_verified_plugins = true
allow_deprecated_plugins = false

# Registry
registry_url = "https://registry.securegit.dev"
registry_mirror = ""
verify_registry_signatures = true

# Email notifications (if notify_security_advisories = true)
[plugins.notifications.email]
enabled = false
smtp_server = "smtp.example.com"
smtp_port = 587
smtp_user = "alerts@example.com"
smtp_password_env = "SECUREGIT_SMTP_PASSWORD"
recipient = "security-team@example.com"

# Webhook notifications
[plugins.notifications.webhook]
enabled = false
url = "https://hooks.slack.com/services/..."
method = "POST"
```

## Best Practices

### For Users

1. **Enable automatic security updates**
   ```toml
   auto_update_security = true
   ```

2. **Check for updates weekly**
   ```bash
   securegit plugin check-updates
   ```

3. **Subscribe to security advisories**
   - Watch plugin repositories on GitHub
   - Enable email notifications

4. **Test updates in staging first**
   - Don't auto-update in production CI/CD
   - Validate updates with test scans

5. **Pin versions in CI/CD**
   - Ensures reproducible builds
   - Update pins regularly

### For Plugin Developers

1. **Follow semantic versioning**
   - Major: Breaking changes
   - Minor: New features, backward compatible
   - Patch: Bug fixes

2. **Provide detailed changelogs**
   - Use Keep a Changelog format
   - Highlight security fixes
   - Note breaking changes

3. **Publish security advisories**
   - Use GitHub Security Advisories
   - Include CVE IDs
   - Provide mitigation steps

4. **Sign releases**
   - GPG sign all releases
   - Provide checksums
   - Support reproducible builds

5. **Communicate deprecations early**
   - 6+ months notice before EOL
   - Provide migration guides
   - Suggest replacement plugins

## Implementation Roadmap

### Phase 1: Foundation (v0.2.0)
- [x] Plugin manifest format
- [ ] Version registry implementation
- [ ] Basic update checking
- [ ] Manual update command

### Phase 2: Automation (v0.3.0)
- [ ] Automatic update checks
- [ ] Changelog fetching and parsing
- [ ] Update notifications
- [ ] Security advisory integration

### Phase 3: Intelligence (v0.4.0)
- [ ] Changelog summarization
- [ ] CVE database integration
- [ ] Email/webhook notifications
- [ ] Automatic security updates

### Phase 4: Registry (v0.5.0)
- [ ] Central plugin registry
- [ ] Trust and verification
- [ ] Community ratings
- [ ] Plugin marketplace

## Metrics and Monitoring

Track plugin health across installations:

```bash
securegit plugin stats

Plugin Statistics:
  Total plugins: 8
  Up to date: 6 (75%)
  Updates available: 2 (25%)
  Security updates: 1 (12.5%)
  Deprecated: 0
  End-of-life: 0

Average age: 14 days
Oldest plugin: semgrep (45 days old, 7 versions behind)

Recommendation: Update 2 plugins (1 security-critical)
```

## Conclusion

A robust version management system ensures SecureGit remains an effective security tool over time. By proactively notifying users of updates, especially security-critical ones, we prevent the "comfortable with old version" syndrome that undermines security scanning effectiveness.

The combination of automatic checking, clear notifications, easy updates, and security advisory integration creates a sustainable ecosystem where plugins stay current and effective against evolving threats.