kittykat

kittykat is an on-demand rotating HTTP proxy that routes traffic through the Tor network. It uses a Rust implementation of Tor - Arti - instead of C Tor.

kittykat is designed for web-scraping and for hiding against API rate-limits. This project doesn't encourage the second reason for it's creation. It's just listed as one of the reasons why it was created in the first place.

Features

• Tor Circuit Isolation: For each Proxy-Authorization token we create a new isolation token which ensures that our connection will use a different Tor circuit (if you want to know more about that, see Arti's TorClient struct).

• Automatic Cleanup: Idle isolation tokens are purged after a configurable TTL (default: 10s).

• Anonymous Circuit Isolation: When the authorization header is nowhere to be found, kittykat will still create a new isolation token global for all anonymous connections, which also get's purged after the TTL.

• Bidirectional Tunneling: HTTPs/CONNECT support for secure traffic.

Building

To build kittykat you can simply build it with cargo. You can also install it.

# Build in release mode,
cargo build --release

# or install it.
cargo install --path .

Setup

Configuration

You can configure kittykat using either environment variables or a configuration file. If kittykat sees even one environment variable listed below, it will always choose environment variables over a configuration file.

Below is a list of options you can configure, the environment variable name is enclosed in parenthesis:

• listen_address (KITTYKAT_LISTEN_ADDRESS): required, used to configure the IPv4 address that the proxy will listen on.

• token_lifetime (KITTYKAT_TOKEN_LIFETIME): default: 10000, used to set the TTL (in milliseconds) for both anonymous and session tokens.

• optimistic_stream (KITTYKAT_OPTIMISTIC): default: false, used to configure whether kittykat should open an "optimistic" stream when connecting to the target via Tor. Read this for more information.

• log_level (KITTYKAT_LOG): default: info, used to configure the logging level. Possible values are: trace, debug, info, warn or error.

• max_circuit_dirtiness (KITTYKAT_MAX_CIRC_DIRT): default: 15, used to configure max dirtiness of a Tor circuit. Read this for more information.

Usage

Basic usage

Configure your client to use a HTTP proxy.

# Using cURL.

curl -x http://localhost:8118 https://check.torproject.org/api/ip
#=> { "isTor": true, "IP": "172.18.55.78" }

As you can see we can use kittykat without authorization as it'll generate an anonymous token for us internally.

Reusing circuits

Next, we will authorize ourselves into kittykat so it knows which cat- hold on, that wasn't in the script. Sorry, my brain is being silly. We authorize ourselves to create a new, reausable session for ourselves of course.

# Using cURL.

curl -x http://localhost:8118 --proxy-user "cat:goes meow" https://check.torproject.org/api/ip
#=> { "isTor": true, "IP": "10.72.20.4" }

curl -x http://localhost:8118 --proxy-user "cat:goes meow" https://check.torproject.org/api/ip
#=> { "isTor": true, "IP": "10.72.20.4" }

We got the same IP, yay! :3