Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/enet4/heel-gun
Test HTTP servers for robustness to arbitrary requests
https://github.com/enet4/heel-gun
cli-app http rust testing-tools
Last synced: 3 months ago
JSON representation
Test HTTP servers for robustness to arbitrary requests
- Host: GitHub
- URL: https://github.com/enet4/heel-gun
- Owner: Enet4
- License: apache-2.0
- Created: 2019-03-12T22:56:26.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-06-13T22:18:12.000Z (over 1 year ago)
- Last Synced: 2024-10-12T02:15:09.193Z (3 months ago)
- Topics: cli-app, http, rust, testing-tools
- Language: Rust
- Homepage:
- Size: 78.1 KB
- Stars: 17
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# Heel Gun
[](https://crates.io/crates/heel-gun) [](https://travis-ci.org/Enet4/heel-gun) [](https://deps.rs/repo/github/Enet4/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.
```none
USAGE:
heel-gun [OPTIONS] [outdir]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-N number of iterations to test for each target [default: 100]
ARGS:
the base URL to test
path to configuration file
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:
```none
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:
```csv
method,uri,reason,file
GET,http://testmachine.myspot.net:8080/cool-endpoint/lBtY2g18?id=0&more=891134,501 Not Implemented
GET,http://testmachine.myspot.net:8080/cool-endpoint/ie9EMV9G?id=-1&more=238164,501 Not Implemented
GET,http://testmachine.myspot.net:8080/cool-endpoint/dJ7iV7cs?id=null&more=415128,501 Not Implemented
GET,http://testmachine.myspot.net:8080/cool-endpoint/HCvpC90k?id=null&more=902781,501 Not Implemented
POST,http://testmachine.myspot.net:8080/user/UBwqFvFnXh?admin=undefined,501 Not Implemented
POST,http://testmachine.myspot.net:8080/user/LkspwEu0g4?admin=null,501 Not Implemented
POST,http://testmachine.myspot.net:8080/user/pkgagTBnem?admin,501 Not Implemented
POST,http://testmachine.myspot.net:8080/user/rRdlgzll2D?admin=false,501 Not Implemented
```
Moreover, the HTTP bodies of server error responses are saved as independent
files in an output directory:
```none
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.
`` 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](./heel-gun.d.ts)). See also
the [resources](resources) directory for examples. Support for
[Play framework "routes"](https://www.playframework.com/documentation/2.7.x/ScalaRouting#The-routes-file-syntax)
definitions is available as an experimental feature.
You can also define the `RUST_LOG` environment variable for additional logging
output (as defined by [`log`](https://crates.io/crates/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](LICENSE-APACHE) or )
* MIT license ([LICENSE-MIT](LICENSE-MIT) or )
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.