{"id":31752216,"url":"https://github.com/jonasfroeller/header-checker","last_synced_at":"2025-10-09T16:58:39.348Z","repository":{"id":309245779,"uuid":"1035600449","full_name":"jonasfroeller/header-checker","owner":"jonasfroeller","description":"HTTP Security Header Analyzer.","archived":false,"fork":false,"pushed_at":"2025-09-29T00:19:36.000Z","size":523,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T02:31:07.381Z","etag":null,"topics":["header-scanner","security-headers-scanner","website-scanner"],"latest_commit_sha":null,"homepage":"https://sha.merginit.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonasfroeller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-10T18:33:27.000Z","updated_at":"2025-09-29T00:19:40.000Z","dependencies_parsed_at":"2025-08-10T20:36:19.059Z","dependency_job_id":"570e65ed-8083-4148-8dbc-95bf683b66b2","html_url":"https://github.com/jonasfroeller/header-checker","commit_stats":null,"previous_names":["jonasfroeller/header-checker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonasfroeller/header-checker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasfroeller%2Fheader-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasfroeller%2Fheader-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasfroeller%2Fheader-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasfroeller%2Fheader-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonasfroeller","download_url":"https://codeload.github.com/jonasfroeller/header-checker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasfroeller%2Fheader-checker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001776,"owners_count":26083173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["header-scanner","security-headers-scanner","website-scanner"],"created_at":"2025-10-09T16:58:23.219Z","updated_at":"2025-10-09T16:58:39.343Z","avatar_url":"https://github.com/jonasfroeller.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HTTP Security Header Analyzer\n\n## Overview\n\nThis is a Flask-based web application that provides a web interface and REST API to analyze HTTP security headers. It helps developers and security professionals assess the security posture of web applications.  \nThe system is designed as a simple, lightweight service that performs live HTTP header analysis and presents results through a user-friendly web interface with caching and rate limiting capabilities.\n\n![example](./example.png)\n\n## System Architecture\n\n### Frontend Architecture\n\n- **Technology**: Vanilla JavaScript with Bootstrap for UI components\n- **Design Pattern**: Single-page application with dynamic content loading\n- **Styling**: Bootstrap dark theme with custom CSS for security grades and smooth animations\n- **User Interface**: Clean, responsive design with real-time analysis feedback and shareable results\n- **Sharing Feature**: URL-based result sharing with automatic clipboard copy functionality\n\n### Backend Architecture\n\n- **Framework**: Flask (Python) with modular service architecture\n- **Design Pattern**: Service-oriented architecture with separation of concerns\n- **Core Services**:\n  - `HumbleService`: Handles HTTP security header analysis with automatic protocol fallback (HTTPS→HTTP)\n  - `CacheService`: Provides in-memory caching with TTL support for performance optimization\n  - `URLValidator`: Handles URL validation, normalization, and protocol detection\n- **Rate Limiting**: Flask-Limiter integration for API protection\n- **Security**: ProxyFix middleware for proper header handling behind proxies\n\n### Data Flow\n\n1. User submits URL through web interface or API (or loads shared URL)\n2. URL validation and normalization with automatic protocol detection (HTTPS preferred)\n3. Cache check for existing results\n4. Analysis executed by humble CLI (brief JSON) with optional HTTPS→HTTP fallback\n5. Result mapping to UI/API schema and caching\n6. Response delivery\n7. Optional shareable URL for results\n\n### Error Handling\n\n- Network timeout handling for HTTP requests\n- Comprehensive input validation and sanitization\n- Rate limiting with meaningful error responses\n\n## External Dependencies\n\n### Core Dependencies\n\n- **Flask**: Web framework for API and web interface\n- **Flask-Limiter**: Rate limiting middleware\n- **Werkzeug**: WSGI utilities and middleware\n- **Bootstrap**: Frontend CSS framework via CDN\n- **Font Awesome**: Icon library via CDN\n\n### Security Analysis Engine\n\n- **humble CLI (only)**: The application relies exclusively on the official humble analyzer for checks, grading, and summaries.\n\nConfiguration for humble:\n\n- Set one of the following environment variables so the app can locate humble:\n  - `HUMBLE_PY`: Full path to `humble.py` (e.g., `D:/tools/humble/humble.py`)\n  - `HUMBLE_HOME`: Directory containing `humble.py` (e.g., `D:/tools/humble`)\n- Optional: `PYTHON_LAUNCHER` to override the Python executable used to run humble (defaults to `py` on Windows, `python3` on Linux/macOS)\n\nInstallation of humble (from source) summary:\n\n```bash\ngit clone https://github.com/rfc-st/humble.git\ncd humble\npip install -r requirements.txt\n# then set HUMBLE_HOME to this directory or HUMBLE_PY to its humble.py\n```\n\n### Runtime Dependencies\n\n- **Python requests library**: For making HTTP requests to analyze security headers\n- **Threading**: For thread-safe cache operations\n- **JSON**: For parsing analysis results and API responses\n\n### External Services\n\n- **CDN Resources**: Bootstrap CSS and Font Awesome icons loaded from external CDNs\n- No database dependencies (uses in-memory caching)\n- No external API dependencies\n\n### Environment Configuration\n\n- `SESSION_SECRET`: Flask session secret key (defaults to development key)\n- Rate limiting configuration through Flask-Limiter\n- Logging configuration set to DEBUG level for development\n\n## Run frontend and backend together\n\nThe Flask app serves both the API and the web UI (from `templates/` and `static/`). Start the server with one of the following single commands:\n\n- Using Python (recommended):\n  \n  ```bash\n  python main.py\n  ```\n\n- Using Flask CLI (auto-reload):\n  \n  ```bash\n  python -m flask --app app run --debug\n  ```\n\n- Using uv (if installed):\n  \n  ```bash\n  uv run python main.py\n  ```\n\nThen open http://localhost:5000 in your browser.\n\n### Zero-friction setup with uv\n\n```bash\nuv sync --frozen --no-dev\n# Option A: vendor humble once (recommended)\ngit clone https://github.com/rfc-st/humble.git .tools/humble\n# Windows PowerShell\n$env:HUMBLE_HOME = \"$PWD/.tools/humble\"\n# macOS/Linux\nexport HUMBLE_HOME=\"$PWD/.tools/humble\"\n\nuv run python main.py\n```\n\nNotes:\n- The app auto-discovers `.tools/humble/humble.py` or `vendor/humble/humble.py` if `HUMBLE_HOME`/`HUMBLE_PY` is not set.\n- If you prefer an isolated interpreter for humble, create a venv under `.tools/humble/.venv` and set `PYTHON_LAUNCHER` to that interpreter path. Otherwise the app uses the current `sys.executable`.\n\nAPI response shape (humble-only, abbreviated):\n- url, status_code, timestamp, scan_time, cached\n- headers: raw response headers\n- grade (A–F), score, analysis_source=\"humble\"\n- security_headers: object keyed by header name with present/value/status\n- missing_headers: array of header names\n- warnings: array of {header, message}\n- humble: passthrough of parsed humble output with:\n  - present_headers, missing_headers, deprecated_or_insecure, fingerprint_headers, empty_values\n  - info, browser_compat, browser_compat_map, analysis_results_lines, analysis_runtime_seconds\n  - totals (numeric counts), grade, raw_object, source\n\n## Production Deployment\n\nUse uv to install dependencies, then run the app with a production WSGI server (Gunicorn) behind a reverse proxy.\n\n1) Install dependencies (prod)\n\n```bash\nuv sync --frozen --no-dev\n```\n\n2) Run with Gunicorn (Linux)\n\n```bash\nexport SESSION_SECRET=\"\u003cyour-strong-secret\u003e\"\ngunicorn -w 4 -k gthread -b 0.0.0.0:8000 app:app\n```\n\n3) Reverse proxy (Nginx)\n\n```nginx\nlocation / {\n  proxy_pass http://127.0.0.1:8000;\n  proxy_set_header Host $host;\n  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n  proxy_set_header X-Forwarded-Proto $scheme;\n}\n```\n\nNotes:\n- Gunicorn is not supported on Windows; for local Windows use WSL or a Windows-friendly server (e.g., waitress). For real prod, prefer Linux.\n- Set `SESSION_SECRET` in production.\n\n### Install dependencies (first run)\n\nIf you don't use `uv`, install the minimal runtime deps with pip:\n\n```bash\npython -m pip install --upgrade pip\npip install flask flask-limiter werkzeug requests\n```\n\nOptional extras in `pyproject.toml` (e.g., `gunicorn`, `flask-sqlalchemy`) are not yet required to run this app.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasfroeller%2Fheader-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonasfroeller%2Fheader-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasfroeller%2Fheader-checker/lists"}