HExHTTP: testing HTTP headers and cache poisoning from one CLI

What the tool actually does

HExHTTP is described as a tool designed to perform tests on HTTP headers and analyze the results to identify vulnerabilities and interesting behaviours. The word analyse is doing real work in that sentence. The tool does not simply look for a specific header value, it sends requests designed to reveal how the server and its caching layer treat header input, and then draws conclusions from the response.

The modules directory at the top of the repository is where the individual checks live, and the CLI has a flag that confirms the shape of the tool. The --ocp option, only cache poisoning modules, restricts the run to the cache poisoning checks, and --only-top runs only the top cache poisoning and cache poisoning denial of service module, described as a curated set of error and reflected cross-site scripting payloads, skipping every other check.

That distinction between a full run and a single curated module is a sensible design for a scanner with this many payloads, because the difference between a broad run and a focused one is measured in request count, and request count is what the target feels.

The project classifies itself as Development Status 4, Beta, and it is worth knowing that the tests include a Burp Suite integration, since the tool's findings are meant to end up in a place where a tester can triage them rather than in a terminal scrollback.

Installing from a clone, from PyPI or as a Docker image

The install is a four-step process, and the last step is a smoke test.

git clone https://github.com/c0dejump/HExHTTP.git
cd HExHTTP
pip install .

For a development install, the README shows the editable form with the dev extra, which pulls in the linting and testing tools.

pip install -e ".{dev]"

Then you check it runs, either as the script or as a module.

./hexhttp.py -u 'https://target.tld/'
   # OR
python3 hexhttp.py -u 'https://target.tld/'

The package is also on PyPI under the name hexhttp, so pip install hexhttp works for a normal installation.

The Docker route is a two-command build and run, and the network mode matters. The container is built from a Python 3.11 Alpine base with the package installed and the script made executable, and the run command uses host networking so the tool can reach targets on the local network.

docker build -t hexhttp:latest .
docker run --rm -it --net=host -v "$PWD:/hexhttp/" hexhttp:latest -u 'https://target.tld/'

The volume mount is what puts the results directory, the error logs and the screenshots on the host, which is what makes the container useful rather than a sealed box.

The package metadata sets the floor at Python 3.11 and names the licence as MIT, and the dependencies are requests and urllib3 for the HTTP layer, beautifulsoup4 for parsing responses, httpx, tldextract for working out registrable domains, curl_cffi, and pync on macOS only.

The command line and the request-shaping options

The usage output is the reference for what you can control, and the options fall into groups.

The target is given with -u for a single URL, which is required if no file is provided, or -f for a file of URLs. The request settings let you add a custom header with -H, a custom user agent with -A, and HTTP authentication with -a, with the example given as admin:admin.

Two options are about how the tool looks to the target rather than what it sends. The -hu option, humans, performs a timesleep to reproduce human behaviour, and it takes a value of r or random, with a default of 0s. And -s enables TLS fingerprint impersonation, which the usage notes say requires curl_cffi. That second one is the difference between a scanner that looks like a Python client and one that looks like a browser, and it is a legitimate feature of a testing tool since many WAFs key on the client fingerprint.

Concurrency is controlled with -t for the number of threads, defaulting to 10, which is the setting to lower first if a target starts rate limiting you.

The output options generate an HTML report with -o, defaulting to results/ with a date in the filename, and a log file path with -L defaulting to error_logs/. Verbosity is raised with -v, and the log level is set with -l.

Two extras are worth calling out. The --screen option takes a screenshot of confirmed poisoned pages and requires playwright, defaulting to a screenshots/ directory. And --ocp, only-cp, restricts the run to the cache poisoning modules.

The Burp Suite bridge and the proxy options

The Burp integration is a two-part arrangement. There is a custom extension, downloaded as utils/burp_extension_issue.py, and you add it through Extensions, Add, choosing Python as the extension type and selecting the file. The README shows the sequence in the Burp dialog and then says to verify it is loaded in the Extensions tab. The prerequisites are Burp Suite Community or Professional, Python 3.x, and Jython for Burp extensions.

The --burp option then does two things. It sends behaviour findings and confirmed requests to the Burp proxy, defaulting to 127.0.0.1:8080, and it creates issues in Burp Suite for the results, with behaviour findings marked as medium severity and confirmed vulnerabilities as high severity. That split is the point of the integration: a scanner produces a lot of noise and a handful of real findings, and routing the two separately means the confirmed ones get triaged first.

» ./hexhttp.py -u 'https://target.tld/' --burp
» ./hexhttp.py -u 'https://target.tld/' --burp 192.168.1.100:8080

The general proxy option is separate, and it routes all HTTP requests through a proxy rather than just the findings. With no argument it uses 127.0.0.1:8080.

» ./hexhttp.py -u 'https://target.tld/' --proxy 10.0.0.1:3128
» ./hexhttp.py -u 'https://target.tld/' --proxy

The two can be combined, and the example makes the intent clear: route all traffic through a corporate proxy while sending findings to Burp.

» ./hexhttp.py -u 'https://target.tld/' --proxy corporate.proxy:3128 --burp 127.0.0.1:8080

Four proxy formats are supported: host:port, host alone which uses the default port 8080, a full http:// URL, and https:// for an HTTPS proxy.

Where HExHTTP is the wrong tool

The first limitation is that this is a targeted assessment tool and not a mass scanner. It takes a URL or a file of URLs, and it sends crafted payloads with cache poisoning and denial of service payloads in them. Pointing it at a range of hosts you do not own is both a legal problem and a practical one, since a single run with the default ten threads across many hosts is a lot of hostile-looking traffic from your address.

The second is that the findings are only as good as the analysis rules. The tool reports vulnerabilities and interesting behaviours, and its verdict depends on how the response headers change, which means a caching layer that behaves differently in production than in a test, a CDN that sits in front of the origin, or a WAF that rewrites headers will all change the result. The README's own example is described as being on a public target, which is the right way to calibrate expectations about what a finding means.

The third is the beta classification and the moving target underneath it. The releases are frequent, v2.5 in March 2026, v2.6 in May and v2.7 in September, and the last push was on 2026-09-06, so the tool changes often. A finding recorded from one version may not reproduce from the next, and a scanner whose rule set moves is one you have to re-run rather than one whose output you can act on once.

The fourth is the optional dependencies. The stealth option needs curl_cffi, the screenshot option needs playwright, and the Burp bridge needs Jython on the Burp side. A deployment that wants all three has three extra toolchains, and the ones that are not installed simply make the corresponding feature unavailable rather than failing loudly.

The fifth is that this tool does not cover the rest of a web application assessment. There is nothing here about authentication logic, access control, injection points in parameters or the business logic of the application. It is a header-focused tool, and a team looking for a full assessment platform is looking at something else.

Licence, maintenance and the cost of the scanning workflow

The project is under the MIT licence. GitHub shows the licence field as unknown, but the package metadata sets license to MIT as text, and the pyproject classifiers include the MIT licence classifier, so the terms are documented even if the hosting site cannot classify them.

The repository is not archived and the last push was on 2026-09-06, the same day as the v2.7 release, so the tool is actively maintained. There is a CHANGELOG.md linked from the README as the news page, a pre-commit configuration, and a dev extra that collects black, ruff, mypy, bandit and pytest, which tells you the project treats its own linting and security scanning as part of the workflow.

The cost of the tool is low in resources. It is a Python package with a handful of common dependencies, it runs from a clone or a container, and the output is a directory of files. There is no server, no database and no account.

The cost of running it as a workflow is the reporting. The results go to a dated HTML report, the errors to a log directory, and the confirmed screenshots to a screenshots directory, and none of that is integrated into anything else. The Burp bridge is the answer to that for a team already working in Burp, and for anyone else the HTML report is a document you read once and then have to reconcile with the rest of their findings by hand.

The Dockerfile is a minimal build on a Python 3.11 Alpine base, which keeps the image small and the install reproducible, and the entrypoint points straight at the script. The Docker and pip installation paths are the two supported ones, and the pip install hexhttp route means a tester can add it to a tooling environment without a clone.

Editorial conclusion

HExHTTP suits a security engineer running an authorised assessment of a web application, since it puts header analysis, cache poisoning checks and evidence capture behind one command instead of a directory of Burp extensions. It does not suit scanning an arbitrary internet range, since the tool sends crafted payloads and expects a target you are allowed to test. Start with a single URL, read the generated HTML report before widening the scope, and note that the stealth and screenshot options need curl_cffi and playwright respectively.

Frequently asked questions

Official sources

1. c0dejump/HExHTTP on GitHub
2. Issues
3. README
4. Releases