Security Header Analyzer - Claude Code Context

Efficient context for AI assistants working on this project

Project Overview

Security Header Analyzer is a Python CLI tool and library that analyzes HTTP security headers against industry best practices. It validates 15 security headers (HSTS, CSP, X-Frame-Options, etc.) and provides actionable recommendations.

Key Features:

Analyzes 15 security headers with sophisticated validation
Detects CSP bypasses, cookie prefix violations, cache conflicts
Cross-origin isolation validation (COEP + COOP interaction)
582 comprehensive tests (97%+ coverage)
Extensive documentation (52+ files)

Tech Stack: Python 3.8+, pytest, requests, MyPy (strict mode), Black, isort

Quick Reference for AI Assistants

Code Standards

Type Hints: MyPy strict mode (100% typed)

Every function must have type annotations
Use Optional[str] not str | None (Python 3.8 compatibility)
Type alias: Finding = Dict[str, Any]
See: docs/repo-rules/python-code-standards.md

Formatting: Black (100-char lines)

Automated via pre-commit hooks
Never manually format - let Black do it
Config: pyproject.toml → [tool.black]

Imports: isort (Black profile)

Order: stdlib → third-party → local
Vertical hanging indent with trailing commas
Config: pyproject.toml → [tool.isort]

Core Patterns:

Registry Pattern: All analyzers registered in sha/analyzers/__init__.py
Finding Structure: 7 required keys (header_name, status, severity, message, actual_value, recommendation)
Config Dictionaries: Externalized validation rules in each analyzer's CONFIG

Testing Requirements

Coverage: 97%+ overall, 100% for new analyzers (non-negotiable)

Organization:

Class-based: TestParse* and TestAnalyze* classes
Files: tests/analyzers/test_<analyzer>.py
Real-world fixtures: tests/fixtures/headers/*.json

Framework: pytest with comprehensive fixtures

Central fixture hub: tests/conftest.py (220 lines)
Factory fixtures: mock_response_factory, mock_session_factory
Real-world: github_headers, google_headers, etc.

Run Tests:

pytest --cov=sha --cov-report=term-missing

Full Details: docs/repo-rules/testing-standards.md

Git Practices

Commits: Imperative mood, descriptive

✅ "Add CSP bypass detection"
❌ "Added feature"

Branch: Single main branch workflow (solo developer)

Sprint-Based: For multi-step work

"Sprint N: "
"Mark Sprint N as COMPLETED -
"

Co-Authoring with Claude:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Full Details: docs/repo-rules/git-practices.md

Documentation Standards

Philosophy: Brevity, Conciseness, Accuracy

Update Documentation When:

Adding new analyzer → Create docs/headers/<name>.md
Changing API → Update docs/api-reference.md
Modifying architecture → Update docs/architecture/
Updating code → Update inline docstrings

Templates:

Header docs: See docs/repo-rules/documentation-standards.md#header-documentation-template
Python docstrings: Module, Purpose, Overview, Key Functions, See Also
Cross-linking: Bidirectional links required

Full Details: docs/repo-rules/documentation-standards.md

Key Files for Context

Core Codebase

sha/analyzers/__init__.py - Registry pattern (ANALYZER_REGISTRY, CONFIG_REGISTRY)
sha/analyzers/*.py - Individual header analyzers (15 total)
sha/analyzer.py - Orchestration layer
sha/fetcher.py - HTTP fetching with SSRF protection
sha/config.py - Constants, exceptions
sha/main.py - CLI entry point

Tests

tests/conftest.py - Shared fixtures
tests/analyzers/ - Analyzer unit tests (12 files)
tests/test_integration.py - CLI workflow tests
tests/test_real_world_headers.py - Production header validation

Documentation

docs/repo-rules/ - ALL coding standards (Python, testing, git, debugging, docs)
docs/headers/ - Individual header documentation (15 headers)
docs/architecture/ - System design, patterns, extensibility

Configuration

pyproject.toml - All tool configs (Black, isort, MyPy, pytest, coverage)
.pre-commit-config.yaml - Automated quality checks
pytest.ini - Test configuration

Solo Developer Workflow

Efficient Practices

Before Every Commit:

# Tests and coverage
pytest --cov=sha --cov-report=term-missing

# Pre-commit hooks (auto-run on commit)
git add .
git commit -m "Clear descriptive message"

Let Automation Handle:

Formatting (Black)
Import sorting (isort)
Type checking (MyPy)
Linting (flake8)
Security scanning (bandit)

Focus Your Time On:

Correct logic
Comprehensive tests
Clear documentation
Descriptive commit messages

Common Tasks

Adding a New Analyzer

1. Create analyzer module: sha/analyzers/new_header.py

HEADER_KEY = "new-header-name"  # Lowercase with hyphens

CONFIG = {
    "display_name": "New-Header-Name",
    "severity_missing": "high",
    # ... validation rules
}

def analyze(value: Optional[str]) -> Finding:
    """Analyze header and return Finding dict."""
    # ... implementation

2. Register: Update sha/analyzers/__init__.py

from . import new_header
ANALYZER_REGISTRY[new_header.HEADER_KEY] = new_header.analyze
CONFIG_REGISTRY[new_header.HEADER_KEY] = new_header.CONFIG

3. Add tests: tests/analyzers/test_new_header.py

class TestParseNewHeader:
    def test_parse_valid(self): ...

class TestAnalyzeNewHeader:
    def test_analyze_missing(self): ...
    def test_analyze_good(self): ...
    def test_analyze_bad(self): ...

4. Create documentation: docs/headers/new-header.md

5. Update references:

docs/headers/README.md
docs/analyzer-reference.md
docs/repo-rules/security-headers-best-practices.md

Full Guide: docs/architecture/extensibility-guide.md Code Standards: docs/repo-rules/python-code-standards.md#analyzer-implementation-guide

Debugging

Test Failures:

# Verbose output with full traceback
pytest tests/path/to/test.py::TestClass::test_function -vv --tb=long

# With print statements shown
pytest -vvs

Type Errors:

# Check types
mypy sha/

# Specific file with error codes
mypy sha/analyzers/hsts.py --show-error-codes

Coverage Gaps:

# Find missing lines
pytest --cov=sha --cov-report=html
open htmlcov/index.html

Full Guide: docs/repo-rules/debugging-practices.md

Documentation Updates

When Code Changes:

Update inline docstrings immediately
Update related .md files before committing
Add cross-links to new content
Verify links work

Templates:

Header docs: 150-250 lines (Quick Ref, What It Does, How It Works, Attack Scenarios, Examples, Common Mistakes)
Python docstrings: Module, Purpose, Overview, Key Functions, Example Usage, See Also
Architecture docs: High-level overview, component details, code references

Quality Checklist:

Brevity (no unnecessary words)
Conciseness (clear purpose per section)
Accuracy (verified against code)
Cross-linked (bidirectional links)

Full Guide: docs/repo-rules/documentation-standards.md

Repository Structure

security-header-analyzer/
├── sha/                              # Main package
│   ├── __init__.py                   # Package initialization
│   ├── __main__.py                   # Entry point: python -m sha
│   ├── main.py                       # CLI orchestration
│   ├── analyzer.py                   # Analysis coordination
│   ├── fetcher.py                    # HTTP fetching (SSRF protected)
│   ├── reporter.py                   # Report generation (text/JSON)
│   ├── config.py                     # Constants, exceptions
│   └── analyzers/                    # Header analyzers (15 total)
│       ├── __init__.py               # Registry (ANALYZER_REGISTRY)
│       ├── hsts.py                   # Strict-Transport-Security
│       ├── csp.py                    # Content-Security-Policy
│       ├── set_cookie.py             # Set-Cookie
│       ├── cache_control.py          # Cache-Control
│       ├── permissions_policy.py     # Permissions-Policy
│       ├── cross_origin_validator.py # COEP+COOP interaction
│       └── ... (10 more analyzers)
│
├── tests/                            # Test suite (582 tests)
│   ├── conftest.py                   # Shared fixtures
│   ├── fixtures/headers/             # Real-world header JSONs
│   ├── analyzers/                    # Analyzer unit tests (12 files)
│   ├── test_integration.py           # CLI workflow tests
│   ├── test_fetcher.py               # HTTP fetching tests
│   └── ... (8 more test files)
│
├── docs/                             # Documentation (52+ files)
│   ├── README.md                     # Master index
│   ├── installation-guide.md
│   ├── usage-guide.md
│   ├── quick-start-tutorial.md
│   ├── headers/                      # Header documentation (15 files)
│   │   ├── README.md
│   │   ├── hsts.md
│   │   ├── csp.md
│   │   └── ...
│   ├── architecture/                 # Architecture docs (8 files)
│   │   ├── README.md
│   │   ├── system-design.md
│   │   ├── registry-pattern.md
│   │   ├── extensibility-guide.md
│   │   └── ...
│   └── repo-rules/                   # Repository standards (7 files)
│       ├── README.md
│       ├── python-code-standards.md  # ← Essential for coding
│       ├── testing-standards.md      # ← Essential for testing
│       ├── git-practices.md          # ← Essential for commits
│       ├── debugging-practices.md
│       ├── documentation-standards.md
│       └── security-headers-best-practices.md
│
├── .github/workflows/                # CI/CD
│   └── test.yml                      # Multi-version testing
│
├── pyproject.toml                    # Project config (all tools)
├── pytest.ini                        # pytest configuration
├── .pre-commit-config.yaml           # Quality checks
├── CONTRIBUTING.md                   # Contribution guidelines
└── README.md                         # Project README

Important Patterns

Registry Pattern (Core Architecture)

Purpose: Decouple analyzer implementations from orchestration

Implementation: sha/analyzers/init.py

ANALYZER_REGISTRY: Dict[str, Callable] = {
    hsts.HEADER_KEY: hsts.analyze,
    csp.HEADER_KEY: csp.analyze,
    # ... all 15 analyzers
}

Benefits:

Add new analyzers without modifying orchestration code
Consistent interface: analyze(value: Optional[str]) -> Finding
Centralized configuration

Full Explanation: docs/architecture/registry-pattern.md

Finding Structure (Standardized Output)

All analyzers must return:

{
    "header_name": str,           # Display name
    "status": str,                # "good" | "acceptable" | "bad" | "missing"
    "severity": str,              # "critical" | "high" | "medium" | "low" | "info"
    "message": str,               # Human-readable explanation
    "actual_value": Optional[str], # Actual header value
    "recommendation": Optional[str] # How to fix (None if good)
}

Benefits:

Consistent reporter output
Type-safe validation
Clear contract between layers

Configuration Dictionary Pattern

Every analyzer has a module-level CONFIG:

CONFIG = {
    "display_name": "Header-Name",
    "severity_missing": "critical",
    "validation": {
        # Thresholds and rules
    },
    "messages": {
        STATUS_GOOD: "...",
        STATUS_BAD: "...",
    },
    "recommendations": {
        # How to fix issues
    }
}

Benefits:

Change thresholds without modifying code
Self-documenting
Easy to test

Project Status

Version: 1.0.0 Python: 3.8, 3.9, 3.10, 3.11, 3.12 Tests: 582 (100% pass rate) Coverage: 97%+ Headers Analyzed: 15 Documentation Files: 52+

Recent Achievements:

✅ Sprint 5 COMPLETED - All enhancement sprints finished (100%)
✅ Industry-leading CSP bypass detection (15 patterns)
✅ First tool with COEP+COOP cross-header validation
✅ Cookie prefix validation (__Secure-, __Host-)
✅ Cache-Control conflict detection (4 types)
✅ Permissions-Policy risk categorization (19 features)

External Resources

Project README: README.md
Contributing Guide: CONTRIBUTING.md
All Documentation: docs/README.md
Architecture Docs: docs/architecture/README.md
Repository Rules: docs/repo-rules/README.md ⭐ Essential

Quick Start for AI Assistants

Read repository rules first: docs/repo-rules/README.md
Understand the Registry Pattern: docs/architecture/registry-pattern.md
Reference existing analyzers: sha/analyzers/hsts.py (simple), sha/analyzers/csp.py (complex)
Follow the standards: Type hints, Finding structure, CONFIG pattern
Write comprehensive tests: 100% coverage for new code
Update documentation: Always update docs with code changes
Use descriptive commits: Imperative mood, explain what and why

Most Important Files to Understand:

docs/repo-rules/python-code-standards.md - How to write code
docs/architecture/registry-pattern.md - How analyzers integrate
sha/analyzers/hsts.py - Simple analyzer example
tests/analyzers/test_hsts.py - Test pattern example

Last Updated: 2026-01-01 Maintained By: Solo developer (working alone) AI Assistance: Claude Code (co-authoring commits)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Security Header Analyzer - Claude Code Context

Project Overview

Quick Reference for AI Assistants

Code Standards

Testing Requirements

Git Practices

Documentation Standards

Key Files for Context

Core Codebase

Tests

Documentation

Configuration

Solo Developer Workflow

Efficient Practices

Common Tasks

Adding a New Analyzer

Debugging

Documentation Updates

Repository Structure

Important Patterns

Registry Pattern (Core Architecture)

Finding Structure (Standardized Output)

Configuration Dictionary Pattern

Project Status

External Resources

Quick Start for AI Assistants

FilesExpand file tree

.claude_code.md

Latest commit

History

.claude_code.md

File metadata and controls

Security Header Analyzer - Claude Code Context

Project Overview

Quick Reference for AI Assistants

Code Standards

Testing Requirements

Git Practices

Documentation Standards

Key Files for Context

Core Codebase

Tests

Documentation

Configuration

Solo Developer Workflow

Efficient Practices

Common Tasks

Adding a New Analyzer

Debugging

Documentation Updates

Repository Structure

Important Patterns

Registry Pattern (Core Architecture)

Finding Structure (Standardized Output)

Configuration Dictionary Pattern

Project Status

External Resources

Quick Start for AI Assistants