Skip to content

Commit

Permalink
change flag prefix and add a note on installation from source
Browse files Browse the repository at this point in the history
  • Loading branch information
xiam committed Apr 27, 2020
1 parent 75958e1 commit 1a8c26f
Showing 1 changed file with 28 additions and 18 deletions.
46 changes: 28 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,20 @@ If you'd rather not accept free candy from this van you can also grab a release
from our [releases page](https://github.com/malfunkt/hyperfox/releases) and
install it manually.

### Building `hyperfox` from source

In order to build `hyperfox` from source you'll need Go and a C compiler:

Use `go install` to build and install `hyperfox`:

```
go install github.com/malfunkt/hyperfox
```

## How does it work?

Hyperfox creates a transparent HTTP proxy server and binds it to port 1080/TCP
on localhost (`--addr 127.0.0.1 --http 1080`). The proxy server reads plaintext
on localhost (`-addr 127.0.0.1 -http 1080`). The proxy server reads plaintext
HTTP requests and redirects them to the target destination (the `Host` header
is used to identify the destination), when the target destination replies,
Hyperfox intercepts the response and forwards it to the original client.
Expand All @@ -30,7 +40,7 @@ All HTTP communications between origin and destination are intercepted by
Hyperfox and recorded on a SQLite database that is created automatically.
Everytime Hyperfox starts, a new database is created (e.g.:
`hyperfox-00123.db`). You can change this behaviour by explicitly providing a
database name (e.g.: `--db traffic-log.db`).
database name (e.g.: `-db traffic-log.db`).

### Usage

Expand All @@ -54,22 +64,22 @@ you should be able to see a log for the page you requested in Hyperfox's output:
127.0.0.1:44254 - - [11/Apr/2020:19:19:48 -0500] "GET http://example.com/ HTTP/1.1" 200 -1
```

### User interface (`--ui`)
### User interface (`-ui`)

![hyperfox-ui](https://user-images.githubusercontent.com/385670/79090465-6e7eb300-7d0f-11ea-8fc6-df1e6da8a12e.png)

Use the `--ui` parameter to enable Hyperfox UI wich will open in a new browser
Use the `-ui` parameter to enable Hyperfox UI wich will open in a new browser
window:

```
hyperfox --db records.db --ui
hyperfox -db records.db -ui
```

The above command creates a web server that binds to `127.0.0.1:1984`. If you'd
like to change the bind address or port use the `--ui-addr` switch:
like to change the bind address or port use the `-ui-addr` switch:

```
hyperfox --db records.db --ui --ui-addr 127.0.0.1:3000
hyperfox -db records.db -ui -ui-addr 127.0.0.1:3000
```

Changing the UI server address is specially useful when Hyperfox is running on
Expand All @@ -84,14 +94,14 @@ might not be adecuate.

#### Run Hyperfox UI on your mobile device

When the `--ui-addr`parameter is different from `127.0.0.1` Hyperfox will
When the `-ui-addr`parameter is different from `127.0.0.1` Hyperfox will
output a QR code to make it easier to connect from mobile devices:

```
hyperfox --db records.db --ui --ui-addr 192.168.1.23:1984
hyperfox -db records.db -ui -ui-addr 192.168.1.23:1984
```

### SSL/TLS mode (`--ca-cert` & `--ca-key`)
### SSL/TLS mode (`-ca-cert` & `-ca-key`)

SSL/TLS connections are secure end to end and protected from eavesdropping.
Hyperfox won't be able to see anything happening between a client and a secure
Expand Down Expand Up @@ -119,11 +129,11 @@ device:

![Hyperfox root CA certificate](https://chart.googleapis.com/chart?cht=qr&choe=UTF-8&chs=220x220&chl=https://static.hyperfox.org/rootCA.crt)

Use the `--ca-cert` and `--ca-key` flags to provide Hyperfox with the root CA
Use the `-ca-cert` and `-ca-key` flags to provide Hyperfox with the root CA
certificate and key you'd like to use:

```
hyperfox --ca-cert rootCA.crt --ca-key rootCA.key
hyperfox -ca-cert rootCA.crt -ca-key rootCA.key
```

the above command creates a special server and binds it to `127.0.0.1:10443`,
Expand All @@ -135,20 +145,20 @@ this certificate is signed with the providede root CA key.

#### TLS interception example

Launch Hyperfox with appropriate TLS parameters and `--http 443` (port 443
Launch Hyperfox with appropriate TLS parameters and `-http 443` (port 443
requires admin privileges).

```
sudo hyperfox --ca-cert ./ca/rootCA.crt --ca-key ./ca/rootCA.key --https 443
sudo hyperfox -ca-cert ./ca/rootCA.crt -ca-key ./ca/rootCA.key -https 443
```

Use cURL to build a HTTPs request to example.com: the `--resolve` option tells
Use cURL to build a HTTPs request to example.com: the `-resolve` option tells
cURL to skip DNS verification and use `127.0.0.1` as if it were the legitimate
address for `example.com`, while the `-k` parameter tells cURL to accept any
TLS certificate.

```
curl -k --resolve example.com:443:127.0.0.1 https://example.com
curl -k -resolve example.com:443:127.0.0.1 https://example.com
```

you should be able to see a log for the page you requested in Hyperfox's output:
Expand All @@ -169,11 +179,11 @@ example.com 127.0.0.1

Run Hyperfox with the options you'd like, just remember that you should use
ports 80 for HTTP and 443 for HTTPS, and that requires admin privileges. In
addition to `--http` and `--https` use the `--dns` parameter with a valid DNS
addition to `-http` and `-https` use the `-dns` parameter with a valid DNS
resolver:

```
sudo hyperfox --ui --http 80 --dns 8.8.8.8
sudo hyperfox -ui -http 80 -dns 8.8.8.8
```

that will make Hyperfox skip the OS DNS resolver and use an alternative one
Expand Down

0 comments on commit 1a8c26f

Please sign in to comment.