Skip to content
/ hedra Public

Hedra — Command-line tool to analyze HTTP security headers and detect missing protections like CSP, HSTS, and X-Frame-Options.

License

MIT license
8 stars 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

bl4ckstack/hedra

BranchesTags

Repository files navigation

Hedra

Ruby Gem Version License Downloads

Security header analyzer with SSL/TLS validation, baseline tracking, and CI/CD integration.

Hedra Logo

Installation

gem install hedra

Quick Start

hedra scan https://github.com
hedra audit https://stripe.com --json
hedra scan -f urls.txt --format html --output report.html

Commands

scan

Scan URLs for security headers with flexible output options.

hedra scan https://github.com
hedra scan -f urls.txt --concurrency 20
hedra scan https://stripe.com --cache --rate 10/s

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.

hedra audit https://github.com
hedra audit https://api.stripe.com --json --output report.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.

hedra watch https://myapp.com --interval 3600

Options:

  • --interval N • Check interval in seconds (default: 3600)

compare

Compare security headers between environments.

hedra compare https://staging.myapp.com https://myapp.com

ci_check

CI/CD-friendly check with exit codes and thresholds.

hedra ci_check https://myapp.com --threshold 85
hedra ci_check -f urls.txt --fail-on-critical

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.

hedra baseline list
hedra baseline compare production-v1 -f urls.txt
hedra baseline delete production-v1

cache

Manage response cache for faster repeated scans.

hedra cache clear
hedra cache clear-expired

plugin

Extend functionality with custom security checks.

hedra plugin list
hedra plugin install path/to/plugin.rb
hedra plugin remove plugin_name

Security Checks

HTTP Headers Analyzed

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

Additional Validations

SSL/TLS Checks:

  • Certificate expiry dates
  • Signature algorithm strength
  • Key size validation
  • Chain verification
  • TLS version detection (TLS 1.2/1.3)
  • Certificate Transparency log verification

Protocol Security:

  • HTTP/2 and HTTP/3 detection
  • TLS version enforcement
  • Insecure protocol warnings

CORS Security:

  • Access-Control-Allow-Origin validation
  • Wildcard and null origin detection
  • Credentials with wildcard prevention
  • Dangerous HTTP methods detection
  • Sensitive header exposure checks

Subresource Integrity (SRI):

  • External script/stylesheet SRI validation
  • Crossorigin attribute verification
  • Same-origin resource detection

DNS Security:

  • DNSSEC validation
  • CAA (Certificate Authority Authorization) records
  • DNS-based security policy enforcement

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:

# HTTP settings
timeout: 10
concurrency: 10
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

Define organization-specific policies in ~/.hedra/rules.yml:

rules:
  - header: "X-Custom-Security"
    type: missing
    severity: warning
    message: "Custom security header is missing"
    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"

Rule Types:

  • missing • Header should be present
  • pattern • Header value must match regex

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/:

# ~/.hedra/plugins/corporate_policy.rb
module Hedra
  class CorporatePolicyPlugin < Plugin
    def self.check(headers)
      findings = []
      
      # 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: 'server',
          issue: 'Server version exposed',
          severity: :warning,
          recommended_fix: 'Remove version from Server header'
        }
      end
      
      findings
    end
  end
end

Management:

hedra plugin install ~/.hedra/plugins/corporate_policy.rb
hedra plugin list
hedra plugin remove corporate_policy

CI/CD Integration

GitHub Actions

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

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

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)

hedra scan https://github.com

Clean, colored terminal output with scores and recommendations.

JSON

hedra scan https://stripe.com --output report.json --format json

Structured data for automation and parsing.

CSV

hedra scan -f urls.txt --output report.csv --format csv

Import into spreadsheets for analysis and tracking.

HTML

hedra scan -f urls.txt --output report.html --format html

Interactive report with sorting, filtering, and charts.

Advanced Security Checks

Subresource Integrity (SRI)

Validates that external scripts and stylesheets use SRI attributes to prevent tampering:

hedra scan https://myapp.com --check-sri

Checks:

  • External resources without integrity attributes
  • Missing crossorigin attributes
  • Same-origin vs cross-origin detection

CORS Policy Analysis

Validates Cross-Origin Resource Sharing configuration for security issues:

hedra scan https://api.myapp.com --check-cors

Detects:

  • Wildcard origins with credentials (critical vulnerability)
  • Null origin allowance
  • Insecure HTTP origins
  • Dangerous HTTP methods (TRACE, TRACK)
  • Overly permissive configurations
  • Sensitive header exposure

Protocol Version Detection

Checks HTTP and TLS protocol versions:

hedra scan https://myapp.com --check-protocol

Validates:

  • HTTP/1.1 vs HTTP/2 vs HTTP/3
  • TLS 1.2/1.3 enforcement
  • Deprecated protocol detection (SSLv3, TLS 1.0/1.1)
  • Protocol upgrade recommendations

Certificate Transparency

Verifies certificates are logged in CT logs:

hedra audit https://myapp.com --check-ct

Checks:

  • SCT (Signed Certificate Timestamp) presence
  • Multiple independent CT logs
  • SCT delivery methods (extension, OCSP, TLS)

DNS Security

Validates DNS-level security features:

hedra audit https://myapp.com --check-dns

Validates:

  • DNSSEC enablement
  • CAA records for certificate issuance control
  • CAA tags (issue, issuewild, iodef)
  • DNS-based security policies

Combined Advanced Scan

Run all advanced checks together:

hedra audit https://myapp.com \
  --check-sri \
  --check-cors \
  --check-protocol \
  --check-ct \
  --check-dns \
  --output comprehensive-report.json

Real-World Examples

Basic Security Audit

hedra scan https://myapp.com

Comprehensive Security Audit with All Checks

hedra audit https://myapp.com \
  --check-sri \
  --check-ct \
  --check-dns \
  --json \
  --output full-audit.json

Quick CORS and Protocol Check

hedra scan https://api.myapp.com \
  --check-cors \
  --check-protocol

Production Deployment Check

# 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

# 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

# Check every hour
hedra watch https://api.myapp.com --interval 3600

Environment Comparison

hedra compare https://staging.myapp.com https://myapp.com

Proxy-Based Testing

# Route through Burp Suite
hedra scan https://target.com --proxy http://127.0.0.1:8080

Custom User-Agent

hedra scan https://myapp.com --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0)"

Performance Tuning

Caching Strategy

# Enable caching for repeated scans
hedra scan -f urls.txt --cache --cache-ttl 7200

# Clear cache when needed
hedra cache clear

Rate Limiting

# 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

# 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

# Clone and setup
git clone https://github.com/blackstack/hedra.git
cd hedra
bundle install

# Run tests
bundle exec rspec

# Check code style
bundle exec rubocop

# Build gem
rake build
gem install pkg/hedra-*.gem

Troubleshooting

SSL Certificate Errors

# Skip certificate validation
hedra scan https://self-signed.badssl.com --no-check-certificates

Rate Limiting Issues

# Reduce load on target server
hedra scan -f urls.txt --concurrency 1 --rate 1/s

Timeout Problems

# Increase timeout for slow servers
hedra scan https://slow-server.com --timeout 60

Resources

GitHub: https://github.com/bl4ckstack/hedra
RubyGems: https://rubygems.org/gems/hedra
Issues: https://github.com/bl4ckstack/hedra/issues
OWASP Headers: https://owasp.org/www-project-secure-headers/

License

MIT License - see LICENSE for details.

About

Hedra — Command-line tool to analyze HTTP security headers and detect missing protections like CSP, HSTS, and X-Frame-Options.

Topics

ruby cli security rubygems cybersecurity web-security pentesting information-security vulnerability-assessment http-headers hedra

Resources

Readme

License

MIT license
Activity

Stars

8 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

6 tags

Packages

No packages published

Contributors 2

  •  
  •  

Languages