ja3transport

README

JA3Transport

For a more in-depth look at the library, check out our blogpost.

Abstract

JA3 is a method for fingerprinting TLS clients using options in the TLS ClientHello packet like SSL version and available client extensions. At its core, this method of detecting malicious traffic is marginally better than the User-Agent header in HTTP since the client is in control of the ClientHello packet. Currently, there is no tooling available to easily craft ClientHello packets, so the JA3 hash is a great detection mechanism. A team of two members from CU Cyber have created a Go library that makes it easy to mock JA3 signatures.

Documentation

Index

• Variables
• func NewTransport(ja3 string) (*http.Transport, error)
• func NewTransportWithConfig(ja3 string, config *tls.Config) (*http.Transport, error)
• type Browser
• type ErrExtensionNotExist
  • func (e ErrExtensionNotExist) Error() string
• type JA3Client
  • func New(b Browser) (*JA3Client, error)
  • func NewWithString(ja3 string) (*JA3Client, error)
  • func (c *JA3Client) Do(req *http.Request) (*http.Response, error)
  • func (c *JA3Client) Get(targetURL string) (*http.Response, error)
  • func (c *JA3Client) Head(url string) (resp *http.Response, err error)
  • func (c *JA3Client) Post(url, contentType string, body io.Reader) (*http.Response, error)
  • func (c *JA3Client) PostForm(url string, data url.Values) (resp *http.Response, err error)

Examples

• New
• NewTransport
• NewTransportWithConfig
• NewWithString

Variables

var ChromeAuto = Browser{
	JA3:       "769,47–53–5–10–49161–49162–49171–49172–50–56–19–4,0–10–11,23–24–25,0",
	UserAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36",
}

ChromeAuto mocks Chrome 78

var SafariAuto = Browser{
	JA3:       "771,4865-4866-4867-49196-49195-49188-49187-49162-49161-52393-49200-49199-49192-49191-49172-49171-52392-157-156-61-60-53-47-49160-49170-10,65281-0-23-13-5-18-16-11-51-45-43-10-21,29-23-24-25,0",
	UserAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 13_1_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.1 Mobile/15E148 Safari/604.1",
}

SafariAuto mocks Safari 604.1

Functions

func NewTransport

func NewTransport(ja3 string) (*http.Transport, error)

NewTransport creates an http.Transport which mocks the given JA3 signature when HTTPS is used

Example

tr, _ := NewTransport("771-61-60-53,0-23-15,29,23,24,0")
client := &http.Client{Transport: tr}
client.Get("https://ja3er.com/json")

func NewTransportWithConfig

func NewTransportWithConfig(ja3 string, config *tls.Config) (*http.Transport, error)

NewTransportWithConfig creates an http.Transport object given a utls.Config

Example

// Must import the `github.com/refraction-networking/utls` package to create the Config object.
config := &tls.Config{
	InsecureSkipVerify: true,
}
// Pass the config object to NewTransportWithConfig
tr, _ := NewTransportWithConfig("771-61-60-53,0-23-15,29,23,24,0", config)
client := &http.Client{Transport: tr}
client.Get("https://ja3er.com/json")

Types

type Browser

type Browser struct {
	JA3       string
	UserAgent string
}

Browser represents a browser JA3 and User-Agent string

type ErrExtensionNotExist

type ErrExtensionNotExist string

ErrExtensionNotExist is returned when an extension is not supported by the library

func (ErrExtensionNotExist) Error

func (e ErrExtensionNotExist) Error() string

Error is the error value which contains the extension that does not exist

type JA3Client

type JA3Client struct {
	*http.Client

	Config  *tls.Config
	Browser Browser
}

JA3Client contains is similar to http.Client

func New

func New(b Browser) (*JA3Client, error)

New creates a JA3Client based on a Browser struct

Example

client, _ := New(SafariAuto)
client.Get("https://ja3er.com/json")

func NewWithString

func NewWithString(ja3 string) (*JA3Client, error)

NewWithString creates a JA3 client with the specified JA3 string

Example

client, _ := NewWithString("771,4865-4866-4867-49196-49195-49188-49187-49162-49161-52393-49200-49199-49192-49191-49172-49171-52392-157-156-61-60-53-47-49160-49170-10,65281-0-23-13-5-18-16-11-51-45-43-10-21,29-23-24-25,0")
client.Get("https://ja3er.com/json")

func (*JA3Client) Do

func (c *JA3Client) Do(req *http.Request) (*http.Response, error)

Do sends an HTTP request and returns an HTTP response, following policy (such as redirects, cookies, auth) as configured on the client.

func (*JA3Client) Get

func (c *JA3Client) Get(targetURL string) (*http.Response, error)

Get issues a GET to the specified URL.

func (*JA3Client) Head

func (c *JA3Client) Head(url string) (resp *http.Response, err error)

Head issues a HEAD to the specified URL.

func (*JA3Client) Post

func (c *JA3Client) Post(url, contentType string, body io.Reader) (*http.Response, error)

Post issues a POST to the specified URL.

func (*JA3Client) PostForm

func (c *JA3Client) PostForm(url string, data url.Values) (resp *http.Response, err error)

PostForm issues a POST to the specified URL, with data's keys and values URL-encoded as the request body.