hedra 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab829bc24159c4c23c53be1f82efbc8f61374401c2ae7f882140c8bb8de8e37f
+  data.tar.gz: 9a83e90dfb32a981e978c57c37973dee68d55adfdebe071517127ce9a98f1d92
+SHA512:
+  metadata.gz: 2f499c341d3ed325fe3be5eb4e9ab6db27a0e3c54441c9dc19d48a6631d79f8c0dcfea050f6d4cc7322c7bcba4d9d3a7149a71044db42bae3c697edc4e360956
+  data.tar.gz: 8b242f020e24deb65b6c218938532d43ddcdc15963015e644c8cd7edc4c5244d04547e38133fae18f139841dd37244a46387186660a2fec4b236257a0f9e5fea

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hedra Team
+
+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,342 @@
+# Hedra 🛡️
+
+A comprehensive security header analyzer for modern web applications. Scan, audit, and monitor HTTP security headers with ease.
+
+```
+ _   _          _           
+| | | | ___  __| |_ __ __ _ 
+| |_| |/ _ \/ _` | '__/ _` |
+|  _  |  __/ (_| | | | (_| |
+|_| |_|\___|\__,_|_|  \__,_|
+                             
+Security Header Analyzer
+```
+
+## Features
+
+- 🔍 **Comprehensive Scanning** - Analyze security headers for single or multiple URLs
+- 🎯 **Deep Auditing** - Detailed security header analysis with recommendations
+- 👁️ **Continuous Monitoring** - Watch URLs for header changes over time
+- 📊 **Multiple Output Formats** - Table, JSON, and CSV export options
+- 🔌 **Plugin Architecture** - Extend with custom header checks
+- ⚡ **Concurrent Scanning** - Fast parallel URL scanning with configurable concurrency
+- 🌐 **Proxy Support** - HTTP and SOCKS proxy compatibility
+- 🎨 **Beautiful CLI** - Color-coded output with severity badges
+- 📈 **Security Scoring** - 0-100 score based on header coverage
+
+## Installation
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/hedra/hedra.git
+cd hedra
+
+# Install dependencies
+bundle install
+
+# Build the gem
+rake build
+
+# Install the gem
+gem install pkg/hedra-1.0.0.gem
+```
+
+### Quick Start
+
+```bash
+bundle install
+chmod +x bin/hedra
+bin/hedra --help
+```
+
+## Usage
+
+### Basic Scanning
+
+Scan a single URL:
+```bash
+hedra scan https://example.com
+```
+
+Scan multiple URLs from a file:
+```bash
+hedra scan -f urls.txt
+```
+
+### Deep Audit
+
+Perform detailed security analysis:
+```bash
+hedra audit https://example.com
+```
+
+Export audit results as JSON:
+```bash
+hedra audit https://example.com --json --output result.json
+```
+
+### Advanced Scanning
+
+Concurrent scanning with custom settings:
+```bash
+hedra scan -f urls.txt --concurrency 20 --timeout 15
+```
+
+Scan through a proxy:
+```bash
+hedra scan https://example.com --proxy http://127.0.0.1:8080
+```
+
+Custom User-Agent and follow redirects:
+```bash
+hedra scan https://example.com --user-agent "MyBot/1.0" --follow-redirects
+```
+
+### Continuous Monitoring
+
+Watch a URL and check every hour:
+```bash
+hedra watch https://example.com --interval 3600
+```
+
+### Compare Headers
+
+Compare security headers between two URLs:
+```bash
+hedra compare https://staging.example.com https://prod.example.com
+```
+
+### Export Results
+
+Export scan results:
+```bash
+hedra scan -f urls.txt --output results.csv --format csv
+```
+
+### Plugin Management
+
+List installed plugins:
+```bash
+hedra plugin list
+```
+
+Install a custom plugin:
+```bash
+hedra plugin install path/to/plugin.rb
+```
+
+Remove a plugin:
+```bash
+hedra plugin remove my_plugin
+```
+
+## Security Headers Checked
+
+Hedra analyzes the following security headers:
+
+### Critical Headers
+- **Content-Security-Policy (CSP)** - Prevents XSS and injection attacks
+- **Strict-Transport-Security (HSTS)** - Enforces HTTPS connections
+
+### Important Headers
+- **X-Frame-Options** - Prevents clickjacking attacks
+- **X-Content-Type-Options** - Prevents MIME-sniffing attacks
+
+### Recommended Headers
+- **Referrer-Policy** - Controls referrer information
+- **Permissions-Policy** - Controls browser features
+- **Cross-Origin-Opener-Policy (COOP)** - Isolates browsing context
+- **Cross-Origin-Embedder-Policy (COEP)** - Controls resource embedding
+- **Cross-Origin-Resource-Policy (CORP)** - Controls resource sharing
+
+## Configuration
+
+Create a config file at `~/.hedra/config.yml`:
+
+```yaml
+timeout: 10
+concurrency: 10
+follow_redirects: false
+user_agent: "Hedra/1.0.0"
+output_format: table
+```
+
+### Custom Rules
+
+Add custom header checks 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"
+  
+  - header: "Server"
+    type: pattern
+    pattern: "(Apache|nginx|IIS)"
+    severity: info
+    message: "Server header exposes server software"
+    fix: "Remove or obfuscate Server header"
+```
+
+## Plugin Development
+
+Create custom plugins to extend Hedra's functionality:
+
+```ruby
+# ~/.hedra/plugins/my_plugin.rb
+module Hedra
+  class MyPlugin < Plugin
+    def self.check(headers)
+      findings = []
+      
+      unless headers.key?('x-my-header')
+        findings << {
+          header: 'x-my-header',
+          issue: 'My custom header is missing',
+          severity: :warning,
+          recommended_fix: 'Add X-My-Header'
+        }
+      end
+      
+      findings
+    end
+  end
+end
+```
+
+## Output Examples
+
+### Table Output
+```
+https://example.com
+Score: 75/100
+Timestamp: 2025-11-12T10:30:00Z
+
+┌─────────────────────────────┬──────────────────────────────┬──────────┐
+│ Header                      │ Issue                        │ Severity │
+├─────────────────────────────┼──────────────────────────────┼──────────┤
+│ permissions-policy          │ Header is missing            │ ● INFO   │
+│ cross-origin-opener-policy  │ Header is missing            │ ● INFO   │
+└─────────────────────────────┴──────────────────────────────┴──────────┘
+```
+
+### JSON Output
+```json
+{
+  "url": "https://example.com",
+  "timestamp": "2025-11-12T10:30:00Z",
+  "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"
+    }
+  ],
+  "score": 75
+}
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+bundle exec rspec --format documentation
+
+# Run specific test file
+bundle exec rspec spec/hedra/analyzer_spec.rb
+```
+
+### Linting
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Building
+
+```bash
+# Build gem
+rake build
+
+# Install locally
+gem install pkg/hedra-1.0.0.gem
+```
+
+## CI/CD
+
+Hedra includes GitHub Actions CI configuration that:
+- Runs tests on Ruby 3.0, 3.1, and 3.2
+- Executes RuboCop linting
+- Builds the gem package
+
+## Architecture
+
+### Core Components
+
+- **CLI** - Thor-based command-line interface with subcommands
+- **Analyzer** - Core logic for header analysis and validation
+- **HttpClient** - HTTP wrapper with retry logic, proxy support, and TLS verification
+- **Scorer** - Calculates security scores based on header coverage
+- **PluginManager** - Discovers and executes custom plugins
+- **Exporter** - Handles JSON and CSV output formats
+
+### Design Decisions
+
+1. **Modular Architecture** - Each header check is isolated, making it easy to add new checks
+2. **Secure Defaults** - TLS verification on, no redirect following, conservative timeouts
+3. **Thread-Safe Concurrency** - Uses Ruby's concurrent-ruby gem for safe parallel scanning
+4. **Extensible Plugin System** - Simple base class for custom header checks
+5. **Comprehensive Testing** - WebMock stubs prevent live network calls in tests
+
+## Contributing
+
+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
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📖 Documentation: [GitHub Wiki](https://github.com/hedra/hedra/wiki)
+- 🐛 Issues: [GitHub Issues](https://github.com/hedra/hedra/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/hedra/hedra/discussions)
+
+## Acknowledgments
+
+Built with:
+- [Thor](https://github.com/rails/thor) - CLI framework
+- [HTTP.rb](https://github.com/httprb/http) - HTTP client
+- [TTY::Table](https://github.com/piotrmurach/tty-table) - Terminal tables
+- [Pastel](https://github.com/piotrmurach/pastel) - Terminal colors
+- [RSpec](https://rspec.info/) - Testing framework
+
+---
+
+Made with ❤️ by the Hedra Team

data/bin/hedra

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/hedra'
+
+begin
+  Hedra::CLI.start(ARGV)
+rescue Hedra::Error => e
+  warn "ERROR: #{e.message}"
+  exit 1
+rescue Interrupt
+  warn "\nInterrupted"
+  exit 130
+end

data/config/example_config.yml

@@ -0,0 +1,17 @@
+# Hedra Configuration Example
+# Copy to ~/.hedra/config.yml to customize
+
+# HTTP client settings
+timeout: 10
+concurrency: 10
+follow_redirects: false
+user_agent: "Hedra/1.0.0"
+
+# Proxy settings (optional)
+# proxy: "http://127.0.0.1:8080"
+
+# Output preferences
+output_format: table  # table, json, or csv
+
+# Rate limiting (optional)
+# rate_limit: "5/s"

data/config/example_rules.yml

@@ -0,0 +1,16 @@
+# Custom security header rules
+# Copy to ~/.hedra/rules.yml to enable
+
+rules:
+  - header: "X-Custom-Security"
+    type: missing
+    severity: warning
+    message: "Custom security header is missing"
+    fix: "Add X-Custom-Security header"
+  
+  - header: "Server"
+    type: pattern
+    pattern: "(Apache|nginx|IIS)"
+    severity: info
+    message: "Server header exposes server software"
+    fix: "Remove or obfuscate Server header"

data/lib/hedra/analyzer.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Hedra
+  class Analyzer
+    SECURITY_HEADERS = {
+      'content-security-policy' => {
+        required: true,
+        severity: :critical,
+        message: 'Content-Security-Policy header is missing',
+        fix: "Add CSP header: Content-Security-Policy: default-src 'self'"
+      },
+      'strict-transport-security' => {
+        required: true,
+        severity: :critical,
+        message: 'Strict-Transport-Security (HSTS) header is missing',
+        fix: 'Add HSTS header: Strict-Transport-Security: max-age=31536000; includeSubDomains'
+      },
+      'x-frame-options' => {
+        required: true,
+        severity: :warning,
+        message: 'X-Frame-Options header is missing',
+        fix: 'Add X-Frame-Options: DENY or SAMEORIGIN'
+      },
+      'x-content-type-options' => {
+        required: true,
+        severity: :warning,
+        message: 'X-Content-Type-Options header is missing',
+        fix: 'Add X-Content-Type-Options: nosniff'
+      },
+      'referrer-policy' => {
+        required: true,
+        severity: :info,
+        message: 'Referrer-Policy header is missing',
+        fix: 'Add Referrer-Policy: strict-origin-when-cross-origin'
+      },
+      'permissions-policy' => {
+        required: false,
+        severity: :info,
+        message: 'Permissions-Policy header is missing',
+        fix: 'Consider adding Permissions-Policy to control browser features'
+      },
+      'cross-origin-opener-policy' => {
+        required: false,
+        severity: :info,
+        message: 'Cross-Origin-Opener-Policy header is missing',
+        fix: 'Add Cross-Origin-Opener-Policy: same-origin'
+      },
+      'cross-origin-embedder-policy' => {
+        required: false,
+        severity: :info,
+        message: 'Cross-Origin-Embedder-Policy header is missing',
+        fix: 'Add Cross-Origin-Embedder-Policy: require-corp'
+      },
+      'cross-origin-resource-policy' => {
+        required: false,
+        severity: :info,
+        message: 'Cross-Origin-Resource-Policy header is missing',
+        fix: 'Add Cross-Origin-Resource-Policy: same-origin'
+      }
+    }.freeze
+
+    def initialize
+      @plugin_manager = PluginManager.new
+      @scorer = Scorer.new
+      load_custom_rules
+    end
+
+    def analyze(url, headers)
+      normalized_headers = normalize_headers(headers)
+      findings = []
+
+      # Check for missing required headers
+      SECURITY_HEADERS.each do |header_name, config|
+        next unless config[:required]
+
+        next if normalized_headers.key?(header_name)
+
+        findings << {
+          header: header_name,
+          issue: config[:message],
+          severity: config[:severity],
+          recommended_fix: config[:fix]
+        }
+      end
+
+      # Validate header values
+      findings.concat(validate_header_values(normalized_headers))
+
+      # Apply custom rules
+      findings.concat(apply_custom_rules(normalized_headers))
+
+      # Run plugin checks
+      findings.concat(@plugin_manager.run_checks(normalized_headers))
+
+      # Calculate security score
+      score = @scorer.calculate(normalized_headers, findings)
+
+      {
+        url: url,
+        timestamp: Time.now.iso8601,
+        headers: headers,
+        findings: findings,
+        score: score
+      }
+    end
+
+    private
+
+    def normalize_headers(headers)
+      headers.transform_keys { |k| k.to_s.downcase }
+    end
+
+    def validate_header_values(headers)
+      findings = []
+
+      # Validate CSP
+      if headers['content-security-policy']
+        csp = headers['content-security-policy']
+        if csp.include?('unsafe-inline') || csp.include?('unsafe-eval')
+          findings << {
+            header: 'content-security-policy',
+            issue: 'CSP contains unsafe directives (unsafe-inline or unsafe-eval)',
+            severity: :warning,
+            recommended_fix: 'Remove unsafe-inline and unsafe-eval, use nonces or hashes'
+          }
+        end
+      end
+
+      # Validate HSTS
+      if headers['strict-transport-security']
+        hsts = headers['strict-transport-security']
+        if hsts =~ /max-age=(\d+)/
+          max_age = ::Regexp.last_match(1).to_i
+          if max_age < 31_536_000
+            findings << {
+              header: 'strict-transport-security',
+              issue: 'HSTS max-age is less than 1 year (31536000 seconds)',
+              severity: :warning,
+              recommended_fix: 'Set max-age to at least 31536000'
+            }
+          end
+        end
+      end
+
+      # Validate X-Frame-Options
+      if headers['x-frame-options']
+        xfo = headers['x-frame-options'].upcase
+        unless %w[DENY SAMEORIGIN].include?(xfo.split.first)
+          findings << {
+            header: 'x-frame-options',
+            issue: 'X-Frame-Options has invalid value',
+            severity: :warning,
+            recommended_fix: 'Use DENY or SAMEORIGIN'
+          }
+        end
+      end
+
+      # Validate X-Content-Type-Options
+      if headers['x-content-type-options']
+        xcto = headers['x-content-type-options'].downcase
+        unless xcto == 'nosniff'
+          findings << {
+            header: 'x-content-type-options',
+            issue: 'X-Content-Type-Options should be "nosniff"',
+            severity: :info,
+            recommended_fix: 'Set to nosniff'
+          }
+        end
+      end
+
+      findings
+    end
+
+    def load_custom_rules
+      @custom_rules = []
+      config_path = File.expand_path('~/.hedra/rules.yml')
+      return unless File.exist?(config_path)
+
+      rules = YAML.load_file(config_path)
+      @custom_rules = rules['rules'] || []
+    rescue StandardError => e
+      warn "Failed to load custom rules: #{e.message}"
+    end
+
+    def apply_custom_rules(headers)
+      findings = []
+
+      @custom_rules.each do |rule|
+        header_name = rule['header'].downcase
+        pattern = Regexp.new(rule['pattern']) if rule['pattern']
+
+        if rule['type'] == 'missing' && !headers.key?(header_name)
+          findings << {
+            header: header_name,
+            issue: rule['message'],
+            severity: rule['severity'].to_sym,
+            recommended_fix: rule['fix']
+          }
+        elsif rule['type'] == 'pattern' && headers[header_name]
+          if pattern && headers[header_name] =~ pattern
+            findings << {
+              header: header_name,
+              issue: rule['message'],
+              severity: rule['severity'].to_sym,
+              recommended_fix: rule['fix']
+            }
+          end
+        end
+      end
+
+      findings
+    end
+  end
+end