securegit 0.8.5

# User Guide: Plugin Management

## Quick Start

### Install a Plugin

```bash
# From community registry
securegit plugin install gitleaks

# From GitHub URL
securegit plugin install https://github.com/securegit-plugins/gitleaks.git

# From local path
securegit plugin install ./my-custom-plugin
```

### Check for Updates

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

# Check specific plugin
securegit plugin check-updates gitleaks
```

### Update Plugins

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

# Update specific plugin
securegit plugin update gitleaks

# Update security fixes only
securegit plugin update --security-only
```

## Understanding Plugin Versions

### Version Display

```bash
# List installed plugins with versions
securegit plugin list
```

**Output:**
```
Installed Plugins:

Built-in Plugins (5):
  ✓ secrets       1.0.0  Hardcoded secret detection
  ✓ patterns      1.0.0  Dangerous code patterns
  ✓ entropy       1.0.0  High entropy content detection
  ✓ binary        1.0.0  Binary file detection
  ✓ git-internals 1.0.0  Git repository threat scanning

External Plugins (4):
  ✓ gitleaks       8.22.0   (up to date)
    Secret detection with gitleaks
    Updated: 2 days ago

  ⚠ trivy-config   0.58.2   (update available: 0.60.0)
    Container/IaC misconfiguration scanner
    Updated: 15 days ago
    Behind: 12 commits

  🚨 semgrep        1.45.0   (SECURITY UPDATE: 1.52.0)
    Multi-language SAST scanner
    Updated: 45 days ago
    Behind: 87 commits
    Security: CVE-2026-1234 (HIGH)

  ✓ todo-scanner   1.0.0    (up to date)
    Development comment detection
    Updated: 1 day ago
```

### Version Information

```bash
# Detailed version info for a plugin
securegit plugin info gitleaks
```

**Output:**
```
Plugin: gitleaks

Current Version: 8.22.0
Latest Version:  8.22.0
Status:          Up to date ✓

Description:     Detect hardcoded secrets using gitleaks
Author:          SecureGit Community
License:         MIT
Repository:      https://github.com/securegit-plugins/gitleaks.git
Homepage:        https://github.com/gitleaks/gitleaks

Installed:       2026-01-27 (2 days ago)
Last Checked:    2026-01-29 (Today)
Last Updated:    2026-01-27 (2 days ago)

Git Information:
  Commit:        a1b2c3d4
  Branch:        main
  Remote:        https://github.com/securegit-plugins/gitleaks.git

Capabilities:
  File Types:    All text files
  Languages:     All
  Scan Phase:    Post-extract
  Severity:      Critical findings
  Performance:   ~50ms per file

Statistics:
  Total Scans:   142
  Findings:      23
  Last Run:      2026-01-29 10:30:00
```

## Staying Up to Date

### Daily Workflow

**Morning routine:**
```bash
# Start your day with a quick check
securegit plugin check-updates

# If updates available:
securegit plugin update --all
```

### Enable Automatic Checks

Edit `~/.config/securegit/config.toml`:

```toml
[plugins]
auto_update_check = true              # Check on startup
update_check_interval_hours = 24      # Once per day
notify_updates_available = true       # Show notification
```

With this enabled:
```bash
# Any securegit command shows update notifications
securegit scan /path/to/code

SecureGit Security Scan

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

[Scan continues...]
```

### Security Update Alerts

Get immediate alerts for security-critical updates:

```toml
[plugins]
notify_security_advisories = true
block_scan_with_vulnerable_plugins = false  # Set to true to enforce updates
```

**With blocking enabled:**
```bash
securegit scan /path/to/code

❌ ERROR: Cannot scan with vulnerable plugins

Plugin 'semgrep' has a critical security vulnerability:
  CVE-2026-1234 (HIGH severity)
  Your version: 1.45.0
  Fixed in:     1.50.0

Update required before scanning:
  securegit plugin update semgrep

To scan anyway (not recommended):
  securegit scan --allow-vulnerable-plugins /path/to/code
```

## Understanding Changelogs

### View What Changed

```bash
# See what's new in an update
securegit plugin changelog semgrep
```

**Output:**
```
Changelog: semgrep 1.45.0 → 1.52.0

You are 87 commits behind the latest version.

🚨 CRITICAL SECURITY UPDATES (2):

  v1.50.0 (2026-01-25)
    CVE-2026-1234: Remote code execution via malicious rules
    ⚠ HIGH severity - Update immediately

    Impact: Malicious rule files could execute arbitrary code
    during parsing, potentially compromising your system.

    Mitigation: Upgrade to v1.50.0 or later.

  v1.48.0 (2026-01-20)
    CVE-2026-1235: Path traversal in rule loading
    ⚠ MEDIUM severity

✨ NEW FEATURES (8):

  v1.52.0 - Added 60 new JavaScript security rules
    • React hooks security patterns
    • Next.js API route vulnerabilities
    • Express.js input validation

  v1.51.0 - Parallel scanning (60% faster)
    • Multi-core utilization
    • Configurable worker count

  v1.49.0 - Python 3.12 support
    • New syntax patterns
    • Type hint security checks

  [Show 5 more features...]

🐛 BUG FIXES (15):

  v1.52.0 - Fixed false positives in React hooks
  v1.51.0 - Corrected regex matching edge cases
  v1.50.0 - Fixed crash when scanning binary files
  [Show 12 more fixes...]

⚡ PERFORMANCE IMPROVEMENTS (3):

  v1.51.0 - 60% faster on large codebases
    • Optimized pattern matching
    • Reduced memory allocations

  v1.49.0 - 35% memory usage reduction
    • Improved rule caching
    • Lazy loading of patterns

  v1.46.0 - Faster rule compilation

Recommendation: UPDATE IMMEDIATELY (security vulnerabilities)

Update command:
  securegit plugin update semgrep

Full git history:
  cd ~/.config/securegit/plugins/semgrep
  git log v1.45.0..v1.52.0
```

### Smart Changelog Summaries

SecureGit categorizes and prioritizes changes:

1. **Security fixes** - Always shown first, highlighted
2. **Breaking changes** - Important for CI/CD
3. **New features** - What you gain from updating
4. **Bug fixes** - What problems are resolved
5. **Performance** - Speed/memory improvements

### Get More Details

```bash
# Full git commit history
cd ~/.config/securegit/plugins/semgrep
git log

# Specific version range
git log v1.45.0..v1.52.0

# One-line summary
git log --oneline v1.45.0..v1.52.0

# Show file changes
git log --stat v1.45.0..v1.52.0
```

## Handling Updates

### Safe Update Process

**1. Check what will change:**
```bash
securegit plugin changelog semgrep
```

**2. Test in a sandbox first:**
```bash
# Create test directory
mkdir /tmp/plugin-test

# Update in test environment
SECUREGIT_CONFIG_DIR=/tmp/plugin-test securegit plugin update semgrep

# Test the update
SECUREGIT_CONFIG_DIR=/tmp/plugin-test securegit scan /path/to/test/code

# If successful, update production
securegit plugin update semgrep
```

**3. Update with confirmation:**
```bash
# Interactive mode (prompts before updating)
securegit plugin update --interactive
```

**Output:**
```
Update available for semgrep

Changes (1.45.0 → 1.52.0):
  🚨 2 security fixes (including CVE-2026-1234)
  ✨ 8 new features
  🐛 15 bug fixes
  ⚡ 60% faster performance

This update includes critical security fixes.

Proceed with update? [Y/n]: y

Updating semgrep...
✓ Downloaded v1.52.0
✓ Installed successfully
✓ Verified plugin integrity

Successfully updated semgrep to 1.52.0

Test the update:
  securegit scan --plugin semgrep /path/to/test
```

### Rollback if Needed

If an update causes problems:

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

# Rollback to specific version
securegit plugin rollback semgrep --to 1.45.0

# List available versions
securegit plugin versions semgrep
```

**Output:**
```
Rolling back semgrep from 1.52.0 to 1.45.0...

⚠ Warning: Version 1.45.0 has known security vulnerability CVE-2026-1234

Are you sure you want to rollback? [y/N]: y

Checking out version 1.45.0...
✓ Rollback complete

Reason for rollback (optional): New version causes false positives in our codebase

Rollback recorded for feedback to plugin maintainer.

Note: You are now running an outdated version with known vulnerabilities.
Consider reporting the issue and waiting for a fix rather than staying on old version.
```

## CI/CD Best Practices

### Pin Versions in CI

For reproducible builds, pin plugin versions:

**~/.config/securegit/config.toml** (in CI):
```toml
[plugins.gitleaks]
enabled = true
version = "8.22.0"            # Specific version
allow_auto_update = false     # Don't auto-update in CI

[plugins.semgrep]
enabled = true
version = "1.52.0"
allow_auto_update = false
```

**In CI pipeline:**
```yaml
# .github/workflows/security-scan.yml
- name: Security Scan
  run: |
    # Install specific versions
    securegit plugin install gitleaks --version 8.22.0
    securegit plugin install semgrep --version 1.52.0

    # Scan (won't auto-update)
    securegit scan . --fail-on high
```

### Update Pins Regularly

Don't let pinned versions get too old:

```bash
# Check how old your pins are
securegit plugin check-updates --show-pinned
```

**Output:**
```
Pinned Plugin Versions:

⚠ gitleaks pinned to 8.22.0
  Latest: 8.25.0
  Age: 45 days
  Status: 3 versions behind, no security issues

🚨 semgrep pinned to 1.52.0
  Latest: 1.60.0
  Age: 60 days
  Status: 8 versions behind, 1 SECURITY UPDATE

  CVE-2026-5678 (MEDIUM) fixed in v1.58.0
  Recommendation: Update pin to 1.60.0 or later

Update your pin in config.toml:
  [plugins.semgrep]
  version = "1.60.0"
```

### Scheduled CI Updates

Weekly job to check for updates:

```yaml
# .github/workflows/plugin-updates.yml
name: Check Plugin Updates
on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9am

jobs:
  check-updates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check for plugin updates
        run: |
          securegit plugin check-updates --json > updates.json

      - name: Create issue if security updates available
        if: contains(steps.check.outputs.*, 'security')
        uses: actions/github-script@v6
        with:
          script: |
            const updates = require('./updates.json');
            const security = updates.filter(u => u.security_advisory);

            if (security.length > 0) {
              github.rest.issues.create({
                owner: context.repo.owner,
                repo: context.repo.repo,
                title: `🚨 Security Updates Available for ${security.length} Plugin(s)`,
                body: formatUpdates(security),
                labels: ['security', 'dependencies']
              });
            }
```

## Troubleshooting Updates

### Update Fails

**Problem: Update download fails**
```
Error: Failed to download plugin update
Connection timeout
```

**Solution:**
```bash
# Check network connectivity
curl -I https://github.com

# Try with different mirror
securegit plugin update gitleaks --mirror https://mirror.example.com

# Manual download and install
curl -L https://github.com/gitleaks/gitleaks/releases/download/v8.22.0/gitleaks_8.22.0_linux_x64.tar.gz -o gitleaks.tar.gz
securegit plugin install ./gitleaks.tar.gz
```

**Problem: Checksum verification fails**
```
Error: Checksum mismatch
Expected: abc123...
Got:      def456...
```

**Solution:**
```bash
# Download may be corrupted, try again
securegit plugin update gitleaks --force-download

# If persistent, check for man-in-the-middle
curl -v https://github.com | grep -i ssl

# Verify checksum manually
sha256sum ~/.config/securegit/plugins/gitleaks/gitleaks
```

**Problem: Update breaks existing scans**
```
Error: Plugin execution failed
semgrep: invalid rule format
```

**Solution:**
```bash
# Rollback immediately
securegit plugin rollback semgrep

# Check if it's a configuration issue
securegit plugin verify semgrep

# Report bug to plugin maintainer
securegit plugin report-issue semgrep "Update to 1.52.0 breaks rule format"
```

### Version Conflicts

**Problem: Two plugins require different versions of a tool**
```
⚠ Version conflict detected

Plugin 'semgrep-custom' requires semgrep >= 1.50.0
Plugin 'legacy-scanner' requires semgrep <= 1.45.0

Cannot satisfy both requirements.
```

**Solution:**
```bash
# Option 1: Update legacy plugin
securegit plugin update legacy-scanner

# Option 2: Disable one plugin
securegit plugin disable legacy-scanner

# Option 3: Use plugin profiles
securegit scan --profile modern  # Uses semgrep 1.50.0+
securegit scan --profile legacy  # Uses semgrep 1.45.0
```

## Plugin Health Monitoring

### Check Plugin Health

```bash
securegit plugin health
```

**Output:**
```
Plugin Health Report

Overall Status: ⚠ Attention Needed

Built-in Plugins: ✓ Healthy (5/5)
External Plugins: ⚠ Issues (2/4)

Detailed Status:

✓ gitleaks
  Version: 8.22.0 (current)
  Last scan: 2 hours ago
  Success rate: 100% (142/142 scans)
  Avg execution time: 45ms

⚠ trivy-config
  Version: 0.58.2 (update available: 0.60.0)
  Last scan: 1 day ago
  Success rate: 98% (95/97 scans)
  Avg execution time: 120ms
  Note: 2 failed scans due to timeout

🚨 semgrep
  Version: 1.45.0 (SECURITY UPDATE REQUIRED)
  Last scan: 15 days ago
  Success rate: 100% (89/89 scans)
  Avg execution time: 2.3s
  Issue: CVE-2026-1234 vulnerability

✓ todo-scanner
  Version: 1.0.0 (current)
  Last scan: 3 hours ago
  Success rate: 100% (156/156 scans)
  Avg execution time: 18ms

Recommendations:
  1. Update semgrep immediately (security vulnerability)
  2. Update trivy-config to reduce timeouts
  3. All plugins functioning normally otherwise

Run 'securegit plugin update --all' to resolve issues.
```

### Set Update Reminders

```toml
[plugins.reminders]
enabled = true
check_interval_days = 7
notify_method = "terminal"  # terminal, email, webhook

# Custom reminder schedule per plugin
[plugins.reminders.semgrep]
check_interval_days = 1  # Check daily for critical tools
```

## Summary

### Daily Habits

- Run `securegit plugin check-updates` weekly
- Enable `auto_update_check = true` for notifications
- Review changelogs before updating
- Test updates before deploying to CI/CD

### Security Priorities

- Update security-critical plugins immediately
- Subscribe to security advisories
- Don't ignore update notifications
- Report issues if updates break functionality

### Best Practices

- Pin versions in CI/CD
- Test updates in staging first
- Keep update pins current (< 30 days old)
- Monitor plugin health regularly
- Rollback if needed, but don't stay on old versions

The goal: **Always run current, secure versions without breaking your workflow.**