header_scanner.py

import sys
import requests
import argparse
import json
from urllib.parse import urlparse


class HeaderScanner:
    DEFAULT_CLIENT_HEADERS = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0",
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "Accept-Language": "en-US,en;q=0.5",
        "Upgrade-Insecure-Requests": "1",
    }

    SECURITY_HEADERS = {
        "Strict-Transport-Security": "Enforces HTTPS (HSTS)",
        "Content-Security-Policy": "Mitigates XSS and data injection",
        "X-Content-Type-Options": 'Prevents MIME sniffing (should be "nosniff")',
        "X-Frame-Options": 'Prevents clickjacking (should be "DENY" or "SAMEORIGIN")',
        "X-XSS-Protection": "Legacy XSS protection (modern browsers ignore)",
        "Referrer-Policy": "Controls referrer information",
        "Permissions-Policy": "Controls browser feature access",
    }

    SENSITIVE_HEADERS = [
        "Server",
        "X-Powered-By",
        "X-AspNet-Version",
        "X-AspNetMvc-Version",
        "X-Runtime",
        "X-Version",
    ]

    # Grading system configuration
    # Baseline points for using HTTPS (awarded automatically if URL is https)
    HTTPS_BASELINE = 25
    # HSTS preload API
    HSTS_PRELOAD_API = "https://hstspreload.org/api/v2/status"

    HEADER_WEIGHTS = {
        "Strict-Transport-Security": 25,  # Critical - enforces HTTPS
        "Content-Security-Policy": 20,  # Critical - XSS/injection protection
        "X-Content-Type-Options": 10,  # Important - MIME sniffing
        "X-Frame-Options": 10,  # Important - clickjacking
        "Referrer-Policy": 5,  # Moderate - privacy
        "Permissions-Policy": 5,  # Moderate - feature access
        "X-XSS-Protection": 0,  # Deprecated - browsers ignore this
    }

    EXPECTED_VALUES = {
        "X-Content-Type-Options": lambda v: v.lower() == "nosniff",
        "X-Frame-Options": lambda v: v.upper() in ("DENY", "SAMEORIGIN"),
        "Referrer-Policy": lambda v: v.lower()
        in (
            "no-referrer",
            "no-referrer-when-downgrade",
            "origin",
            "origin-when-cross-origin",
            "same-origin",
            "strict-origin",
            "strict-origin-when-cross-origin",
        ),
    }

    # Reduced penalty - Server header is common and low-risk
    SENSITIVE_PENALTY = 2  # Points deducted per sensitive header exposed

    GRADE_THRESHOLDS = [
        (90, "A+", "Excellent"),
        (75, "A", "Very Good"),
        (60, "B", "Good"),
        (45, "C", "Acceptable"),
        (30, "D", "Poor"),
        (0, "F", "Critical"),
    ]

    def __init__(self, url, args):
        self.args = args
        self.url = self._validate_url(url)
        self.headers = self._build_client_headers()
        self.response = None
        self._hsts_preload_status = None  # Cached result

    def _validate_url(self, url):
        if not url.startswith(("http://", "https://")):
            url = f"https://{url}"
        return url

    def _build_client_headers(self):
        if self.args.no_default_headers:
            headers = {}
        else:
            headers = dict(self.DEFAULT_CLIENT_HEADERS)

        if getattr(self.args, "user_agent", None):
            headers["User-Agent"] = self.args.user_agent

        for item in getattr(self.args, "header", []) or []:
            if ":" not in item:
                print(
                    f"[!] Ignoring invalid header (expected 'Key: Value'): {item}",
                    file=sys.stderr,
                )
                continue
            key, value = item.split(":", 1)
            key = key.strip()
            value = value.strip()
            if not key:
                print(f"[!] Ignoring header with empty key: {item}", file=sys.stderr)
                continue
            headers[key] = value
        return headers

    def _extract_domain(self, url):
        """Extract the registrable domain from a URL."""
        parsed = urlparse(url)
        hostname = parsed.netloc or parsed.path
        # Remove port if present
        hostname = hostname.split(":")[0]
        # Get the main domain (e.g., www.google.com -> google.com)
        parts = hostname.split(".")
        if len(parts) >= 2:
            return ".".join(parts[-2:])
        return hostname

    def check_hsts_preload(self):
        """Check if domain is in browser HSTS preload list.

        Checks both the original requested domain and the final redirected domain,
        since sites like twitter.com may redirect to x.com but still be preloaded.
        """
        if self._hsts_preload_status is not None:
            return self._hsts_preload_status

        # Check both original domain and final domain (after redirects)
        original_domain = self._extract_domain(self.url)
        final_domain = (
            self._extract_domain(self.response.url)
            if self.response
            else original_domain
        )

        domains_to_check = [original_domain]
        if final_domain != original_domain:
            domains_to_check.append(final_domain)

        for domain in domains_to_check:
            try:
                resp = requests.get(
                    self.HSTS_PRELOAD_API, params={"domain": domain}, timeout=5
                )
                if resp.ok:
                    data = resp.json()
                    status = data.get("status", "")
                    if status == "preloaded":
                        self._hsts_preload_status = {
                            "domain": domain,
                            "preloaded": True,
                            "status": status,
                        }
                        return self._hsts_preload_status
            except requests.exceptions.RequestException:
                continue

        # Neither domain is preloaded
        self._hsts_preload_status = {
            "domain": original_domain,
            "preloaded": False,
            "status": "unknown",
        }
        return self._hsts_preload_status

    def make_request(self):
        timeout = self.args.timeout
        insecure = self.args.insecure

        try:
            response = requests.head(
                self.url,
                headers=self.headers,
                timeout=timeout,
                verify=not insecure,
                allow_redirects=True,
            )
            if not response.ok:
                raise requests.exceptions.RequestException(
                    f"HEAD not OK: {response.status_code}"
                )
            self.response = response
            return response
        except (requests.exceptions.RequestException, requests.exceptions.HTTPError):
            try:
                response = requests.get(
                    self.url,
                    headers=self.headers,
                    timeout=timeout,
                    verify=not insecure,
                    allow_redirects=True,
                )
                self.response = response
                return response
            except requests.exceptions.RequestException:
                raise

    def analyze_security_headers(self):
        print("\n" + "=" * 60)
        print("[+] Analyzing security headers...")
        print("=" * 60)

        present = []
        missing = []
        headers = self.response.headers

        for header, description in self.SECURITY_HEADERS.items():
            if header in headers:
                present.append((header, headers[header]))
            else:
                missing.append((header, description))

        if present:
            print("Security headers present:")
            for header, value in present:
                if header == "X-Content-Type-Options" and value.lower() != "nosniff":
                    print(f"  • {header} → {value} (should be 'nosniff')")
                elif header == "X-Frame-Options" and value.upper() not in (
                    "DENY",
                    "SAMEORIGIN",
                ):
                    print(f"  • {header} → {value} (should be 'DENY' or 'SAMEORIGIN')")
                else:
                    print(f"  • {header} → {value}")
        else:
            print("All security headers missing")

        if missing:
            print("Security headers missing:")
            for header, description in missing:
                print(f"  • {header} → {description}")
        else:
            print("All security headers present")

    def analyze_sensitive_headers(self):
        print("\n" + "=" * 60)
        print("[+] Analyzing sensitive headers...")
        print("=" * 60)

        found = []
        headers = self.response.headers
        for header in self.SENSITIVE_HEADERS:
            if header in headers:
                found.append((header, headers[header]))

        if found:
            print("Potentially sensitive headers found:")
            for header, value in found:
                print(f"  • {header}: {value}")
            print("These headers might reveal technology, version or framework details")
        else:
            print("[+] No sensitive headers present")

    def calculate_grade(self):
        """Calculate security grade based on headers analysis."""
        headers = self.response.headers

        # Calculate total possible (HTTPS baseline + header weights, excluding 0-weight headers)
        header_points_possible = sum(w for w in self.HEADER_WEIGHTS.values() if w > 0)
        total_possible = self.HTTPS_BASELINE + header_points_possible

        score_details = {
            "header_scores": [],
            "value_bonuses": [],
            "penalties": [],
            "https_baseline": 0,
            "total_possible": total_possible,
        }

        earned_points = 0

        # Baseline points for HTTPS
        if self.response.url.startswith("https://"):
            earned_points += self.HTTPS_BASELINE
            score_details["https_baseline"] = self.HTTPS_BASELINE

        # Check if site is HSTS preloaded - if so, automatic A+ (browser already trusts it)
        hsts_preload = self.check_hsts_preload()
        if hsts_preload.get("preloaded"):
            return {
                "score": 100,
                "max_score": 100,
                "percentage": 100,
                "grade": "A+",
                "description": "Browser Trusted",
                "hsts_preloaded": True,
                "hsts_domain": hsts_preload["domain"],
                "details": None,
            }

        # Score for security headers present and their values
        for header, weight in self.HEADER_WEIGHTS.items():
            if weight == 0:  # Skip deprecated headers with 0 weight
                continue
            if header in headers:
                value = headers[header]
                earned_points += weight
                score_details["header_scores"].append((header, weight, True))

                # Check for correct value (bonus: no deduction)
                if header in self.EXPECTED_VALUES:
                    validator = self.EXPECTED_VALUES[header]
                    if validator(value):
                        score_details["value_bonuses"].append((header, "correct"))
                    else:
                        # Partial credit - header present but misconfigured
                        penalty = weight // 4  # Reduced penalty for misconfiguration
                        earned_points -= penalty
                        score_details["value_bonuses"].append(
                            (header, f"misconfigured (-{penalty})")
                        )
            else:
                score_details["header_scores"].append((header, weight, False))

        # Penalty for sensitive headers exposed (capped to avoid crushing the score)
        sensitive_count = 0
        for header in self.SENSITIVE_HEADERS:
            if header in headers:
                sensitive_count += 1
                score_details["penalties"].append((header, self.SENSITIVE_PENALTY))

        total_penalty = min(
            sensitive_count * self.SENSITIVE_PENALTY, 10
        )  # Cap at 10 pts
        earned_points = max(0, earned_points - total_penalty)

        # Calculate percentage
        percentage = (earned_points / total_possible) * 100
        percentage = min(100, max(0, percentage))  # Clamp to 0-100

        # Determine letter grade
        grade = "F"
        description = "Critical"
        for threshold, letter, desc in self.GRADE_THRESHOLDS:
            if percentage >= threshold:
                grade = letter
                description = desc
                break

        return {
            "score": round(earned_points, 1),
            "max_score": score_details["total_possible"],
            "percentage": round(percentage, 1),
            "grade": grade,
            "description": description,
            "details": score_details,
        }

    def display_grade(self):
        """Display the security grade with breakdown."""
        result = self.calculate_grade()

        print("\n" + "=" * 60)
        print("[+] SECURITY GRADE")
        print("=" * 60)

        # Special case: HSTS preloaded sites
        if result.get("hsts_preloaded"):
            print(f"\n  Grade: {result['grade']} ({result['description']})")
            print(
                f"\n  ★ This site is in the HSTS Preload List ({result['hsts_domain']})"
            )
            print(
                "  ★ HSTS is built into all major browsers (Chrome, Firefox, Safari, Edge)"
            )
            print(
                "  ★ Browsers will ALWAYS use HTTPS for this site, even on first visit"
            )
            print(
                "  ★ Header analysis is not needed - browser-level trust is the gold standard"
            )
            return result

        # Normal grading display
        grade_bar = self._create_grade_bar(result["percentage"])
        print(f"\n  Grade: {result['grade']} ({result['description']})")
        print(
            f"  Score: {result['score']}/{result['max_score']} ({result['percentage']}%)"
        )
        print(f"  {grade_bar}")

        # Breakdown
        details = result["details"]

        # Show HTTPS baseline if earned
        if details.get("https_baseline", 0) > 0:
            print(f"\n  HTTPS Baseline: +{details['https_baseline']} pts")

        print("\n  Header Scores:")
        for header, weight, present in details["header_scores"]:
            status = "✓" if present else "✗"
            points = f"+{weight}" if present else f" 0"
            print(f"    {status} {header}: {points} pts")

        if details["value_bonuses"]:
            print("\n  Value Validation:")
            for header, status in details["value_bonuses"]:
                icon = "✓" if status == "correct" else "⚠"
                print(f"    {icon} {header}: {status}")

        if details["penalties"]:
            print("\n  Penalties (Sensitive Headers Exposed):")
            for header, penalty in details["penalties"]:
                print(f"    ✗ {header}: -{penalty} pts")

        return result

    def _create_grade_bar(self, percentage):
        """Create a visual progress bar for the grade."""
        bar_length = 30
        filled = int(bar_length * percentage / 100)
        empty = bar_length - filled

        # Color coding based on percentage
        if percentage >= 80:
            fill_char = "█"
        elif percentage >= 60:
            fill_char = "▓"
        elif percentage >= 40:
            fill_char = "▒"
        else:
            fill_char = "░"

        bar = fill_char * filled + "░" * empty
        return f"  [{bar}]"

    def print_headers(self, as_json=False):
        if as_json:
            print("\n" + "=" * 60)
            print("[+] RAW RESPONSE HEADERS (AS JSON)")
            print("=" * 60)

            headers_dict = dict(self.response.headers)
            print(json.dumps(headers_dict, indent=4, sort_keys=True))
        else:
            print("\n" + "=" * 60)
            print("[+] RAW RESPONSE HEADERS")
            print("=" * 60)
            for key, value in self.response.headers.items():
                print(f"{key}: {value}")

    def scan(self):
        self.make_request()

        print(f"[+] Target: {self.url}")
        print(f"[+] Status Code: {self.response.status_code}")
        if self.response.history:
            print(f"[+] Redirected {len(self.response.history)} times")
            print(f"    Final URL: {self.response.url}")

        self.print_headers(as_json=self.args.json)
        self.analyze_security_headers()
        self.analyze_sensitive_headers()
        self.display_grade()

        print("\n" + "=" * 60)
        print("[+] Scan completed successfully!")
        print("=" * 60)


def main():
    parser = argparse.ArgumentParser(
        formatter_class=argparse.RawTextHelpFormatter,
        description="HTTP Header Security Analyzer",
    )
    parser.add_argument("url", help="Target URL to scan")
    parser.add_argument(
        "--insecure",
        "-k",
        action="store_true",
        help="Skip SSL certificate verification",
    )
    parser.add_argument(
        "--timeout",
        type=int,
        default=10,
        help="Request timeout in seconds (default: 10)",
    )
    parser.add_argument(
        "--user-agent", dest="user_agent", help="Override User-Agent header"
    )
    parser.add_argument(
        "--header",
        "-H",
        action="append",
        default=[],
        help='Custom request header, e.g., -H "Key: Value". Repeat to add multiple.',
    )
    parser.add_argument(
        "--no-default-headers",
        action="store_true",
        help="Do not include built-in client headers (start from empty set)",
    )
    parser.add_argument("--json", action="store_true", help="Output results as JSON")

    args = parser.parse_args()

    try:
        scanner = HeaderScanner(args.url.strip(), args)
        scanner.scan()
    except KeyboardInterrupt:
        sys.exit("\n[!] Scan interrupted by user")
    except requests.exceptions.RequestException as e:
        if isinstance(e, requests.exceptions.SSLError):
            sys.exit(
                f"[!] SSL Error: {e}\n    Use --insecure to bypass certificate validation"
            )
        elif isinstance(e, requests.exceptions.Timeout):
            sys.exit(f"[!] Request timed out after {args.timeout} seconds")
        elif isinstance(e, requests.exceptions.ConnectionError):
            sys.exit("[!] Failed to connect to the server")
        else:
            sys.exit(f"[!] Request failed: {e}")


if __name__ == "__main__":
    main()