hedra 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7ead36ae675253cd990b46928a4ce3cfa7046dde55e2353c6101b53953edd18
-  data.tar.gz: 3c5361c38a9393ca66310eb19809a9a770b4ef91476d21010c56cccb5d76fec3
+  metadata.gz: 124399236bba4ce146d076b83f5d47cfd4fd646f5ced61096a01efe0a9e80333
+  data.tar.gz: ae5c000c2421d787a9e6c28c6574aef21555bb1bbffbe3e1ae1ccd8169478bf9
 SHA512:
-  metadata.gz: 4505267cfc8111cc24680a5962941786edeae9bbd133d75d9ab7bbc61c7ea32ca2dd4281bd655d090cf8513f1951232fa074edd64ba33b4544e9bd425294566c
-  data.tar.gz: 36616c7e22a2fd223d1d5c760a96bfa6c09c5a06392073c836d4b8414f81a272896ec96f57f348e8c78f65cc9f45481c930dbdeceb899d2b26afd5a9663b7e68
+  metadata.gz: 0cffa289a6c2d3413f118f160a6f57badab79b68bf2333573c9efd6e830e1970f33afcf0d24aa6f27740f50f03d45c65275b4c2951826bc8d3df081f4bd197f4
+  data.tar.gz: 02b4706392f72c1a42883eeb8dec92d7b7776856806fbab65aa4e7283c967be679ff471fb2e8da8677901f00db47be15afe9fb3fc0836ef275e05e3d38462a2b

data/README.md

@@ -1,147 +1,457 @@
-# Hedra 🛡️
+# Hedra
 
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg)](https://www.ruby-lang.org/)
-[![CI](https://github.com/blackstack/hedra/workflows/CI/badge.svg)](https://github.com/blackstack/hedra/actions)
-[![Gem Version](https://badge.fury.io/rb/hedra.svg)](https://badge.fury.io/rb/hedra)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/Ruby-3.0%2B-CC342D?style=flat&logo=ruby)](https://www.ruby-lang.org/)
+[![Gem Version](https://img.shields.io/gem/v/hedra?style=flat&logo=rubygems&color=E9573F)](https://rubygems.org/gems/hedra)
+[![License](https://img.shields.io/badge/License-MIT-00A98F?style=flat)](LICENSE)
+[![Downloads](https://img.shields.io/gem/dt/hedra?style=flat&color=blue)](https://rubygems.org/gems/hedra)
 
-A comprehensive security header analyzer for modern web applications.
+> Security header analyzer with SSL/TLS validation, baseline tracking, and CI/CD integration.
 
 ## Installation
-
 ```bash
 gem install hedra
 ```
 
-## Usage
+## Quick Start
+```bash
+hedra scan https://github.com
+hedra audit https://stripe.com --json
+hedra scan -f urls.txt --format html --output report.html
+```
+
+## Commands
 
-### Scan a URL
+### scan
 
+Scan URLs for security headers with flexible output options.
 ```bash
-hedra scan https://example.com
+hedra scan https://github.com
+hedra scan -f urls.txt --concurrency 20
+hedra scan https://stripe.com --cache --rate 10/s
 ```
 
-### Detailed Audit
-
+**Key Options:**
+- `-f, --file FILE` • Read URLs from file
+- `-c, --concurrency N` • Concurrent requests (default: 10)
+- `-t, --timeout N` • Request timeout in seconds (default: 10)
+- `--rate RATE` • Rate limit: 10/s, 100/m, 1000/h
+- `--cache` • Enable response caching
+- `--cache-ttl N` • Cache TTL in seconds (default: 3600)
+- `-o, --output FILE` • Output file
+- `--format FORMAT` • table, json, csv, html (default: table)
+- `--proxy URL` • HTTP/SOCKS proxy
+- `--user-agent STRING` • Custom User-Agent
+- `--save-baseline NAME` • Save results as baseline
+- `--[no-]progress` • Show/hide progress bar
+- `--[no-]check-certificates` • SSL checks (default: enabled)
+- `--[no-]check-security-txt` • RFC 9116 checks
+
+### audit
+
+Deep security audit with detailed recommendations.
 ```bash
-hedra audit https://example.com
+hedra audit https://github.com
+hedra audit https://api.stripe.com --json --output report.json
 ```
 
-### Export as JSON
+**Options:**
+- `--json` • JSON output format
+- `-o, --output FILE` • Output file
+- `--proxy URL` • HTTP/SOCKS proxy
+- `--user-agent STRING` • Custom User-Agent
+- `-t, --timeout N` • Request timeout
+- `--[no-]check-certificates` • SSL/TLS validation
+- `--[no-]check-security-txt` • security.txt checks
+
+### watch
 
+Monitor security headers periodically.
 ```bash
-hedra audit https://example.com --json --output report.json
+hedra watch https://myapp.com --interval 3600
 ```
 
-### Scan Multiple URLs
+**Options:**
+- `--interval N` • Check interval in seconds (default: 3600)
 
+### compare
+
+Compare security headers between environments.
 ```bash
-# Create urls.txt with one URL per line
-hedra scan -f urls.txt --concurrency 20
+hedra compare https://staging.myapp.com https://myapp.com
 ```
 
-### Monitor Over Time
+### ci_check
 
+CI/CD-friendly check with exit codes and thresholds.
 ```bash
-hedra watch https://example.com --interval 3600
+hedra ci_check https://myapp.com --threshold 85
+hedra ci_check -f urls.txt --fail-on-critical
 ```
 
-### Compare Headers
+**Options:**
+- `-f, --file FILE` • Read URLs from file
+- `--threshold N` • Minimum score threshold (default: 80)
+- `--fail-on-critical` • Fail on critical issues (default: true)
+
+**Exit Codes:**
+- `0` • All checks passed
+- `1` • Score below threshold or critical issues found
 
+### baseline
+
+Track security posture changes over time.
 ```bash
-hedra compare https://staging.example.com https://prod.example.com
+hedra baseline list
+hedra baseline compare production-v1 -f urls.txt
+hedra baseline delete production-v1
 ```
 
-## Security Headers Checked
+### cache
 
-- **Content-Security-Policy (CSP)** - Prevents XSS attacks
-- **Strict-Transport-Security (HSTS)** - Enforces HTTPS
-- **X-Frame-Options** - Prevents clickjacking
-- **X-Content-Type-Options** - Prevents MIME-sniffing
-- **Referrer-Policy** - Controls referrer information
-- **Permissions-Policy** - Controls browser features
-- **Cross-Origin-Opener-Policy (COOP)**
-- **Cross-Origin-Embedder-Policy (COEP)**
-- **Cross-Origin-Resource-Policy (CORP)**
+Manage response cache for faster repeated scans.
+```bash
+hedra cache clear
+hedra cache clear-expired
+```
 
-## Options
+### plugin
 
+Extend functionality with custom security checks.
 ```bash
-# Concurrent scanning
-hedra scan -f urls.txt --concurrency 20 --timeout 15
+hedra plugin list
+hedra plugin install path/to/plugin.rb
+hedra plugin remove plugin_name
+```
 
-# Through a proxy
-hedra scan https://example.com --proxy http://127.0.0.1:8080
+## Security Checks
 
-# Custom User-Agent
-hedra scan https://example.com --user-agent "MyBot/1.0"
+### HTTP Headers Analyzed
 
-# Follow redirects
-hedra scan https://example.com --follow-redirects
+| Header | Weight | Purpose |
+|--------|--------|---------|
+| Content-Security-Policy | 25 pts | Prevent XSS and injection attacks |
+| Strict-Transport-Security | 25 pts | Enforce HTTPS connections |
+| X-Frame-Options | 15 pts | Prevent clickjacking |
+| X-Content-Type-Options | 10 pts | Stop MIME-type sniffing |
+| Referrer-Policy | 10 pts | Control referrer information |
+| Permissions-Policy | 5 pts | Manage browser features |
+| Cross-Origin-Opener-Policy | 5 pts | Isolate browsing context |
+| Cross-Origin-Embedder-Policy | 3 pts | Enable cross-origin isolation |
+| Cross-Origin-Resource-Policy | 2 pts | Control resource loading |
 
-# Export as CSV
-hedra scan -f urls.txt --output results.csv --format csv
-```
+### Additional Validations
+
+**SSL/TLS Checks:**
+- Certificate expiry dates
+- Signature algorithm strength
+- Key size validation
+- Chain verification
+
+**RFC 9116:**
+- security.txt file presence and format
+
+### Scoring System
+
+**Base:** 100 points from header weights
+
+**Penalties:**
+- Critical issue: -20 points
+- Warning: -10 points
+- Info: -5 points
 
 ## Configuration
 
 Create `~/.hedra/config.yml`:
-
 ```yaml
+# HTTP settings
 timeout: 10
 concurrency: 10
-user_agent: "Hedra/1.0.0"
-output_format: table
+user_agent: "Hedra/2.0.0"
+follow_redirects: true
+max_retries: 3
+
+# Performance
+cache_enabled: false
+cache_ttl: 3600
+rate_limit: "10/s"
+
+# Security checks
+check_certificates: true
+check_security_txt: false
+
+# Output
+output_format: "table"
+progress_bar: true
+
+# Circuit breaker
+circuit_breaker_threshold: 5
+circuit_breaker_timeout: 60
 ```
 
 ## Custom Rules
 
-Create `~/.hedra/rules.yml`:
-
+Define organization-specific policies in `~/.hedra/rules.yml`:
 ```yaml
 rules:
   - header: "X-Custom-Security"
     type: missing
     severity: warning
     message: "Custom security header is missing"
-    fix: "Add X-Custom-Security header"
+    fix: "Add X-Custom-Security: enabled"
+    
+  - header: "Server"
+    type: pattern
+    pattern: "^(Apache|nginx)"
+    severity: info
+    message: "Server header exposes software version"
+    fix: "Remove or obfuscate Server header"
 ```
 
-## Plugins
+**Rule Types:**
+- `missing` • Header should be present
+- `pattern` • Header value must match regex
 
-Create custom header checks:
+**Severity Levels:**
+- `critical` • -20 points, immediate action required
+- `warning` • -10 points, should be addressed
+- `info` • -5 points, best practice
 
+## Plugin System
+
+Create custom checks in `~/.hedra/plugins/`:
 ```ruby
-# ~/.hedra/plugins/my_plugin.rb
+# ~/.hedra/plugins/corporate_policy.rb
 module Hedra
-  class MyPlugin < Plugin
+  class CorporatePolicyPlugin < Plugin
     def self.check(headers)
       findings = []
-      unless headers.key?('x-my-header')
+      
+      # Enforce corporate header
+      unless headers.key?('x-corp-security')
+        findings << {
+          header: 'x-corp-security',
+          issue: 'Corporate security header missing',
+          severity: :critical,
+          recommended_fix: 'Add X-Corp-Security: v2'
+        }
+      end
+      
+      # Check version disclosure
+      if headers['server']&.match?(/\d+\.\d+/)
         findings << {
-          header: 'x-my-header',
-          issue: 'Custom header missing',
+          header: 'server',
+          issue: 'Server version exposed',
           severity: :warning,
-          recommended_fix: 'Add X-My-Header'
+          recommended_fix: 'Remove version from Server header'
         }
       end
+      
       findings
     end
   end
 end
 ```
 
-Install plugin:
-
+**Management:**
 ```bash
-hedra plugin install ~/.hedra/plugins/my_plugin.rb
+hedra plugin install ~/.hedra/plugins/corporate_policy.rb
 hedra plugin list
+hedra plugin remove corporate_policy
 ```
 
-## Development
+## CI/CD Integration
+
+### GitHub Actions
+```yaml
+name: Security Headers Check
+
+on: [push, pull_request]
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+      
+      - name: Install Hedra
+        run: gem install hedra
+      
+      - name: Run Security Check
+        run: hedra ci_check ${{ secrets.APP_URL }} --threshold 85
+      
+      - name: Generate HTML Report
+        if: always()
+        run: hedra scan ${{ secrets.APP_URL }} --output report.html --format html
+      
+      - name: Upload Report
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: security-report
+          path: report.html
+```
+
+### GitLab CI
+```yaml
+security_headers:
+  image: ruby:3.2
+  script:
+    - gem install hedra
+    - hedra ci_check $APP_URL --threshold 85
+    - hedra scan $APP_URL --output report.json --format json
+  artifacts:
+    reports:
+      junit: report.json
+    paths:
+      - report.json
+  only:
+    - merge_requests
+    - main
+```
+
+### Jenkins Pipeline
+```groovy
+pipeline {
+    agent any
+    
+    stages {
+        stage('Security Headers') {
+            steps {
+                sh 'gem install hedra'
+                sh 'hedra ci_check ${APP_URL} --threshold 85'
+            }
+        }
+    }
+    
+    post {
+        always {
+            sh 'hedra scan ${APP_URL} --output report.html --format html'
+            publishHTML([
+                reportDir: '.',
+                reportFiles: 'report.html',
+                reportName: 'Security Report'
+            ])
+        }
+    }
+}
+```
+
+## Export Formats
 
+### Table (Default)
 ```bash
-# Clone and install
+hedra scan https://github.com
+```
+
+Clean, colored terminal output with scores and recommendations.
+
+### JSON
+```bash
+hedra scan https://stripe.com --output report.json --format json
+```
+
+Structured data for automation and parsing.
+
+### CSV
+```bash
+hedra scan -f urls.txt --output report.csv --format csv
+```
+
+Import into spreadsheets for analysis and tracking.
+
+### HTML
+```bash
+hedra scan -f urls.txt --output report.html --format html
+```
+
+Interactive report with sorting, filtering, and charts.
+
+## Real-World Examples
+
+### Basic Security Audit
+```bash
+hedra scan https://myapp.com
+```
+
+### Production Deployment Check
+```bash
+# Save baseline after deployment
+hedra scan -f production-urls.txt --save-baseline prod-v2.1.0
+
+# Compare before next deployment
+hedra baseline compare prod-v2.1.0 -f production-urls.txt
+```
+
+### High-Volume Scanning
+```bash
+# Scan 1000 URLs with rate limiting and caching
+hedra scan -f large-list.txt \
+  --concurrency 50 \
+  --rate 20/s \
+  --cache \
+  --output results.json \
+  --format json
+```
+
+### Continuous Monitoring
+```bash
+# Check every hour
+hedra watch https://api.myapp.com --interval 3600
+```
+
+### Environment Comparison
+```bash
+hedra compare https://staging.myapp.com https://myapp.com
+```
+
+### Proxy-Based Testing
+```bash
+# Route through Burp Suite
+hedra scan https://target.com --proxy http://127.0.0.1:8080
+```
+
+### Custom User-Agent
+```bash
+hedra scan https://myapp.com --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0)"
+```
+
+## Performance Tuning
+
+### Caching Strategy
+```bash
+# Enable caching for repeated scans
+hedra scan -f urls.txt --cache --cache-ttl 7200
+
+# Clear cache when needed
+hedra cache clear
+```
+
+### Rate Limiting
+```bash
+# Conservative approach
+hedra scan -f urls.txt --rate 10/s --concurrency 5
+
+# Aggressive scanning
+hedra scan -f urls.txt --rate 100/s --concurrency 50
+```
+
+### Timeout Configuration
+```bash
+# Fast scan for responsive servers
+hedra scan -f urls.txt --timeout 5
+
+# Patient scan for slow servers
+hedra scan -f urls.txt --timeout 30
+```
+
+## Development
+```bash
+# Clone and setup
 git clone https://github.com/blackstack/hedra.git
 cd hedra
 bundle install
@@ -149,67 +459,45 @@ bundle install
 # Run tests
 bundle exec rspec
 
-# Run linter
+# Check code style
 bundle exec rubocop
 
 # Build gem
 rake build
+gem install pkg/hedra-*.gem
 ```
 
-## Output Examples
-
-### Table Format
+## Troubleshooting
 
+### SSL Certificate Errors
+```bash
+# Skip certificate validation
+hedra scan https://self-signed.badssl.com --no-check-certificates
 ```
-https://example.com
-Score: 75/100
-Timestamp: 2025-11-12T10:30:00Z
 
-┌─────────────────────────────┬──────────────────────────────┬──────────────┐
-│ Header                      │ Issue                        │ Severity     │
-├─────────────────────────────┼──────────────────────────────┼──────────────┤
-│ x-frame-options             │ Header is missing            │ ● WARNING    │
-│ referrer-policy             │ Header is missing            │ ● INFO       │
-└─────────────────────────────┴──────────────────────────────┴──────────────┘
+### Rate Limiting Issues
+```bash
+# Reduce load on target server
+hedra scan -f urls.txt --concurrency 1 --rate 1/s
 ```
 
-### JSON Format
-
-```json
-{
-  "url": "https://example.com",
-  "timestamp": "2025-11-12T10:30:00Z",
-  "score": 75,
-  "headers": {
-    "content-security-policy": "default-src 'self'",
-    "strict-transport-security": "max-age=31536000"
-  },
-  "findings": [
-    {
-      "header": "x-frame-options",
-      "issue": "X-Frame-Options header is missing",
-      "severity": "warning",
-      "recommended_fix": "Add X-Frame-Options: DENY or SAMEORIGIN"
-    }
-  ]
-}
+### Timeout Problems
+```bash
+# Increase timeout for slow servers
+hedra scan https://slow-server.com --timeout 60
 ```
 
-## Contributing
+## Resources
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Write tests for your changes
-4. Ensure tests pass (`bundle exec rspec`)
-5. Ensure linting passes (`bundle exec rubocop`)
-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
+**GitHub:** https://github.com/blackstack/hedra  
+**RubyGems:** https://rubygems.org/gems/hedra  
+**Issues:** https://github.com/blackstack/hedra/issues  
+**OWASP Headers:** https://owasp.org/www-project-secure-headers/
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-Built by [BlackStack](https://github.com/bl4ckstack)
+**Built by [BlackStack](https://github.com/blackstack)** • Securing the web, one header at a time.