go-iovation

README

go-iovation

Go library and CLI for generating iovation device fingerprint blackbox tokens with TLS fingerprint impersonation.

Table of Contents

• Features
• Install
• Quickstart
• CLI
• How It Works
• Documentation
• Testing
• License

Features

• Fetches and parses iovation Snare configuration scripts
• Assembles browser fingerprint signals with randomized device defaults
• Chrome TLS fingerprint impersonation via surf
• DES-ECB encrypted blackbox token output
• Pluggable structured logging interface
• CLI for standalone usage

Install

Library:

go get github.com/arisu-archive/go-iovation

CLI:

go install github.com/arisu-archive/go-iovation/cmd/iovation@latest

Requires Go 1.26 or later.

Quickstart

client := iovation.New(nil, nil)

scriptURL, _ := url.Parse("https://example.com/snare.js")
config, _ := client.Parse(context.Background(), *scriptURL)

var key [8]byte
decoded, _ := hex.DecodeString("aabbccddeeaabbcc")
copy(key[:], decoded)

generator, _ := iovation.NewGenerator(config, key, nil)
blackbox, _ := generator.Generate("https://example.com/login")

fmt.Println(blackbox) // 0400<base64 encoded DES ciphertext>

CLI

iovation generate \
  --url https://example.com/snare.js \
  --target https://example.com/login \
  --key aabbccddeeaabbcc

Flag	Required	Default	Description
--url	Yes	--	Snare script URL
--target	Yes	--	Target URL embedded in blackbox
--key	Yes	--	DES key as 16-character hex string
--timeout	No	30	Request timeout in seconds
--verbose, -v	No	false	Enable debug logging

How It Works

1. Fetch -- Client.Parse fetches the remote Snare script using a Chrome-impersonated TLS client and captures Sec-CH-UA-* request headers
2. Extract -- Regex parser pulls signal key-value pairs from the script (base64, percent-encoded, and literal values)
3. Assemble -- NewGenerator merges server signals with randomized device defaults (screen resolution, GPU, audio context, timing) and applies browser/OS detection from the user-agent
4. Encrypt -- Generator.Generate packs signals into binary format, zero-pads to block alignment, encrypts with DES-ECB, and outputs a 0400-prefixed base64 token

Documentation

See the Go Reference for the full API.

Testing

Tests use Ginkgo v2 and Gomega.

go test ./...

License

MIT