gem_guard 0.1.6 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '073099f4fd844fee5ffd2b5466fbee6df36a8c5b9d640039efb0cbdb4db89b97'
-  data.tar.gz: 21ba615adb70721d4f9ede82e3a43361a92e72e683c53530504913250ccd7309
+  metadata.gz: 0370d291f988c0082519f85fdfaffc6fd2acfad9150f91e1c0c66e4d913fd2c0
+  data.tar.gz: 81378c1f38167cccd7ff0ed7f6fb8399556afe40bb29421d2d50601e5aafed91
 SHA512:
-  metadata.gz: d1bc314331a645c4b2d9791f41d852620fc7a977fc7eaf90ea927743f297057f4af93c40da2788422c8c468b11fbb1ad4d80d59f16cb4a0c9c063f37ebed809c
-  data.tar.gz: 1dc4f927542ae0983fb73a0d285c66f61c93960f1128bde659a313bbda24a7e6625d41acfdc48fcadeb8600f78bdb2f6de2b052e072a553aa78a937ad841b7dc
+  metadata.gz: f07731cbc1d4b3dffe6494a4749dfac41cd31849df39e5e712b3735322135131a59f8dd06aaa790c39104d632637d050e3a25e58a9b92c9441accde55a90126e
+  data.tar.gz: 5906908cb03aac3227f78b16cc49b5e8a7b78756361b809840c1b8de9a5dfb3bc5d138954a3703f051e2ee62e8eaea11cb047e1073882c5b2bf3f2715a36468e

data/README.md

@@ -6,15 +6,41 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Security](https://img.shields.io/badge/Security-Policy-blue.svg)](SECURITY.md)
 
-Supply chain security and vulnerability management for Ruby gems. GemGuard provides developers with a comprehensive tool to detect, report, and remediate dependency-related security risks.
-
-## Features
-
-- 🔍 **Vulnerability Scanning**: Detect known CVEs in your dependencies
-- 📊 **Multiple Output Formats**: Human-readable tables and JSON output
-- 🌐 **Multiple Data Sources**: OSV.dev and Ruby Advisory Database
-- 🔧 **Fix Recommendations**: Suggested commands to remediate vulnerabilities
-- 🚀 **CI/CD Ready**: Exit codes for pipeline integration
+**The comprehensive Ruby dependency security scanner and SBOM generator.**
+
+GemGuard is your one-stop solution for Ruby supply chain security. Detect vulnerabilities, identify typosquats, generate SBOMs, and secure your dependencies with enterprise-grade tooling designed for modern DevOps workflows.
+
+## ✨ Features
+
+### 🔍 **Vulnerability Scanning**
+- Detect known CVEs from OSV.dev and Ruby Advisory Database
+- Smart deduplication handles platform-specific gems
+- Severity-based filtering and thresholds
+- Actionable fix recommendations with exact commands
+
+### 🎯 **Typosquat Detection**
+- Fuzzy matching against popular Ruby gems
+- Configurable similarity thresholds
+- Risk level classification (Critical/High/Medium/Low)
+- Hardcoded fallback for reliable detection
+
+### 📋 **SBOM Generation**
+- Industry-standard SPDX 2.3 format
+- CycloneDX 1.5 support
+- Complete dependency metadata
+- License and checksum information
+
+### 🚀 **CI/CD Integration**
+- Configurable exit codes for pipeline control
+- JSON output for automated processing
+- Config file support (`.gemguard.yml`)
+- Multiple output formats and file export
+
+### 🎨 **Developer Experience**
+- Beautiful, colorful terminal output
+- Progress indicators and clear error messages
+- Comprehensive help and documentation
+- Zero-config operation with sensible defaults
 
 ## Installation
 
@@ -32,30 +58,47 @@ Or install it yourself as:
 
     $ gem install gem_guard
 
-## Usage
+## 🚀 Quick Start
+
+```bash
+# Install GemGuard
+gem install gem_guard
+
+# Scan for vulnerabilities
+gem_guard scan
+
+# Check for typosquats
+gem_guard typosquat
 
-### Basic Vulnerability Scan
+# Generate SBOM
+gem_guard sbom
+```
+
+## 📖 Usage
 
-Scan your project's dependencies for known vulnerabilities:
+### 🔍 Vulnerability Scanning
 
+**Basic scan:**
 ```bash
 gem_guard scan
 ```
 
-### Specify Custom Lockfile
-
+**Custom lockfile:**
 ```bash
 gem_guard scan --lockfile path/to/Gemfile.lock
 ```
 
-### JSON Output
-
+**JSON output for automation:**
 ```bash
-gem_guard scan --format json
+gem_guard scan --format json --output vulnerabilities.json
 ```
 
-### Example Output
+**CI/CD integration with exit codes:**
+```bash
+gem_guard scan --fail-on-vulnerabilities --severity-threshold high
+```
 
+**Example output:**
 ```
 🚨 Security Vulnerabilities Found
 ==================================================
@@ -66,17 +109,208 @@ Summary:
 
 Details:
 
-📦 actionpack (6.1.0)
-   🔍 Vulnerability: CVE-2021-22885
-   ⚠️  Severity: HIGH
-   📝 Summary: Possible Information Disclosure / Unintended Method Execution in Action Pack
-   🔧 Fix: bundle update actionpack --to 6.1.3.1
+📦 nokogiri (1.18.8)
+   🔍 Vulnerability: GHSA-353f-x4gh-cqq8
+   ⚠️  Severity: UNKNOWN
+   📝 Summary: Nokogiri patches vendored libxml2 to resolve multiple CVEs
+   🔧 Fix: bundle update nokogiri --to 1.18.9
+
+📦 thor (1.3.2)
+   🔍 Vulnerability: GHSA-mqcp-p2hv-vw6x
+   ⚠️  Severity: CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:C/C:H/I:H/A:H
+   📝 Summary: Thor can construct an unsafe shell command from library input.
+   🔧 Fix: bundle update thor --to 1.4.0
+```
+
+### 🎯 Typosquat Detection
+
+**Basic typosquat check:**
+```bash
+gem_guard typosquat
+```
+
+**Custom similarity threshold:**
+```bash
+gem_guard typosquat --threshold 0.9
+```
+
+**JSON output:**
+```bash
+gem_guard typosquat --format json --output typosquats.json
+```
+
+**Example output:**
+```
+🎯 Potential Typosquat Dependencies Found
+==========================================
+
+📦 railz (7.0.0)
+   🚨 Risk Level: CRITICAL
+   📊 Similarity: 80.0% to 'rails'
+   ⚠️  This gem name is suspiciously similar to the popular gem 'rails'
+   🔧 Consider: Did you mean 'rails'? Review this dependency carefully.
+```
+
+### 📋 SBOM Generation
 
-📦 nokogiri (1.10.0)
-   🔍 Vulnerability: CVE-2020-26247
-   ⚠️  Severity: MEDIUM
-   📝 Summary: XML External Entity vulnerability in Nokogiri
-   🔧 Fix: bundle update nokogiri --to 1.11.0
+**Generate SPDX SBOM:**
+```bash
+gem_guard sbom
+```
+
+**Generate CycloneDX SBOM:**
+```bash
+gem_guard sbom --format cyclone-dx
+```
+
+**Custom project name and output:**
+```bash
+gem_guard sbom --project my-app --output sbom.json
+```
+
+**Example SPDX output:**
+```json
+{
+  "spdxVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "my-app-sbom",
+  "documentNamespace": "https://gem-guard.dev/my-app/2025-01-09T23:55:00Z",
+  "creationInfo": {
+    "created": "2025-01-09T23:55:00Z",
+    "creators": ["Tool: gem_guard-1.0.0"]
+  },
+  "packages": [...],
+  "relationships": [...]
+}
+```
+
+## ⚙️ Configuration
+
+GemGuard supports project-level configuration via `.gemguard.yml`:
+
+```yaml
+# .gemguard.yml
+lockfile_path: "Gemfile.lock"
+output_format: "table"  # table, json
+fail_on_vulnerabilities: true
+severity_threshold: "medium"  # low, medium, high, critical
+output_file: null
+ignore_vulnerabilities:
+  - "CVE-2021-12345"  # Ignore specific CVEs
+  - "GHSA-xxxx-xxxx-xxxx"
+typosquat:
+  similarity_threshold: 0.8
+  enabled: true
+sbom:
+  format: "spdx"  # spdx, cyclone-dx
+  project_name: "my-project"
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `lockfile_path` | Path to Gemfile.lock | `"Gemfile.lock"` |
+| `output_format` | Output format (table/json) | `"table"` |
+| `fail_on_vulnerabilities` | Exit with code 1 if vulnerabilities found | `true` |
+| `severity_threshold` | Minimum severity to report | `"low"` |
+| `output_file` | Write output to file | `null` |
+| `ignore_vulnerabilities` | List of CVE/GHSA IDs to ignore | `[]` |
+| `typosquat.similarity_threshold` | Typosquat detection sensitivity | `0.8` |
+| `typosquat.enabled` | Enable typosquat detection | `true` |
+| `sbom.format` | SBOM format (spdx/cyclone-dx) | `"spdx"` |
+| `sbom.project_name` | Project name in SBOM | `"ruby-project"` |
+
+## 🔄 CI/CD Integration
+
+### Exit Codes
+
+GemGuard uses standard exit codes for CI/CD integration:
+
+- **0**: Success (no vulnerabilities or typosquats found)
+- **1**: Vulnerabilities/typosquats found
+- **2**: Error (invalid arguments, missing files, etc.)
+
+### GitHub Actions
+
+```yaml
+name: Security Scan
+on: [push, pull_request]
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+      
+      - name: Install GemGuard
+        run: gem install gem_guard
+      
+      - name: Vulnerability Scan
+        run: gem_guard scan --format json --output vulnerabilities.json
+      
+      - name: Typosquat Check
+        run: gem_guard typosquat --format json --output typosquats.json
+      
+      - name: Generate SBOM
+        run: gem_guard sbom --output sbom.json
+      
+      - name: Upload Security Reports
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: security-reports
+          path: |
+            vulnerabilities.json
+            typosquats.json
+            sbom.json
+```
+
+### GitLab CI
+
+```yaml
+security_scan:
+  stage: test
+  image: ruby:3.2
+  before_script:
+    - bundle install
+    - gem install gem_guard
+  script:
+    - gem_guard scan --format json --output vulnerabilities.json
+    - gem_guard typosquat --format json --output typosquats.json
+    - gem_guard sbom --output sbom.json
+  artifacts:
+    reports:
+      # GitLab can parse these for security dashboard
+      dependency_scanning: vulnerabilities.json
+    paths:
+      - "*.json"
+    when: always
+  allow_failure: false
+```
+
+### CircleCI
+
+```yaml
+version: 2.1
+jobs:
+  security:
+    docker:
+      - image: cimg/ruby:3.2
+    steps:
+      - checkout
+      - run: bundle install
+      - run: gem install gem_guard
+      - run: gem_guard scan --fail-on-vulnerabilities
+      - run: gem_guard typosquat
+      - run: gem_guard sbom --output sbom.json
+      - store_artifacts:
+          path: sbom.json
 ```
 
 ## Development
@@ -106,14 +340,63 @@ Releases are automated via GitHub Actions. To create a new release:
 
 The release workflow is triggered only when `lib/gem_guard/version.rb` changes.
 
-## Contributing
+## 🤝 Contributing
+
+We welcome contributions! Here's how you can help:
+
+1. **Fork the repository**
+2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
+3. **Write tests** for your changes (we use strict TDD)
+4. **Run the test suite** (`bundle exec rspec`)
+5. **Run the linter** (`bundle exec rake standard`)
+6. **Commit your changes** (`git commit -am 'Add amazing feature'`)
+7. **Push to the branch** (`git push origin feature/amazing-feature`)
+8. **Open a Pull Request**
+
+### Development Guidelines
+
+- Follow DHH-style Ruby: pragmatic, intention-revealing, minimal abstractions
+- Use strict outside-in TDD with RSpec
+- Maintain 100% test coverage
+- Follow StandardRB for code style
+- Write clear, descriptive commit messages
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/wilburhimself/gem_guard.
+## 📊 Roadmap
 
-## License
+- [ ] **Enhanced Vulnerability Sources**: Additional security databases
+- [ ] **Auto-Fix Suggestions**: Automated dependency updates
+- [ ] **Web Dashboard**: Browser-based security monitoring
+- [ ] **IDE Integrations**: VS Code, RubyMine plugins
+- [ ] **Slack/Teams Notifications**: Real-time security alerts
+- [ ] **Custom Rules Engine**: User-defined security policies
+
+## 🏆 Why GemGuard?
+
+| Feature | GemGuard | bundler-audit | Other Tools |
+|---------|----------|---------------|-------------|
+| **Vulnerability Scanning** | ✅ OSV.dev + Ruby Advisory | ✅ Ruby Advisory Only | ❌ Limited Sources |
+| **Typosquat Detection** | ✅ Fuzzy Matching | ❌ | ❌ |
+| **SBOM Generation** | ✅ SPDX + CycloneDX | ❌ | ❌ |
+| **CI/CD Integration** | ✅ Full Support | ⚠️ Basic | ⚠️ Limited |
+| **JSON Output** | ✅ | ✅ | ⚠️ Varies |
+| **Configuration Files** | ✅ | ❌ | ⚠️ Limited |
+| **Platform Deduplication** | ✅ | ❌ | ❌ |
+| **Active Development** | ✅ | ⚠️ Maintenance | ⚠️ Varies |
+
+## 📄 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Security
+## 🔒 Security
+
+If you discover a security vulnerability within GemGuard, please see our [Security Policy](SECURITY.md) for responsible disclosure guidelines.
+
+## 🙏 Acknowledgments
+
+- [OSV.dev](https://osv.dev/) for comprehensive vulnerability data
+- [Ruby Advisory Database](https://github.com/rubysec/ruby-advisory-db) for Ruby-specific advisories
+- The Ruby community for continuous feedback and contributions
+
+---
 
-If you discover a security vulnerability within GemGuard, please send an email to security@example.com. All security vulnerabilities will be promptly addressed.
+**Made with ❤️ for the Ruby community**

data/SECURITY.md

@@ -46,8 +46,52 @@ GemGuard itself implements several security best practices:
 
 When using GemGuard:
 
-- Keep GemGuard updated to the latest version
-- Review vulnerability reports carefully before applying fixes
+- **Keep GemGuard updated** to the latest version for security patches
+- **Review vulnerability reports** carefully before applying fixes
+- **Validate SBOM outputs** before sharing with external parties
+- **Use secure channels** when transmitting security reports
+- **Configure ignore lists** carefully to avoid missing critical vulnerabilities
+- **Monitor CI/CD pipelines** for security scan failures
+
+## Threat Model
+
+GemGuard protects against:
+
+- **Known Vulnerabilities**: CVEs in your dependency chain
+- **Typosquat Attacks**: Malicious gems with similar names to popular packages
+- **Supply Chain Attacks**: Compromised or malicious dependencies
+- **Outdated Dependencies**: Gems with known security issues
+
+## Data Handling
+
+GemGuard:
+
+- **Does not collect** personal or sensitive data
+- **Queries public APIs** (OSV.dev) for vulnerability information
+- **Processes locally** your Gemfile.lock and dependency information
+- **Does not transmit** your code or proprietary information
+- **Caches vulnerability data** temporarily for performance
+
+## Security Updates
+
+We provide security updates through:
+
+- **GitHub Security Advisories** for critical vulnerabilities
+- **RubyGems.org releases** with security patches
+- **Email notifications** to security@wilburhimself.com subscribers
+- **GitHub releases** with detailed changelogs
+
+## Contact
+
+For security-related inquiries:
+
+- **Email**: security@wilburhimself.com
+- **PGP Key**: Available upon request
+- **Response Time**: 48 hours for initial response
+
+---
+
+*Last updated: January 2025*
 - Use GemGuard in your CI/CD pipeline to catch vulnerabilities early
 - Consider the source and severity of reported vulnerabilities
 

data/lib/gem_guard/analyzer.rb

@@ -8,7 +8,10 @@ module GemGuard
 
         next if matching_vulns.empty?
 
-        matching_vulns.each do |vulnerability|
+        # Deduplicate vulnerabilities by ID to avoid duplicate entries for the same vulnerability
+        unique_vulns = matching_vulns.uniq { |vuln| vuln.id }
+
+        unique_vulns.each do |vulnerability|
           if version_affected?(dependency.version, vulnerability)
             vulnerable_dependencies << VulnerableDependency.new(
               dependency: dependency,