bundler-trivy-plugin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea7f6f75aad29ec1c71c632cd92cc3cdb579bb561534cf2f3bffd94b56230027
+  data.tar.gz: 8f54b32d097f04f2954a4140647e78779860b9807d1d54b82ef06e45276e4526
+SHA512:
+  metadata.gz: dfc15a2ad1275fe5a1b6885d90a2ee267f61e73261db6f7b783a6903f7bb338f6072e5b0e47132ec25f5bb6dee14e132638081f17ced72d045ebc4c284c8d985
+  data.tar.gz: b74d1fd1c04cd582919038233c43d9cb83c6da8a866ac7da4424e83a5975863c20f9cb2c6d96ec8987c1a0e84917fdae35fc97ffaa32f02c93b84a3be40d4fff

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure and foundational code
+- Core scanning functionality using Trivy
+- Configuration system supporting YAML files and environment variables
+- Reporter with terminal output support
+- Automatic scanning after `bundle install`
+- Support for ignoring CVEs with expiration dates
+- CI environment detection for automatic fail-on-critical behavior
+- Configurable timeout for Trivy scans
+- Severity filtering (CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN)
+
+### Changed
+- Migrated from RSpec to Minitest for testing (per Durable Programming standards)
+- Moved bundler from development dependency to runtime dependency
+- Enhanced gemspec metadata with RubyGems.org requirements
+
+### Documentation
+- Created comprehensive TODO.md with improvement roadmap
+- Added LICENSE file (MIT)
+- Created CHANGELOG.md following Keep a Changelog format
+- Added CONTRIBUTING.md with development guidelines
+- Added SECURITY.md with vulnerability reporting procedures
+
+## [0.1.0] - 2025-01-31
+
+### Added
+- Initial alpha release
+- Basic Trivy integration for Bundler
+- Configuration file support (`.bundler-trivy.yml`)
+- Environment variable configuration
+- Vulnerability reporting
+- CVE ignore list with expiration
+
+[Unreleased]: https://github.com/durableprogramming/bundler-trivy-plugin/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/durableprogramming/bundler-trivy-plugin/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Durable Programming LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,480 @@
+# Bundler Trivy Plugin
+
+**Automated security vulnerability scanning for Ruby dependencies using Trivy.**
+
+A Bundler plugin that automatically integrates [Trivy](https://trivy.dev/) security scanner into your Ruby development workflow. After every `bundle install`, the plugin scans your dependencies for known vulnerabilities and provides actionable remediation guidance.
+
+## Features
+
+- **Automatic Scanning**: Scans dependencies after `bundle install` with zero configuration
+- **CI/CD Integration**: Smart defaults for CI environments with configurable fail-on policies
+- **Flexible Configuration**: YAML config files and environment variables
+- **CVE Ignore List**: Temporary ignore vulnerabilities with expiration dates
+- **Multiple Output Formats**: Terminal (default), JSON, and compact modes
+- **Detailed Reporting**: Clear vulnerability summaries with fix recommendations
+- **Zero Dependencies**: Lightweight plugin with minimal runtime dependencies
+
+## Quick Start
+
+### 1. Install Trivy
+
+First, install the Trivy scanner:
+
+**macOS**:
+```bash
+brew install aquasecurity/trivy/trivy
+```
+
+**Linux (Ubuntu/Debian)**:
+```bash
+wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
+echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
+sudo apt-get update
+sudo apt-get install trivy
+```
+
+**Other platforms**: See [Trivy Installation Guide](https://trivy.dev/docs/getting-started/installation/)
+
+### 2. Install the Plugin
+
+**From source** (currently):
+```bash
+gem build bundler-trivy-plugin.gemspec
+bundle plugin install bundler-trivy-plugin --source .
+```
+
+**Coming soon - from RubyGems**:
+```bash
+gem install bundler-trivy-plugin
+bundle plugin install bundler-trivy-plugin
+```
+
+### 3. Verify Installation
+
+```bash
+bundle plugin list
+# Should show: bundler-trivy-plugin
+
+trivy --version
+# Should show: Version: 0.x.x or later
+```
+
+### 4. Use It
+
+That's it! The plugin now runs automatically:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Automatic Scanning
+
+The plugin runs automatically after `bundle install`:
+
+```bash
+$ bundle install
+Fetching gem metadata from https://rubygems.org/
+...
+Bundle complete! 15 Gemfile dependencies, 73 gems now installed.
+
+⚠ Trivy found 2 vulnerabilities:
+
+  CRITICAL: 1
+  HIGH: 1
+
+CRITICAL Vulnerabilities:
+
+  rails (6.1.0)
+  CVE-2023-38545: Rails ActiveRecord SQL Injection
+  Fixed in: 6.1.7.6, 7.0.8
+  https://avd.aquasec.com/nvd/cve-2023-38545
+
+Recommended Actions:
+
+  Update rails: bundle update rails
+```
+
+### Skipping Scans
+
+Temporarily skip scanning:
+
+```bash
+BUNDLER_TRIVY_SKIP=true bundle install
+```
+
+### CI/CD Integration
+
+The plugin automatically detects CI environments and enables strict mode:
+
+```yaml
+# GitHub Actions example
+- name: Install dependencies
+  run: bundle install
+  # Plugin automatically fails on critical vulnerabilities in CI
+
+# Override if needed
+- name: Install dependencies (non-blocking)
+  run: BUNDLER_TRIVY_FAIL_ON_CRITICAL=false bundle install
+```
+
+**Supported CI platforms**:
+- GitHub Actions
+- GitLab CI
+- Travis CI
+- Jenkins
+- CircleCI (via CI=true)
+
+## Configuration
+
+### Configuration File
+
+Create `.bundler-trivy.yml` in your project root:
+
+```yaml
+# Enable/disable scanning (default: true)
+enabled: true
+
+# Fail conditions - exit with error code 1 if vulnerabilities found
+fail_on:
+  critical: true  # Default: true in CI, false locally
+  high: false     # Default: false
+  # Note: BUNDLER_TRIVY_FAIL_ON_ANY=true fails on any severity
+
+# Output configuration
+output:
+  format: terminal  # Options: terminal, json
+  compact: false    # Default: false locally, true in CI
+
+# Scanning configuration
+scanning:
+  timeout: 120  # Scan timeout in seconds (default: 120)
+  severity_filter:
+    - CRITICAL
+    - HIGH
+    # Options: CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
+
+# Ignore specific CVEs (use sparingly!)
+ignores:
+  - id: CVE-2023-12345
+    reason: "False positive - does not affect our usage pattern"
+    expires: 2025-12-31  # Required: forces periodic review
+
+  - id: CVE-2023-67890
+    reason: "Waiting for backport to current Rails version"
+    expires: 2025-06-30
+```
+
+### Environment Variables
+
+Environment variables override configuration file settings:
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `BUNDLER_TRIVY_SKIP` | Skip scanning entirely | `false` | `true` |
+| `BUNDLER_TRIVY_FAIL_ON_CRITICAL` | Exit on critical vulns | CI=true | `true` |
+| `BUNDLER_TRIVY_FAIL_ON_HIGH` | Exit on high vulns | `false` | `true` |
+| `BUNDLER_TRIVY_FAIL_ON_ANY` | Exit on any vulns | `false` | `true` |
+| `BUNDLER_TRIVY_COMPACT` | Compact output | CI=true | `true` |
+| `BUNDLER_TRIVY_FORMAT` | Output format | `terminal` | `json` |
+| `BUNDLER_TRIVY_TIMEOUT` | Scan timeout (seconds) | `120` | `300` |
+| `BUNDLER_TRIVY_SEVERITY` | Severity threshold | `CRITICAL` | `HIGH` |
+
+**Examples**:
+
+```bash
+# Ultra-strict mode (fail on any vulnerability)
+BUNDLER_TRIVY_FAIL_ON_ANY=true bundle install
+
+# JSON output for parsing
+BUNDLER_TRIVY_FORMAT=json bundle install > vulnerabilities.json
+
+# Longer timeout for large projects
+BUNDLER_TRIVY_TIMEOUT=300 bundle install
+
+# Skip scanning temporarily
+BUNDLER_TRIVY_SKIP=true bundle install
+```
+
+### Multiple Environments
+
+Use environment-specific configs:
+
+```bash
+# .bundler-trivy.development.yml - lenient for local dev
+enabled: true
+fail_on:
+  critical: false
+
+# .bundler-trivy.production.yml - strict for production
+enabled: true
+fail_on:
+  critical: true
+  high: true
+```
+
+Activate with:
+
+```bash
+BUNDLER_TRIVY_ENV=production bundle install
+```
+
+### Global Configuration
+
+Create `~/.bundle/trivy.yml` for user-wide defaults:
+
+```yaml
+# Your personal defaults for all projects
+output:
+  compact: false
+scanning:
+  timeout: 180
+```
+
+Project configs override global configs.
+
+## Examples
+
+### Example: GitHub Actions Workflow
+
+```yaml
+name: Security Scan
+
+on: [push, pull_request]
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
+          bundler-cache: false  # We'll handle bundling
+
+      - name: Install Trivy
+        run: |
+          wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
+          echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
+          sudo apt-get update
+          sudo apt-get install trivy
+
+      - name: Install Plugin
+        run: |
+          gem build bundler-trivy-plugin.gemspec
+          bundle plugin install bundler-trivy-plugin --source .
+
+      - name: Install Dependencies with Security Scan
+        run: bundle install
+        # Automatically fails on critical vulnerabilities in CI
+```
+
+### Example: GitLab CI
+
+```yaml
+security_scan:
+  image: ruby:3.2
+  before_script:
+    - apt-get update && apt-get install -y wget gnupg
+    - wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | apt-key add -
+    - echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | tee -a /etc/apt/sources.list.d/trivy.list
+    - apt-get update && apt-get install -y trivy
+    - gem build bundler-trivy-plugin.gemspec
+    - bundle plugin install bundler-trivy-plugin --source .
+  script:
+    - bundle install
+  allow_failure: false
+```
+
+### Example: Local Development Workflow
+
+```bash
+# Initial setup
+bundle install  # Scans and warns about vulnerabilities
+
+# Working on features (skip scanning for speed)
+BUNDLER_TRIVY_SKIP=true bundle install
+
+# Before committing (strict check)
+BUNDLER_TRIVY_FAIL_ON_HIGH=true bundle install
+```
+
+## Troubleshooting
+
+### Plugin not running
+
+**Check plugin is installed**:
+```bash
+bundle plugin list
+# Should show bundler-trivy-plugin
+```
+
+**Reinstall if needed**:
+```bash
+bundle plugin uninstall bundler-trivy-plugin
+bundle plugin install bundler-trivy-plugin --source .
+```
+
+### Trivy not found
+
+**Verify Trivy is installed**:
+```bash
+which trivy
+trivy --version
+```
+
+**Install Trivy**: See [Quick Start](#quick-start)
+
+### Scan timing out
+
+**Increase timeout**:
+```bash
+BUNDLER_TRIVY_TIMEOUT=300 bundle install
+```
+
+**Or in config**:
+```yaml
+scanning:
+  timeout: 300
+```
+
+### False positives
+
+**Ignore specific CVEs temporarily**:
+```yaml
+ignores:
+  - id: CVE-2023-XXXXX
+    reason: "Detailed explanation of why this is safe"
+    expires: 2025-12-31  # Forces review
+```
+
+**Best practice**: Always include an expiration date to force periodic review.
+
+### Scan failing in CI
+
+**Check CI logs for specific error**:
+```bash
+# Run locally with same settings
+CI=true bundle install
+```
+
+**Common causes**:
+- Outdated Trivy database
+- Network connectivity issues
+- Actual vulnerabilities (intended behavior!)
+
+### Permission errors
+
+**Linux/macOS**: Ensure Trivy binary is executable:
+```bash
+chmod +x $(which trivy)
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/durableprogramming/bundler-trivy-plugin.git
+cd bundler-trivy-plugin
+bundle install
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+rake test
+
+# Run specific test file
+ruby test/bundler/trivy/config_test.rb
+
+# Run with coverage
+COVERAGE=true rake test
+```
+
+### Code Quality
+
+```bash
+# Check style
+bundle exec rubocop
+
+# Auto-fix violations
+bundle exec rubocop -a
+```
+
+### Local Testing
+
+```bash
+# Build gem
+gem build bundler-trivy-plugin.gemspec
+
+# Install in test project
+cd /path/to/test/project
+bundle plugin uninstall bundler-trivy-plugin || true
+bundle plugin install bundler-trivy-plugin --source /path/to/plugin
+
+# Test
+bundle install
+```
+
+### Opening Console
+
+```bash
+rake console
+```
+
+## Requirements
+
+- **Ruby**: 2.7.0 or later
+- **Bundler**: 2.0 or later
+- **Trivy**: Latest version recommended (0.40.0+)
+- **Operating Systems**: macOS, Linux, Windows (with WSL)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup
+- Code style guidelines
+- Testing requirements
+- Pull request process
+
+## Security
+
+Security is paramount. See [SECURITY.md](SECURITY.md) for:
+- Vulnerability reporting procedures
+- Security best practices
+- Supported versions
+
+**Report security issues to**: security@durableprogramming.com
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
+
+## Roadmap
+
+See [TODO.md](TODO.md) for planned features and improvements.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- **Documentation**: [GitHub README](https://github.com/durableprogramming/bundler-trivy-plugin)
+- **Issues**: [GitHub Issues](https://github.com/durableprogramming/bundler-trivy-plugin/issues)
+- **Email**: commercial@durableprogramming.com
+
+## Credits
+
+- Built by [Durable Programming LLC](https://durableprogramming.com)
+- Powered by [Aqua Security Trivy](https://trivy.dev/)
+- Inspired by the Ruby security community
+
+---
+
+**Stay secure!** 🔒