header_hound 1.0.x-dev

First release of HeaderHound.

HeaderHound fetches a URL and grades its HTTP security headers, much like securityheaders.com does. It started as two custom modules on a Drupal 11 site. For this release they became one generic module with a public submodule, settings, tests and documentation. It's an alpha because it hasn't run in production in this form yet, and Drupal 12 has only had the unit tests so far.

What's in it

• An admin report at Reports » HeaderHound that grades ten headers from A+ to F: Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, X-XSS-Protection and the three cross-origin policies (COEP, COOP and CORP).
• Each header gets a score, what is right and wrong about it, and the recommended value when it's missing.
• A check for headers that give away server or CMS versions, such as Server, X-Powered-By and X-Generator, plus a table of every raw response header.
• An HTML export that is a single self-contained file. It loads nothing from the network and prints cleanly to PDF.
• The HeaderHound Public submodule adds a public checker at /security-headers:
  • Each report gets its own shareable link with a random token.
  • There's an optional public list of recent audits, which visitors can keep their own audit out of.
  • Admins get an audit history with totals and a grade distribution.
• Settings for the public checker: how many audits a visitor can run per time window, whether the recent list is shown, and how many days to keep stored audits (cleaned up on cron).

Security

Running an audit makes your server send a request, so HeaderHound only fetches http and https URLs on ports 80 and 443. Every address the host resolves to must be public. Loopback, private, link-local (including cloud metadata addresses) and other reserved ranges are refused.

Each request is pinned to the address that was checked, so DNS rebinding can't get around this. Redirects are followed by hand, at most five, and each one is checked the same way. Only the headers are read, not the body.

Stored audits keep a keyed hash of the submitter's IP address, never the address itself. On a public site, add a CAPTCHA to the form ID header_hound_public_form as well.

Compatibility

Drupal 10.3 or later, 11 and 12, on PHP 8.2 or later with the curl extension. Tested on Drupal 10.3 and 11.4, with SQLite and MariaDB. On Drupal 12.0-beta2 the unit tests pass and PHPStan reports no deprecations.

Installing

composer require 'drupal/header_hound:^1.0@alpha'

Enable header_hound for the admin report. Enable header_hound_public as well if you want the public checker.

Give the Use the HeaderHound report permission to the roles that should run audits.