securegit 0.8.5

# SecureGit Plugin Ecosystem

## Overview

SecureGit provides a flexible plugin architecture that combines the performance of built-in Rust plugins with the versatility of external tool integration. This hybrid approach enables the security community to leverage decades of existing security tools while maintaining the speed and safety of a modern Rust implementation.

## Architecture Components

### 1. Built-in Plugins (Rust)
- **Location:** Compiled into the securegit binary
- **Performance:** Sub-millisecond execution
- **Examples:** secrets, patterns, entropy, binary, git-internals
- **Development:** Requires Rust knowledge, changes need recompilation

### 2. External Plugins (Any Language)
- **Location:** ~/.config/securegit/plugins/
- **Performance:** 20-50ms startup overhead
- **Examples:** gitleaks, bandit, semgrep, clamav, yara
- **Development:** Any language with executable output

### 3. Native Dynamic Plugins (Rust + FFI)
- **Location:** ~/.config/securegit/plugins/*.so
- **Performance:** Near-native speed with dynamic loading
- **Examples:** Custom Rust plugins distributed as shared libraries
- **Development:** Requires Rust + C FFI, advanced users

### 4. WebAssembly Plugins (Future)
- **Location:** ~/.config/securegit/plugins/*.wasm
- **Performance:** Fast, sandboxed execution
- **Examples:** Portable plugins from Rust, Go, C++
- **Development:** Compile to WASM target

## Current Implementation Status

### Working Features
- ✅ Built-in plugin system with 5 core scanners
- ✅ External plugin discovery and loading
- ✅ JSON-based plugin communication protocol
- ✅ Automatic plugin initialization
- ✅ Error handling and graceful degradation
- ✅ Plugin performance tracking
- ✅ Parallel plugin execution per file

### Roadmap Features
- ⏳ Plugin configuration via config.toml
- ⏳ Plugin enable/disable controls
- ⏳ Native dynamic library plugins
- ⏳ WebAssembly plugin support
- ⏳ Plugin marketplace/registry
- ⏳ Plugin dependency management
- ⏳ Plugin update mechanism

## Demonstrated Capabilities

### Test Scan Results

**Single File (19 lines Python):**
- Built-in plugins: 6 findings in 4ms
- External plugin: 3 findings in 23ms
- Total: 9 findings in 28ms

**Plugin Breakdown:**
```
Plugin Performance:
  secrets - 2 findings in 2ms        (Built-in Rust)
  patterns - 3 findings in 2ms       (Built-in Rust)
  entropy - 1 findings in 0ms        (Built-in Rust)
  todo-scanner - 3 findings in 23ms  (External Python)
```

### Detection Coverage

**Test file contained:**
- 2 Critical: AWS Access Key, Hardcoded password
- 3 High: Database password, eval() usage, hardcoded secret
- 1 Medium: High entropy content
- 3 Low: TODO/FIXME/XXX comments

**All detected successfully** demonstrating comprehensive coverage across:
- Secret detection (credentials, API keys)
- Pattern matching (dangerous functions)
- Entropy analysis (obfuscation detection)
- Code quality (development comments)

## Tool Installation

A convenience script is provided to install popular security tools:

```bash
./scripts/install-security-tools.sh
```

This installs:
- **gitleaks** - Secret detection
- **semgrep** - SAST with custom rules
- **bandit** - Python security scanner
- **trivy** - Container and IaC scanner
- **gosec** - Go security scanner
- **tfsec** - Terraform security scanner
- **grype** - Vulnerability scanner
- **safety** - Python dependency scanner

## Creating Plugins

### Quick Start: Python Plugin

```python
#!/usr/bin/env python3
import json
import sys

file_path = sys.argv[1]

# Your scanning logic here
findings = []

result = {
    "plugin_name": "my-scanner",
    "findings": findings,
    "scanned_files": 1
}

print(json.dumps(result))
```

### Quick Start: Bash Plugin

```bash
#!/bin/bash
FILE="$1"

# Your scanning logic here

echo '{"plugin_name":"my-scanner","findings":[],"scanned_files":1}'
```

### Installation

```bash
# Copy plugin to plugins directory
cp my-plugin ~/.config/securegit/plugins/

# Make executable
chmod +x ~/.config/securegit/plugins/my-plugin

# Test
securegit scan /path/to/test/file
```

## Community Opportunities

### Potential Plugin Contributions

**Secret Detection:**
- trufflehog wrapper
- detect-secrets wrapper
- custom organizational secret patterns

**Language-Specific SAST:**
- brakeman (Ruby)
- eslint-security (JavaScript)
- findsecbugs (Java)
- phpstan (PHP)
- rubocop-security (Ruby)

**Malware Detection:**
- ClamAV wrapper
- YARA rules integration
- VirusTotal API integration

**License Compliance:**
- licensee wrapper
- scancode integration
- fossology integration

**Container Security:**
- hadolint (Dockerfile linting)
- dockle (container image linting)
- snyk container scanning

**Infrastructure as Code:**
- checkov (multi-cloud)
- terrascan
- kics (Checkmarx)

**Dependency Scanning:**
- npm-audit wrapper
- bundler-audit (Ruby)
- cargo-audit (Rust)
- pip-audit (Python)

### Documentation Resources

- **Plugin Development Guide:** PLUGIN_DEVELOPMENT.md
- **Plugin Registry:** PLUGIN_REGISTRY.md
- **Performance Analysis:** PERFORMANCE.md

## GitHub API Compatibility

Testing confirmed that GitLab instances provide GitHub API compatibility:

**Endpoints Tested:**
- ✅ `/api/github/` - API discovery
- ✅ `/api/github/user` - User authentication
- ✅ `/api/github/user/repos` - Repository listing

This enables SecureGit to work with GitHub-compatible hosting platforms including:
- GitHub.com
- GitHub Enterprise
- GitLab (with GitHub API compatibility)
- Gitea
- Gogs

## Performance Characteristics

### Built-in Plugins
- Startup: 0ms (already loaded)
- Per-file: 0-5ms (depends on file size)
- Memory: Minimal (shared runtime)
- Scalability: Excellent (1000s of files/sec)

### External Plugins
- Startup: 20-50ms (subprocess spawn)
- Per-file: 5-100ms (depends on tool complexity)
- Memory: 10-50MB per plugin
- Scalability: Good (50-200 files/sec)

### Optimization Strategies
1. Use built-in plugins for common patterns
2. Use external plugins for specialized analysis
3. Skip irrelevant files early (check extensions)
4. Run plugins in parallel (future enhancement)
5. Cache results by file hash (future enhancement)

## Real-World Usage

### CI/CD Integration

```yaml
# .github/workflows/security-scan.yml
name: Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install SecureGit
        run: |
          curl -sSL https://github.com/armyknifelabs-tools/securegit/releases/latest/download/securegit-linux-amd64 -o securegit
          chmod +x securegit
      - name: Run Security Scan
        run: ./securegit scan . --fail-on high
```

### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit

securegit scan --staged --fail-on medium || {
    echo "Security scan failed. Commit blocked."
    exit 1
}
```

### Developer Workflow

```bash
# Acquire repository securely
securegit acquire https://github.com/user/repo.git /tmp/safe-repo

# Scan for vulnerabilities
securegit scan /tmp/safe-repo

# If clean, use it
cd /tmp/safe-repo
```

## Security Model

### Plugin Isolation

**Built-in Plugins:**
- Run in same process as SecureGit
- Memory-safe (Rust guarantees)
- No network access
- File system access limited to scan target

**External Plugins:**
- Run in separate processes
- Inherit user permissions
- Can access network (tool-dependent)
- Sandboxing via OS process isolation

**Future: WASM Plugins:**
- Run in WebAssembly sandbox
- Capability-based security
- No network or file system access by default
- Must explicitly grant permissions

### Trust Model

Users should audit plugins before installation:
1. Review plugin source code
2. Verify plugin source (official repos preferred)
3. Check plugin permissions requirements
4. Test in isolated environment first
5. Monitor plugin behavior

## Conclusion

SecureGit's plugin ecosystem combines:
- **Performance** through built-in Rust implementations
- **Flexibility** through external tool integration
- **Safety** through process isolation
- **Community** through open architecture

This positions SecureGit as a comprehensive security solution that can grow with the evolving threat landscape while maintaining high performance and ease of use.

## Next Steps

1. Install security tools: `./scripts/install-security-tools.sh`
2. Create custom plugins: See PLUGIN_DEVELOPMENT.md
3. Test scanning: `securegit scan /path/to/code`
4. Share plugins: Submit to plugin registry
5. Provide feedback: GitHub issues and discussions