mirror of
https://github.com/dstotijn/hetty.git
synced 2025-07-01 18:47:29 -04:00
Update README
This commit is contained in:
David Stotijn
263
README.md
263
README.md
@ -1,243 +1,148 @@
|
|||||||
<h1>
|
<h1>
|
||||||
<a href="https://github.com/dstotijn/hetty">
|
<img src="https://hetty.xyz/img/hetty_light.svg#gh-light-mode-only" width="240"/>
|
||||||
<img src="https://hetty.xyz/assets/logo.png" width="293">
|
<img src="https://hetty.xyz/img/hetty_dark.svg#gh-dark-mode-only" width="240"/>
|
||||||
</a>
|
|
||||||
</h1>
|
</h1>
|
||||||
|
|
||||||
[](https://github.com/dstotijn/hetty/releases/latest)
|
[](https://github.com/dstotijn/hetty/releases/latest)
|
||||||
[](https://github.com/dstotijn/hetty/actions/workflows/build-test.yml)
|
[](https://github.com/dstotijn/hetty/actions/workflows/build-test.yml)
|
||||||
|
|
||||||
[](https://github.com/dstotijn/hetty/blob/master/LICENSE)
|
[](https://github.com/dstotijn/hetty/blob/master/LICENSE)
|
||||||
[](https://hetty.xyz/)
|
[](https://hetty.xyz/)
|
||||||
|
|
||||||
**Hetty** is an HTTP toolkit for security research. It aims to become an open
|
**Hetty** is an HTTP toolkit for security research. It aims to become an open
|
||||||
source alternative to commercial software like Burp Suite Pro, with powerful
|
source alternative to commercial software like Burp Suite Pro, with powerful
|
||||||
features tailored to the needs of the infosec and bug bounty community.
|
features tailored to the needs of the infosec and bug bounty community.
|
||||||
|
|
||||||
<img src="https://hetty.xyz/assets/hetty_v0.2.0_header.png">
|
<img src="https://hetty.xyz/img/hero.png" width="907" alt="Hetty proxy logs (screenshot)" />
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- Man-in-the-middle (MITM) HTTP/1.1 proxy with logs
|
- Machine-in-the-middle (MITM) HTTP proxy, with logs and advanced search
|
||||||
- Project based database storage (BadgerDB)
|
- HTTP client for manually creating/editing requests, and replay proxied requests
|
||||||
- Scope support
|
- Scope support, to help keep work organized
|
||||||
- Headless management API using GraphQL
|
- Easy-to-use web based admin interface
|
||||||
- Embedded web interface (Next.js)
|
- Project based database storage, to help keep work organized
|
||||||
|
|
||||||
ℹ️ Hetty is in early development. Additional features are planned
|
👷♂️ Hetty is under active development. Check the <a
|
||||||
for a `v1.0` release. Please see the <a href="https://github.com/dstotijn/hetty/projects/1">backlog</a>
|
href="https://github.com/dstotijn/hetty/projects/1">backlog</a> for the current
|
||||||
for details.
|
status.
|
||||||
|
|
||||||
## Documentation
|
📣 Are you pen testing professionaly in a team? I would love to hear your
|
||||||
|
thoughts on tooling via [this 5 minute
|
||||||
|
survey](https://forms.gle/36jtgNc3TJ2imi5A8). Thank you!
|
||||||
|
|
||||||
📖 [Read the docs.](https://hetty.xyz/)
|
## Getting started
|
||||||
|
|
||||||
## Installation
|
💡 The [Getting started](https://hetty.xyz/docs/getting-started) doc has more
|
||||||
|
detailed install and usage instructions.
|
||||||
|
|
||||||
Hetty compiles to a self-contained binary, with an embedded BadgerDB database
|
### Installation
|
||||||
and web based admin interface.
|
|
||||||
|
|
||||||
### Install pre-built release (recommended)
|
The quickest way to install and update Hetty is via a package manager:
|
||||||
|
|
||||||
👉 Downloads for Linux, macOS and Windows are available on the [releases page](https://github.com/dstotijn/hetty/releases).
|
#### macOS
|
||||||
|
|
||||||
### Build from source
|
```sh
|
||||||
|
brew install hettysoft/tap/hetty
|
||||||
#### Prerequisites
|
|
||||||
|
|
||||||
- [Go 1.16](https://golang.org/)
|
|
||||||
- [Yarn](https://yarnpkg.com/)
|
|
||||||
|
|
||||||
When building from source, the static resources for the admin interface
|
|
||||||
(Next.js) need to be generated via [Yarn](https://yarnpkg.com/). The generated
|
|
||||||
files will be embedded (using the [embed](https://golang.org/pkg/embed/)
|
|
||||||
package) when you use the `build` Makefile target.
|
|
||||||
|
|
||||||
Clone the repository and use the `build` make target to create a binary:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ git clone git@github.com:dstotijn/hetty.git
|
|
||||||
$ cd hetty
|
|
||||||
$ make build
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Docker
|
#### Linux
|
||||||
|
|
||||||
A Docker image is available on Docker Hub: [`dstotijn/hetty`](https://hub.docker.com/r/dstotijn/hetty).
|
```sh
|
||||||
For persistent storage of CA certificates and projects database, mount a volume:
|
sudo snap install hetty
|
||||||
|
|
||||||
```
|
|
||||||
$ mkdir -p $HOME/.hetty
|
|
||||||
$ docker run -v $HOME/.hetty:/root/.hetty -p 8080:8080 dstotijn/hetty
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
#### Windows
|
||||||
|
|
||||||
When Hetty is run, by default it listens on `:8080` and is accessible via
|
```sh
|
||||||
http://localhost:8080. Depending on incoming HTTP requests, it either acts as a
|
scoop bucket add hettysoft https://github.com/hettysoft/scoop.git
|
||||||
MITM proxy, or it serves the API and web interface.
|
scoop install hettysoft/hetty
|
||||||
|
|
||||||
By default, the projects database files and CA certificates are stored in a `.hetty`
|
|
||||||
directory under the user's home directory (`$HOME` on Linux/macOS, `%USERPROFILE%`
|
|
||||||
on Windows).
|
|
||||||
|
|
||||||
To start, ensure `hetty` (downloaded from a release, or manually built) is in your
|
|
||||||
`$PATH` and run:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ hetty
|
|
||||||
```
|
```
|
||||||
|
|
||||||
An overview of configuration flags:
|
#### Other
|
||||||
|
|
||||||
```
|
Alternatively, you can [download the latest release from
|
||||||
$ hetty -h
|
GitHub](https://github.com/dstotijn/hetty/releases/latest) for your OS and
|
||||||
Usage of ./hetty:
|
architecture, and move the binary to a directory in your `$PATH`. If your OS is
|
||||||
-addr string
|
not available for one of the package managers or not listed in the GitHub
|
||||||
TCP address to listen on, in the form "host:port" (default ":8080")
|
releases, you can compile from source _(link coming soon)_ or use a Docker image
|
||||||
-adminPath string
|
_(link coming soon)_.
|
||||||
File path to admin build
|
|
||||||
-cert string
|
|
||||||
CA certificate filepath. Creates a new CA certificate if file doesn't exist (default "~/.hetty/hetty_cert.pem")
|
|
||||||
-key string
|
|
||||||
CA private key filepath. Creates a new CA private key if file doesn't exist (default "~/.hetty/hetty_key.pem")
|
|
||||||
-db string
|
|
||||||
Database directory path (default "~/.hetty/db")
|
|
||||||
```
|
|
||||||
|
|
||||||
You should see:
|
### Usage
|
||||||
|
|
||||||
```
|
Once installed, start Hetty via:
|
||||||
2022/01/26 10:34:24 [INFO] Hetty (v0.3.2) is running on :8080 ...
|
|
||||||
```
|
|
||||||
|
|
||||||
Then, visit [http://localhost:8080](http://localhost:8080) to get started.
|
|
||||||
|
|
||||||
ℹ️ Detailed documentation is under development and will be available soon.
|
|
||||||
|
|
||||||
## Certificate Setup and Installation
|
|
||||||
|
|
||||||
In order for Hetty to proxy requests going to HTTPS endpoints, a root CA certificate for
|
|
||||||
Hetty will need to be set up. Furthermore, the CA certificate may need to be
|
|
||||||
installed to the host for them to be trusted by your browser. The following steps
|
|
||||||
will cover how you can generate your certificate, provide them to hetty, and how
|
|
||||||
you can install them in your local CA store.
|
|
||||||
|
|
||||||
⚠️ _This process was done on a Linux machine but should_
|
|
||||||
_provide guidance on Windows and macOS as well._
|
|
||||||
|
|
||||||
### Generating CA certificates
|
|
||||||
|
|
||||||
You can generate a CA keypair two different ways. The first is bundled directly
|
|
||||||
with Hetty, and simplifies the process immensely. The alternative is using OpenSSL
|
|
||||||
to generate them, which provides more control over expiration time and cryptography
|
|
||||||
used, but requires you install the OpenSSL tooling. The first is suggested for any
|
|
||||||
beginners trying to get started.
|
|
||||||
|
|
||||||
#### Generating CA certificates with hetty
|
|
||||||
|
|
||||||
Hetty will generate the default key and certificate on its own if none are supplied
|
|
||||||
or found in `~/.hetty/` when first running the CLI. To generate a default key and
|
|
||||||
certificate with hetty, simply run the command with no arguments
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
hetty
|
hetty
|
||||||
```
|
```
|
||||||
|
|
||||||
You should now have a key and certificate located at `~/.hetty/hetty_key.pem` and
|
💡 Read the [Getting started](https://hetty.xyz/docs/getting-started) doc for
|
||||||
`~/.hetty/hetty_cert.pem` respectively.
|
more details.
|
||||||
|
|
||||||
#### Generating CA certificates with OpenSSL
|
To list all available options, run: `hetty --help`:
|
||||||
|
|
||||||
You can start off by generating a new key and CA certificate which will both expire
|
|
||||||
after a month.
|
|
||||||
|
|
||||||
```sh
|
|
||||||
mkdir ~/.hetty
|
|
||||||
openssl req -newkey rsa:2048 -new -nodes -x509 -days 31 -keyout ~/.hetty/hetty_key.pem -out ~/.hetty/hetty_cert.pem
|
|
||||||
```
|
|
||||||
|
|
||||||
The default location which `hetty` will check for the key and CA certificate is under
|
|
||||||
`~/.hetty/`, at `hetty_key.pem` and `hetty_cert.pem` respectively. You can move them
|
|
||||||
here and `hetty` will detect them automatically. Otherwise, you can specify the
|
|
||||||
location of these as arguments to `hetty`.
|
|
||||||
|
|
||||||
```
|
```
|
||||||
hetty -key key.pem -cert cert.pem
|
$ hetty --help
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
hetty [flags] [subcommand] [flags]
|
||||||
|
|
||||||
|
Runs an HTTP server with (MITM) proxy, GraphQL service, and a web based admin interface.
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--cert Path to root CA certificate. Creates file if it doesn't exist. (Default: "~/.hetty/hetty_cert.pem")
|
||||||
|
--key Path to root CA private key. Creates file if it doesn't exist. (Default: "~/.hetty/hetty_key.pem")
|
||||||
|
--db Database directory path. (Default: "~/.hetty/db")
|
||||||
|
--addr TCP address for HTTP server to listen on, in the form \"host:port\". (Default: ":8080")
|
||||||
|
--chrome Launch Chrome with proxy settings applied and certificate errors ignored. (Default: false)
|
||||||
|
--verbose Enable verbose logging.
|
||||||
|
--json Encode logs as JSON, instead of pretty/human readable output.
|
||||||
|
--version, -v Output version.
|
||||||
|
--help, -h Output this usage text.
|
||||||
|
|
||||||
|
Subcommands:
|
||||||
|
- cert Certificate management
|
||||||
|
|
||||||
|
Run `hetty <subcommand> --help` for subcommand specific usage instructions.
|
||||||
|
|
||||||
|
Visit https://hetty.xyz to learn more about Hetty.
|
||||||
```
|
```
|
||||||
|
|
||||||
### Trusting the CA certificate
|
## Documentation
|
||||||
|
|
||||||
In order for your browser to allow traffic to the local Hetty proxy, you may need
|
📖 [Read the docs](https://hetty.xyz/docs)
|
||||||
to install these certificates to your local CA store.
|
|
||||||
|
|
||||||
On Ubuntu, you can update your local CA store with the certificate by running the
|
|
||||||
following commands:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
sudo cp ~/.hetty/hetty_cert.pem /usr/local/share/ca-certificates/hetty.crt
|
|
||||||
sudo update-ca-certificates
|
|
||||||
```
|
|
||||||
|
|
||||||
On Windows, you would add your certificate by using the Certificate Manager. You
|
|
||||||
can launch that by running the command:
|
|
||||||
|
|
||||||
```batch
|
|
||||||
certmgr.msc
|
|
||||||
```
|
|
||||||
|
|
||||||
On macOS, you can add your certificate by using the Keychain Access program. This
|
|
||||||
can be found under `Application/Utilities/Keychain Access.app`. After opening this,
|
|
||||||
drag the certificate into the app. Next, open the certificate in the app, enter the
|
|
||||||
_Trust_ section, and under _When using this certificate_ select _Always Trust_.
|
|
||||||
|
|
||||||
_Note: Various Linux distributions may require other steps or commands for updating_
|
|
||||||
_their certificate authority. See the documentation relevant to your distribution for_
|
|
||||||
_more information on how to update the system to trust your self-signed certificate._
|
|
||||||
|
|
||||||
## Vision and roadmap
|
|
||||||
|
|
||||||
- Fast core/engine, built with Go, with a minimal memory footprint.
|
|
||||||
- Easy to use admin interface, built with Next.js and Material UI.
|
|
||||||
- Headless management, via GraphQL API.
|
|
||||||
- Extensibility is top of mind. All modules are written as Go packages, to
|
|
||||||
be used by Hetty, but also as libraries by other software.
|
|
||||||
- Pluggable architecture for MITM proxy, projects, scope. It should be possible.
|
|
||||||
to build a plugin system in the (near) future.
|
|
||||||
- Based on feedback and real-world usage of pentesters and bug bounty hunters.
|
|
||||||
- Aim for a relatively small core feature set that the majority of security researchers need.
|
|
||||||
|
|
||||||
## Support
|
## Support
|
||||||
|
|
||||||
Use [issues](https://github.com/dstotijn/hetty/issues) for bug reports and
|
Use [issues](https://github.com/dstotijn/hetty/issues) for bug reports and
|
||||||
feature requests, and [discussions](https://github.com/dstotijn/hetty/discussions)
|
feature requests, and
|
||||||
for questions and troubleshooting.
|
[discussions](https://github.com/dstotijn/hetty/discussions) for questions and
|
||||||
|
troubleshooting.
|
||||||
|
|
||||||
## Community
|
## Community
|
||||||
|
|
||||||
💬 [Join the Hetty Discord server](https://discord.gg/3HVsj5pTFP).
|
💬 [Join the Hetty Discord server](https://discord.gg/3HVsj5pTFP)
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Want to contribute? Great! Please check the [Contribution Guidelines](CONTRIBUTING.md)
|
Want to contribute? Great! Please check the [Contribution
|
||||||
for details.
|
Guidelines](CONTRIBUTING.md) for details.
|
||||||
|
|
||||||
## Acknowledgements
|
## Acknowledgements
|
||||||
|
|
||||||
- Thanks to the [Hacker101 community on Discord](https://www.hacker101.com/discord)
|
- Thanks to the [Hacker101 community on Discord](https://www.hacker101.com/discord)
|
||||||
for all the encouragement and feedback.
|
for the encouragement and early feedback.
|
||||||
- The font used in the logo and admin interface is [JetBrains Mono](https://www.jetbrains.com/lp/mono/).
|
- The font used in the logo and admin interface is [JetBrains
|
||||||
|
Mono](https://www.jetbrains.com/lp/mono/).
|
||||||
|
|
||||||
## Sponsors
|
## Sponsors
|
||||||
|
|
||||||
<a href="https://www.tines.com/?utm_source=oss&utm_medium=sponsorship&utm_campaign=hetty">
|
<a href="https://www.tines.com/?utm_source=oss&utm_medium=sponsorship&utm_campaign=hetty">
|
||||||
<img src="https://hetty.xyz/assets/tines-sponsorship-badge.png" width="140" alt="Sponsored by Tines">
|
<img src="https://hetty.xyz/img/tines-sponsorship-badge.png" width="140" alt="Sponsored by Tines">
|
||||||
</a>
|
</a>
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[MIT License](LICENSE)
|
[MIT](LICENSE)
|
||||||
|
|
||||||
---
|
© 2022 Hetty Software
|
||||||
|
|
||||||
© 2021 David Stotijn — [Twitter](https://twitter.com/dstotijn), [Email](mailto:dstotijn@gmail.com)
|
|
||||||
|
|||||||
Reference in New Issue
Block a user