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

• Constants
• Variables
• func NewTransport(ja3 string) (*http.Transport, error)
• func NewTransportWithConfig(ja3 string, config *tls.Config) (*http.Transport, error)
• func SplitJa3Field(field string) []string
• 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)

Constants

const (
	Ja3FieldCount  = 5
	DelimiterDash  = "-"
	DelimiterComma = ","
)

JA3 gathers the decimal values of the bytes for the following fields in the Client Hello packet; SSL Version, Accepted Ciphers, List of Extensions, Elliptic Curves, and Elliptic Curve Formats. It then concatenates those values together in order, using a "," to delimit each field and a "-" to delimit each value in each field. The field order is as follows: SSLVersion,Cipher,SSLExtension,EllipticCurve,EllipticCurvePointFormat If there are no SSL Extensions in the Client Hello, the fields are left empty. Example: 769,4-5-10-9-100-98-3-6-19-18-99,,,

More information: https://github.com/salesforce/ja3#how-it-works

Variables

var BadJA3 = Browser{
	JA3:       "771,4865-4867-4866-49196-49162-49195-52393-49161-49200-49172-49199-52392-49171-157-53-156-47-10,0-23-65281-10-11-35-16-5-51-43-13-45-28",
	UserAgent: "curl/xx",
}

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 ChromeVersion103 = Browser{
	JA3:       "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27,29-23-24,1",
	UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36",
}

var Ja3WithPadding = Browser{
	JA3:       "771,4865-4866-4867-49195-49196-52393-49199-49200-53,0-51-43-13-45-10-11-21,29-23-30-25-24,0-1-2",
	UserAgent: "with padding",
}

Extension must contain 10 and 11 if group and format exist.

var Ja3WithoutExtension = Browser{
	JA3:       "771,4865-4866-4867-49195-49196-52393-49199-49200-52392-49171-49172-156-157-47-53,,,",
	UserAgent: "without Extensions",
}

var Ja3WithoutGroupAndFormat = Browser{
	JA3:       "771,4865-4866-4867-49195-49196-52393-49199-49200-53,0-51-43-13-45,29-23-30-25-24,0-1-2",
	UserAgent: "without group and format",
}

Extension must contain 10 and 11 if group and format exist. So if extension 10 and 11 are not setting, group and format are meaningless.

var Ja3WithoutGroupAndFormatWrong = Browser{
	JA3:       "771,4865-4866-4867-49195-49196-52393-49199-49200-53,0-51-43-13-45-10-11,,",
	UserAgent: "without padding",
}

var Ja3WithoutPadding = Browser{
	JA3:       "771,4865-4866-4867-49195-49196-52393-49199-49200-53,0-51-43-13-45-10-11,29-23-30-25-24,0-1-2",
	UserAgent: "without padding",
}

Extension must contain 10 and 11 if group and format exist.

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

func NewTransportWithConfig

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

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

func SplitJa3Field

func SplitJa3Field(field string) []string

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

func NewWithString

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

NewWithString creates a JA3 client with the specified JA3 string

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.