ja3rp

README

JA3RP (JA3 Reverse Proxy)

Ja3RP is a basic reverse proxy server that filters traffic based on JA3 fingerprints. It can also operate as a regular HTTP server for testing purposes.

Inspired by this ja3-server POC.

Installation

# Install library locally:
$ go get github.com/sleeyax/ja3rp

# Install binary globally:
$ go install github.com/sleeyax/ja3rp

Usage

Preparation

A JA3 hash is constructed from a TLS ClientHello packet. For this reason the JA3RP server will need an SSL certificate in order to work.

You can generate a self-signed certificate using the following commands:

$ openssl req -new -subj "/C=US/ST=Utah/CN=localhost" -newkey rsa:2048 -nodes -keyout localhost.key -out localhost.csr
$ openssl x509 -req -days 365 -in localhost.csr -signkey localhost.key -out localhost.crt

Package

The following example starts an HTTPS server and filters incoming traffic based on a JA3 hash. If the hash is found in the whitelist the traffic is forwarded to the configured destination server. Otherwise or if blacklisted the request is blocked.

package main

import (
	"fmt"
	"github.com/sleeyax/ja3rp"
	"github.com/sleeyax/ja3rp/net/http"
	"log"
	"net/url"
)

func main() {
	address := "localhost:1337"
	d, _ := url.Parse("https://example.com")

	server := ja3rp.NewServer(address, ja3rp.ServerOptions{
		Destination: d,
		Whitelist: []string{
			"bd50e49d418ed1777b9a410d614440c4", // firefox
			"b32309a26951912be7dba376398abc3b", // chrome
		},
		Blacklist: []string{
			"3b5074b1b5d032e5620f69f9f700ff0e", // CURL
		},
		OnBlocked: func(w http.ResponseWriter, r *http.Request) {
			fmt.Printf("Sorry, you are not in our whitelist :(")
		},
	})

	err := server.ListenAndServeTLS("certificate.crt", "certificate.key")
	
	log.Fatal(err)
}

CLI

$ ja3rp -h
Usage: ja3rp -a <address> [-d <destination URL> -c <cert file> -k <cert key> -w <whitelist file> -b <blacklist file>]
Example: $ ja3rp -a localhost:1337 -d https://example.com -c certificate.crt -k certificate.key -w whitelist.txt -b blacklist.txt

Hashes should be stored in .txt files, each separated by a new line.

Licenses

This project is licensed with the MIT License.

The included (and then modified) net/http, internal/profile and crypto packages fall under the go source code license.

Documentation

Index

• func JA3Digest(ja3 string) string
• func NewServer(addr string, options ServerOptions) *http.Server
• type Handler
• type Mux
  • func NewMux() *Mux
  • func (mux *Mux) Handle(pattern string, handler http.Handler)
  • func (mux *Mux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
  • func (mux *Mux) Handler(r *http.Request) (h http.Handler, pattern string)
  • func (mux *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerOptions

Functions

func JA3Digest

func JA3Digest(ja3 string) string

JA3Digest creates the JA3 hash from given plaintext JA3 string.

func NewServer

func NewServer(addr string, options ServerOptions) *http.Server

Types

type Handler

type Handler func(w http.ResponseWriter, r *http.Request)

type Mux

type Mux struct {
	// contains filtered or unexported fields
}

Mux is an HTTP request multiplexer. It matches the URL of each incoming request against a list of registered patterns and calls the handler for the pattern that most closely matches the URL.

Patterns name fixed, rooted paths, like "/favicon.ico", or rooted subtrees, like "/images/" (note the trailing slash). Longer patterns take precedence over shorter ones, so that if there are handlers registered for both "/images/" and "/images/thumbnails/", the latter handler will be called for paths beginning "/images/thumbnails/" and the former will receive requests for any other paths in the "/images/" subtree.

Note that since a pattern ending in a slash names a rooted subtree, the pattern "/" matches all paths not matched by other registered patterns, not just the URL with Path == "/".

If a subtree has been registered and a request is received naming the subtree root without its trailing slash, Mux redirects that request to the subtree root (adding the trailing slash). This behavior can be overridden with a separate registration for the path without the trailing slash. For example, registering "/images/" causes Mux to redirect a request for "/images" to "/images/", unless "/images" has been registered separately.

Patterns may optionally begin with a host name, restricting matches to URLs on that host only. Host-specific patterns take precedence over general patterns, so that a handler might register for the two patterns "/codesearch" and "codesearch.google.com/" without also taking over requests for "http://www.google.com/".

Mux also takes care of sanitizing the URL request path and the Host header, stripping the port number and redirecting any request containing . or .. elements or repeated slashes to an equivalent, cleaner URL.

func NewMux

func NewMux() *Mux

NewMux allocates and returns a new Mux.

func (*Mux) Handle

func (mux *Mux) Handle(pattern string, handler http.Handler)

Handle registers the handler for the given pattern. If a handler already exists for pattern, itw ill be overwritten.

func (*Mux) HandleFunc

func (mux *Mux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

HandleFunc registers the handler function for the given pattern.

func (*Mux) Handler

func (mux *Mux) Handler(r *http.Request) (h http.Handler, pattern string)

Handler returns the handler to use for the given request, consulting r.Method, r.Host, and r.URL.Path. It always returns a non-nil handler. If the path is not in its canonical form, the handler will be an internally-generated handler that redirects to the canonical path. If the host contains a port, it is ignored when matching handlers.

The path and host are used unchanged for CONNECT requests.

Handler also returns the registered pattern that matches the request or, in the case of internally-generated redirects, the pattern that will match after following the redirect.

If there is no registered handler that applies to the request, Handler returns a “page not found” handler and an empty pattern.

func (*Mux) ServeHTTP

func (mux *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches the request to the handler whose pattern most closely matches the request URL.

type ServerOptions

type ServerOptions struct {
	// Target server to forward valid traffic to.
	// The reverse proxy mode will be disabled if this field is nil.
	Destination *url.URL

	// Custom Mux to use.
	Mux *Mux

	// Whitelisted JA3 hashes.
	// Only traffic that matches a JA3 from this list will be accepted.
	// If both Whitelist and Blacklist are specified, Blacklist will precede.
	// If both Whitelist and Blacklist are unspecified, all traffic will go through.
	Whitelist []string

	// Blacklisted JA3 hashes
	// Traffic that matches a JA3 from this list will be ignored.
	// If both Whitelist and Blacklist are specified, Blacklist will precede.
	// If both Whitelist and Blacklist are unspecified, all traffic will go through.
	Blacklist []string

	// Called when a JA3 is found on the Blacklist or not on the Whitelist.
	OnBlocked Handler
}