securegit 0.8.5

<!--
  Copyright (c) 2026 ArmyKnife Labs

  This Specification is licensed under the Specification Commons License,
  Version 0.1 (SCL-0.1). See /LICENSE-SCL for the full license text.

  Evaluation Scenario Tier: Open
-->

# SecureGit Documentation

## Overview

SecureGit is a zero-trust code acquisition and security scanning platform that combines aggressive security validation with an extensible plugin architecture.

## Core Documentation

### Getting Started
- [Installation Guide](INSTALLATION.md) - How to install SecureGit
- [Quick Start Guide](QUICKSTART.md) - Your first scan in 5 minutes
- [User Guide](USER_GUIDE.md) - Complete user documentation

### Plugin System

**Architecture & Development:**
- [Plugin Development Guide](PLUGIN_DEVELOPMENT.md) - Create custom security plugins
- [Plugin Registry](PLUGIN_REGISTRY.md) - Community plugin catalog
- [Plugin Ecosystem](PLUGIN_ECOSYSTEM.md) - Architecture overview and capabilities

**Version Management:**
- [Plugin Version Management](PLUGIN_VERSION_MANAGEMENT.md) - Version tracking and updates (design document)
- [Git-Based Plugin Updates](GIT_BASED_PLUGIN_UPDATES.md) - Leveraging Git for simple updates
- [User Guide: Plugin Management](USER_GUIDE_PLUGIN_MANAGEMENT.md) - Practical guide for staying current

**Performance & Installation:**
- [Performance Analysis](PERFORMANCE.md) - Benchmarks and optimization strategies
- [Installation Summary](INSTALLATION_SUMMARY.md) - Tools installed and test results

### Security Features
- [Zero-Trust Acquisition](ZERO_TRUST_ACQUISITION.md) - How SecureGit validates untrusted repositories
- [Threat Detection](THREAT_DETECTION.md) - What SecureGit can find
- [Git Internals Scanning](GIT_INTERNALS_SCANNING.md) - Detecting threats in .git directory

### Advanced Topics
- [CI/CD Integration](CICD_INTEGRATION.md) - GitHub Actions, GitLab CI, Jenkins
- [Custom Policies](CUSTOM_POLICIES.md) - Organization-specific security rules
- [API Documentation](API.md) - Using SecureGit as a library

## Key Concepts

### Zero-Trust Code Acquisition

**Problem:** Cloning untrusted Git repositories exposes your system to:
- Git hooks that execute arbitrary code
- Malicious binaries disguised as source files
- Archive bombs and resource exhaustion
- Path traversal and symlink attacks

**Solution:** SecureGit acquires code through:
1. Download repository as ZIP archive (no hooks execute)
2. Extract with safety validations (size limits, path sanitization)
3. Sanitize and convert to safe Git repository
4. Scan for threats before allowing use

### Hybrid Plugin Architecture

**Built-in Rust Plugins (Speed):**
- secrets: Hardcoded credentials detection
- patterns: Dangerous code patterns
- entropy: Obfuscation and encryption detection
- binary: Suspicious binary file detection
- git-internals: Git repository threat scanning

**External Plugins (Flexibility):**
- Language-agnostic (Bash, Python, Go, any executable)
- Wrap existing tools (gitleaks, semgrep, trivy, ClamAV, YARA)
- Community-maintained
- Easy to create and share

### Plugin Version Management

**The Problem:**
Developers install security plugins and forget about them. Outdated plugins miss new threats and may contain vulnerabilities.

**The Solution:**
- Automatic update checking
- Security advisory integration
- Changelog summarization
- Git-based updates (leveraging built-in Git client)
- Update notifications before every scan

## Documentation Structure

### For Users

**I want to scan code for security issues:**
1. Start: [Quick Start Guide](QUICKSTART.md)
2. Learn: [User Guide](USER_GUIDE.md)
3. Manage: [Plugin Management Guide](USER_GUIDE_PLUGIN_MANAGEMENT.md)

**I want to integrate into CI/CD:**
1. Read: [CI/CD Integration](CICD_INTEGRATION.md)
2. Example: [GitHub Actions Workflow](examples/github-actions.yml)
3. Best Practices: [CI/CD Best Practices](CICD_BEST_PRACTICES.md)

**I want to customize for my organization:**
1. Start: [Custom Policies](CUSTOM_POLICIES.md)
2. Create: [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
3. Deploy: [Enterprise Deployment](ENTERPRISE_DEPLOYMENT.md)

### For Plugin Developers

**I want to create a plugin:**
1. Read: [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
2. Example: [Example Plugins](examples/plugins/)
3. Submit: [Plugin Registry Submission](PLUGIN_SUBMISSION.md)

**I want to maintain a plugin:**
1. Versioning: [Git-Based Plugin Updates](GIT_BASED_PLUGIN_UPDATES.md)
2. Best Practices: [Plugin Maintenance](PLUGIN_MAINTENANCE.md)
3. Security: [Plugin Security Guidelines](PLUGIN_SECURITY.md)

### For Contributors

**I want to contribute to SecureGit:**
1. Setup: [Development Setup](CONTRIBUTING.md)
2. Architecture: [Architecture Overview](ARCHITECTURE.md)
3. Testing: [Testing Guide](TESTING.md)

## Quick Reference

### Common Commands

```bash
# Install SecureGit
curl -sSL https://securegit.dev/install.sh | sh

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

# Scan for security issues
securegit scan /path/to/code

# Install plugins
securegit plugin install gitleaks
securegit plugin install semgrep

# Check for plugin updates
securegit plugin check-updates

# Update plugins
securegit plugin update --all

# View plugin status
securegit plugin list
```

### Configuration Files

```
~/.config/securegit/
├── config.toml              # Main configuration
├── plugins/                 # External plugins
│   ├── gitleaks/           # Git repository per plugin
│   ├── semgrep/
│   └── trivy-config/
└── plugin-versions.json     # Version tracking registry
```

### Key Configuration Options

```toml
# ~/.config/securegit/config.toml

[scan]
fail_on_severity = "high"    # Fail scans with high+ findings
skip_paths = [
    "**/node_modules/**",
    "**/vendor/**",
    "**/.git/**"
]

[plugins]
auto_update_check = true              # Check for updates
update_check_interval_hours = 24      # Once per day
notify_updates_available = true       # Show notifications
auto_update_security = true           # Auto-update security fixes

[acquisition]
max_archive_size_mb = 500             # Max repo size
max_nesting_depth = 25                # Archive nesting limit
allow_symlinks = false                # Block symlink attacks
```

## Plugin Ecosystem

### Available Plugins

**Secret Detection:**
- gitleaks - Hardcoded secrets (API keys, passwords, tokens)
- trufflehog - Entropy-based secret detection
- detect-secrets - Enterprise secret scanner

**SAST (Static Analysis):**
- semgrep - Multi-language SAST with 1000+ rules
- bandit - Python security scanner
- gosec - Go security scanner
- brakeman - Ruby on Rails scanner
- eslint-security - JavaScript/TypeScript

**Container Security:**
- trivy - Container and IaC scanner
- grype - Vulnerability scanner
- hadolint - Dockerfile linter

**Malware Detection:**
- clamav - Antivirus with 40+ years of signatures
- yara - Pattern matching for malware

**License Compliance:**
- licensee - License detection
- scancode - Comprehensive license scanning

**Infrastructure as Code:**
- tfsec - Terraform security
- checkov - Multi-cloud IaC scanner

See [Plugin Registry](PLUGIN_REGISTRY.md) for complete list.

## Performance Characteristics

### Scan Speed

**Single file (19 lines Python):**
- Built-in plugins: 5ms
- With external plugins: 25-50ms

**Medium repository (1000 files):**
- Built-in only: 10-15 seconds
- With 5 external plugins: 1-2 minutes

**Large repository (10,000 files):**
- Built-in only: 2-3 minutes
- With 5 external plugins: 10-15 minutes

See [Performance Analysis](PERFORMANCE.md) for detailed benchmarks.

## Security Model

### Threat Protection

SecureGit protects against:
- **Malicious Git hooks** - Hooks never execute
- **Binary backdoors** - Binary detection and scanning
- **Archive bombs** - Size and nesting limits
- **Path traversal** - Path sanitization
- **Symlink attacks** - Symlink blocking
- **Resource exhaustion** - Timeouts and limits

### Plugin Security

- **Built-in plugins:** Memory-safe Rust, same-process execution
- **External plugins:** Process isolation, configurable timeouts
- **Future WASM plugins:** Sandboxed execution, capability-based security

### Update Security

- Git commit signing verification
- SHA256 checksum validation
- Security advisory integration
- Automatic vulnerability detection

## Roadmap

### Current Version: v0.1.0

**Implemented:**
- ✅ Zero-trust repository acquisition
- ✅ Archive extraction with safety validations
- ✅ Git hook sanitization
- ✅ 5 built-in security scanners
- ✅ External plugin system
- ✅ Plugin discovery and loading
- ✅ Comprehensive scan reporting

### Next Version: v0.2.0 (Plugin Management)

**Planned:**
- [ ] Plugin version registry
- [ ] Git-based update checking
- [ ] Changelog fetching and parsing
- [ ] Update notifications
- [ ] Manual update commands
- [ ] Rollback functionality

### Version 0.3.0 (Automation)

**Planned:**
- [ ] Automatic update checks
- [ ] Security advisory integration
- [ ] CVE database lookups
- [ ] Changelog summarization
- [ ] Email/webhook notifications
- [ ] Automatic security updates

### Version 0.4.0 (Registry)

**Planned:**
- [ ] Central plugin registry
- [ ] Plugin marketplace
- [ ] Community ratings
- [ ] Trust and verification system
- [ ] Plugin discovery and search

### Future Enhancements

**Performance:**
- [ ] Parallel file scanning
- [ ] Incremental scanning (only changed files)
- [ ] Result caching by file hash
- [ ] Multi-threaded plugin execution

**Plugin System:**
- [ ] Native dynamic library plugins (.so)
- [ ] WebAssembly plugin support
- [ ] Plugin dependency management
- [ ] Plugin sandboxing

**Enterprise Features:**
- [ ] Custom policy enforcement
- [ ] Audit logging
- [ ] SAML/SSO integration
- [ ] Central management console
- [ ] License compliance reporting

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup
- Code style guidelines
- Testing requirements
- Pull request process

### Areas for Contribution

**High Priority:**
- Plugin version management implementation
- Additional built-in scanners
- Performance optimizations
- Documentation improvements

**Community Plugins:**
- Wrappers for popular security tools
- Language-specific scanners
- Organization-specific policies
- Integration with commercial tools

**Testing:**
- Test malicious repositories
- Performance benchmarks
- Cross-platform testing
- Plugin compatibility testing

## Support

### Documentation
- [Full documentation](https://docs.securegit.dev)
- [API reference](https://api.securegit.dev)
- [Plugin development guide](PLUGIN_DEVELOPMENT.md)

### Community
- GitHub Discussions: https://github.com/armyknifelabs-tools/securegit/discussions
- Issue Tracker: https://github.com/armyknifelabs-tools/securegit/issues
- Plugin Registry: https://github.com/armyknifelabs-tools/securegit-plugins

### Enterprise Support
- Email: enterprise@securegit.dev
- Commercial support and training available
- Custom plugin development services

## License

SecureGit is dual-licensed under MIT OR Apache-2.0.

See [LICENSE-MIT](../LICENSE-MIT) and [LICENSE-APACHE](../LICENSE-APACHE) for details.

## Acknowledgments

SecureGit builds upon and integrates with many excellent open-source security tools:
- gitleaks - Secret detection
- semgrep - Multi-language SAST
- trivy - Container security
- ClamAV - Malware detection
- And many more in the plugin ecosystem

Special thanks to the security research community for their continuous work in identifying and documenting threats.

## Status

**Current Status:** Beta (v0.1.0)

SecureGit is production-ready for:
- Local development security scanning
- Pre-commit hook integration
- CI/CD security gates
- Repository acquisition and sanitization

Plugin version management is in design phase and will be implemented in v0.2.0.

**Stability:** Core features are stable. External plugin API may evolve.

## Next Steps

**New Users:**
1. Read [Quick Start Guide](QUICKSTART.md)
2. Install SecureGit
3. Run your first scan
4. Install community plugins

**Plugin Developers:**
1. Read [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
2. Create a plugin wrapper
3. Test locally
4. Submit to registry

**Contributors:**
1. Read [CONTRIBUTING.md](CONTRIBUTING.md)
2. Set up development environment
3. Pick an issue or propose a feature
4. Submit a pull request

---

**Build secure software. Trust nothing. Verify everything.**