This basic http server helps you to debug incoming http requests. It helps you to debug 3rd party webhooks etc...
You can install directly the latest version if you have go installation;
go install github.com/vbyazilim/basichttpdebugger@latestThen run:
basichttpdebugger -h
Usage of basichttpdebugger:
-color
enable color
-hmac-header-name string
name of your signature header, e.g. X-Hub-Signature-256
-hmac-secret string
your HMAC secret value
-listen string
listen addr (default ":9002")
-output string
output/write responses to (default "stdout")
-save-format string
save filename format of raw http (default "%Y-%m-%d-%H%i%s-{hostname}-{url}.raw")
-save-raw-http-request
enable saving of raw http request
-version
display version informationStart the server;
basichttpdebugger # listens at :9002Listen different port:
basichttpdebugger -listen ":8000" # listens at :8000If you want to test HMAC validation;
basichttpdebugger -listen ":8000" -hmac-secret "<secret>" -hmac-header-name "<X-HEADER-NAME>"
basichttpdebugger -color -listen ":8000" -hmac-secret "<secret>" -hmac-header-name "<X-HEADER-NAME>"Instead of standard output, pipe everything to file!
basichttpdebugger -listen ":8000" -hmac-secret "<secret>" -hmac-header-name "<X-HEADER-NAME>" -output "/tmp/foo"Now, tail /tmp/foo:
tail -f /tmp/fooWell, add some colors :)
basichttpdebugger -listen ":8000" -colorColor output is disabled if the output is set to file! You can also save/capture Raw HTTP Request for later use too:
basichttpdebugger -save-raw-http-request # will create something like:
# 2024-12-26-163253-localhost_9002-_.raw
# slashes become _If you make:
curl localhost:9002/test/post/data -d '{"foo": "bar"}'
OK
Raw HTTP Request is saved to: 2024-12-26-163406-localhost_9002-_test_post_data.rawSet custom filename format:
basichttpdebugger -save-raw-http-request -save-format="~/Desktop/%Y-%m-{hostname}.raw"
OK
Raw HTTP Request is saved to: /Users/vigo/Desktop/2024-12-localhost_9002.rawYou can replicate the same http request with using nc:
nc localhost 9002 < /Users/vigo/Desktop/2024-12-localhost_9002.rawYou can also clone the source repo and run it locally;
cd /path/to/go/develompent/
git clone github.com/vbyazilim/basichttpdebugger
cd basichttpdebugger/
go run . -h # help
go run . -version # display version information
go run . # starts server, listens at :9002
go run . -listen ":8000" # listens at :8000
# or if you have ruby installed, use rake tasks!
rake # listens at :9002
LISTEN=":8000" rake # listens at :8000
LISTEN=":8000" HMAC_SECRET="<secret>" HMAC_HEADER_NAME="<X-HEADER-NAME>" rake
LISTEN=":8000" HMAC_SECRET="<secret>" HMAC_HEADER_NAME="<X-HEADER-NAME>" COLOR=1 rake
LISTEN=":8000" HMAC_SECRET="<secret>" HMAC_HEADER_NAME="<X-HEADER-NAME>" OUTPUT="/tmp/foo" rake
SAVE_RAW_HTTP_REQUEST=t rake
SAVE_RAW_HTTP_REQUEST=t SAVE_FORMAT="~/Desktop/%Y-%m-%d-%H%i%s-test.raw" rake| Flag | Environment Variable | Default Value |
|---|---|---|
-hmac-header-name |
HMAC_HEADER_NAME |
Not set |
-hmac-secret |
HMAC_SECRET |
Not set |
-color |
COLOR |
false |
-listen |
LISTEN |
:9002 |
-output |
OUTPUT |
stdout |
-save-raw-http-request |
SAVE_RAW_HTTP_REQUEST |
false |
-save-format |
SAVE_FORMAT |
%Y-%m-%d-%H%i%s-{hostname}.raw |
Most of the format is taken from Django!
| Placeholder | Description | Example |
|---|---|---|
{hostname} |
Host name :) | localhost_9002 |
{url} |
URL path | /test/post/data => _test_post_data |
%d |
Day of the month, 2 digits with leading zeros. | 01 to 31 |
%j |
Day of the month without leading zeros. | 1 to 31 |
%D |
Day of the week, textual, 3 letters. | Fri |
%l |
Day of the week, textual, long. | Friday |
%w |
Day of the week, digits without leading zeros. | 0 (Sunday) |
%z |
Day of the year. | 1 to 366 |
%W |
ISO-8601 week number of year, with weeks starting on Monday. | 1 to 53 |
%m |
Month, 2 digits with leading zeros. | 01 to 12 |
%n |
Month without leading zeros. | 1 to 12 |
%M |
Month, textual, 3 letters. | Jan |
%b |
Month, textual, 3 letters, lowercase. | jan |
%F |
Month, textual, long. | January |
%t |
Number of days in the given month. | 28 to 31 |
%y |
Year, 2 digits with leading zeros. | 00 to 99 |
%Y |
Year, 4 digits with leading zeros. | 0001 to 9999 |
%g |
Hour, 12-hour format without leading zeros. | 1 to 12 |
%G |
Hour, 24-hour format without leading zeros. | 0 to 23 |
%h |
Hour, 12-hour format. | 01 to 12 |
%H |
Hour, 24-hour format. | 00 to 23 |
%i |
Minutes. | 00 to 59 |
%s |
Seconds, 2 digits with leading zeros. | 00 to 59 |
%u |
Microseconds. | 000000 to 999999 |
%A |
Meridiem system. | AM or PM |
Here is how it looks, a GitHub webhook (trimmed, masked due to it’s huge/private data):
----------------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------------------------------------------+
| Basic HTTP Debugger |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| Version | <version> |
| Build | <build-sha> |
| Request Time | 2024-12-26 07:37:29.704382 +0000 UTC |
| HTTP Method | POST |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| Request Headers |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| Accept | */* |
| Accept-Encoding | gzip |
| Content-Length | 11453 |
| Content-Type | application/json |
| User-Agent | GitHub-Hookshot/******* |
| X-Forwarded-For | 140.82.115.54 |
| X-Forwarded-Host | ****.ngrok-free.app |
| X-Forwarded-Proto | https |
| X-Github-Delivery | 0d27de20-****-11ef-****-78dbc150f59f |
| X-Github-Event | issue_comment |
| X-Github-Hook-Id | ****02493 |
| X-Github-Hook-Installation-Target-Id | 90642**** |
| X-Github-Hook-Installation-Target-Type | repository |
| X-Hub-Signature | sha1=****************60a5a88092f5c4678b06fd1e |
| X-Hub-Signature-256 | sha256=****************bebf86cbf7bc1c69a93ff8a3d1ff0cf20ee31ff57ed85ab2 |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| Payload |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| HMAC Secret | ******************* |
| HMAC Header Name | X-Hub-Signature-256 |
| Incoming Signature | sha256=****************bebf86cbf7bc1c69a93ff8a3d1ff0cf20ee31ff57ed85ab2 |
| Expected Signature | sha256=****************bebf86cbf7bc1c69a93ff8a3d1ff0cf20ee31ff57ed85ab2 |
| Is Valid? | true |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| Incoming | application/json |
+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| { |
| "action": "created", |
| "comment": { |
| : |
| : |
| "reactions": { |
| : |
| : |
| }, |
| : |
| "user": { |
| : |
| : |
| : |
| } |
| }, |
| "issue": { |
| : |
| "reactions": { |
| : |
| : |
| : |
| }, |
| : |
| "user": { |
| : |
| } |
| }, |
| "organization": { |
| : |
| : |
| : |
| }, |
| "repository": { |
| : |
| : |
| : |
| "owner": { |
| : |
| }, |
| : |
| : |
| }, |
| "sender": { |
| : |
| : |
| } |
| } |
+--------------------------------------------------------------------------------------------------------------------------------------------------+
----------------------------------------------------------------------------------------------------
Raw Http Request
----------------------------------------------------------------------------------------------------
POST /webhook/github HTTP/1.1
Host: ****.ngrok-free.app
Accept: */*
Accept-Encoding: gzip
Content-Length: 11453
Content-Type: application/json
User-Agent: GitHub-Hookshot/*******
X-Forwarded-For: 140.82.115.54
X-Forwarded-Host: ****.ngrok-free.app
X-Forwarded-Proto: https
X-Github-Delivery: 0d27de20-****-11ef-****-78dbc150f59f
X-Github-Event: issue_comment
X-Github-Hook-Id: 51990****
X-Github-Hook-Installation-Target-Id: 90642****
X-Github-Hook-Installation-Target-Type: repository
X-Hub-Signature: sha1=************a68b60a5a88092f5c4678b06fd1e
X-Hub-Signature-256: sha256=************3d61bebf86cbf7bc1c69a93ff8a3d1ff0cf20ee31ff57ed85ab2
{"action":"created","issue":{"url": ...} ... }
----------------------------------------------------------------------------------------------------
For local docker usage, default expose port is: 9002.
docker build -t <your-image> .
docker run -p 9002:9002 <your-image> # run from default port
docker run -p 8400:8400 <your-image> -listen ":8400" # run from 8400
docker run -p 8400:8400 <your-image> -listen ":8400" -hmac-secret "<secret>" -hmac-header-name "<X-HEADER-NAME>"You can download/use from docker hub or ghcr:
- https://hub.docker.com/r/vigo/basichttpdebugger/
- https://github.com/vbyazilim/basichttpdebugger/pkgs/container/basichttpdebugger%2Fbasichttpdebugger
docker run vigo/basichttpdebugger
docker run -p 9002:9002 vigo/basichttpdebugger # run from default port
docker run -p 8400:8400 vigo/basichttpdebugger -listen ":8400" # run from 8400
# run from docker hub on port 9100 with hmac support
docker run -p 9100:9100 vigo/basichttpdebugger -listen ":9100" -hmac-secret "<secret>" -hmac-header-name "<X-HEADER-NAME>"
# run from ghcr on default port
docker run -p 9002:9002 ghcr.io/vbyazilim/basichttpdebugger/basichttpdebugger:latest
# run from ghcr on 9100
docker run -p 9100:9100 ghcr.io/vbyazilim/basichttpdebugger/basichttpdebugger:latest -listen ":9100"
# run from ghcr on 9100 with hmac support
docker run -p 9100:9100 ghcr.io/vbyazilim/basichttpdebugger/basichttpdebugger:latest -listen ":9100" -hmac-secret "<secret>" -hmac-header-name "<X-HEADER-NAME>"rake -T
rake coverage # show test coverage
rake docker:build # build docker image locally
rake docker:run # run docker image locally
rake release[revision] # release new version major,minor,patch, default: patch
rake run # run server (default port 9002)
rake test # run test2024-12-24
- refactor from scratch
- disable color when output is file (due to ansi codes, output looks glitchy)
- auto detect terminal and column width
- add raw http request for response
2024-12-23
- many improvements, pretty output with colors!
- now you can pipe to file too!
2024-09-17
- change default host port to
9002 - add github actions for docker hub and ghcr
2024-06-22
- remove environment variables from source. only
raketask requires environment variables - add command-line flags:
-listen,-hmac-secret,-hmac-header-name,-h,--help - add HMAC validation indicator
- Add http form requests support
- Add http file upload requests support
$ rake -T
rake coverage # show test coverage
rake docker:build # build docker image locally
rake docker:run # run docker image locally
rake release[revision] # release new version major,minor,patch, default: patch
rake run # run server (default port 9002)
rake test # run testThis project is licensed under MIT
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
