Heel Gun

Test your HTTP server for robustness to arbitrary inputs. heel-gun is a tool which performs several HTTP requests to identify cases where the server misbehaves. Requests are built randomly based on a set of configurable rules.

Using

This CLI tool expects two main arguments: the base URL to the HTTP server, and a configuration file defining the HTTP endpoints to test and how these arguments are generated.

USAGE:
    heel-gun [OPTIONS] <url> <config> [outdir]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -N <n>        number of iterations to test for each target [default: 100]

ARGS:
    <url>       the base URL to test
    <config>    path to configuration file
    <outdir>    path to the output directory containing the logs [default: output]

Example:

heel-gun http://testmachine.myspot.net:8080 resources/example.yaml -N 4

This will test the server with a random assortment of requests, such as these:

GET http://testmachine.myspot.net:8080/cool-endpoint/lBtY2g18?id=0&more=891134
GET http://testmachine.myspot.net:8080/cool-endpoint/ie9EMV9G?id=-1&more=238164
GET http://testmachine.myspot.net:8080/cool-endpoint/dJ7iV7cs?id=null&more=415128
GET http://testmachine.myspot.net:8080/cool-endpoint/HCvpC90k?id=null&more=902781
POST http://testmachine.myspot.net:8080/user/UBwqFvFnXh?admin=undefined
POST http://testmachine.myspot.net:8080/user/LkspwEu0g4?admin=null
POST http://testmachine.myspot.net:8080/user/pkgagTBnem?admin
POST http://testmachine.myspot.net:8080/user/rRdlgzll2D?admin=false

And record problematic responses in a CSV file:

method,uri,reason,file
GET,http://testmachine.myspot.net:8080/cool-endpoint/lBtY2g18?id=0&more=891134,501 Not Implemented,GET/cool-endpoint/lBtY2g18?id=0&more=891134
GET,http://testmachine.myspot.net:8080/cool-endpoint/ie9EMV9G?id=-1&more=238164,501 Not Implemented,GET/cool-endpoint/ie9EMV9G?id=-1&more=238164
GET,http://testmachine.myspot.net:8080/cool-endpoint/dJ7iV7cs?id=null&more=415128,501 Not Implemented,GET/cool-endpoint/dJ7iV7cs?id=null&more=415128
GET,http://testmachine.myspot.net:8080/cool-endpoint/HCvpC90k?id=null&more=902781,501 Not Implemented,GET/cool-endpoint/HCvpC90k?id=null&more=902781
POST,http://testmachine.myspot.net:8080/user/UBwqFvFnXh?admin=undefined,501 Not Implemented,POST/user/UBwqFvFnXh?admin=undefined
POST,http://testmachine.myspot.net:8080/user/LkspwEu0g4?admin=null,501 Not Implemented,POST/user/LkspwEu0g4?admin=null
POST,http://testmachine.myspot.net:8080/user/pkgagTBnem?admin,501 Not Implemented,POST/user/pkgagTBnem?admin
POST,http://testmachine.myspot.net:8080/user/rRdlgzll2D?admin=false,501 Not Implemented,POST/user/rRdlgzll2D?admin=false

Moreover, the HTTP bodies of server error responses are saved as independent files in an output directory:

output/
├── GET
│   └── cool-endpoint
│       ├── lBtY2g18?id=0&more=891134
│       ├── ie9EMV9G?id=-1&more=238164
│       ├── dJ7iV7cs?id=null&more=415128
│       └──  HCvpC90k?id=null&more=902781
└── POST
    └── user
        ├── UBwqFvFnXh?admin=undefined
        ├── LkspwEu0g4?admin=null
        ├── pkgagTBnem?admin
        └── rRdlgzll2D?admin=false

For the time being, problematic responses are either HTTP responses with a 5xx status code, or requests which result in a broken or timed out connection.

<config> is a file describing a set of rules for producing URI paths and other parameters such as query string arguments. The schema is available as a TypeScript type definition file (heel-gun.d.ts). See also the resources directory for examples. Support for Play framework "routes" definitions is available as an experimental feature.

You can also define the RUST_LOG environment variable for additional logging output (as defined by log, to one of "error", "warn", "info", "debug" or "trace"):

RUST_LOG=info heel-gun http://testmachine.myspot.net:8080 resources/example.yaml

License and Warning Note

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

In spite of the main goal of testing for server robustness, this tool may also present itself as capable of doing dangerous mistakes (such as running in production), poorly intended actions (DoS attacks), and other sorts of misuse. Please be responsible when using heel-gun. As defined by the aforementioned license, all authors and contributors to heel-gun cannot be held liable for any damage which may occur from the use of this software.