What is a TLS fingerprint (JA3 / JA4); how does TR7 use it in bot detection?

Short answer

A TLS fingerprint is an identity derived from the ClientHello (TLS version, cipher suites, extensions and their order) that a client sends in its TLS handshake; JA3 turns it into an MD5 hash, and JA4 into a readable, sectioned string. While the User-Agent header can be changed easily, the fingerprint is hard to imitate because it reflects the TLS library that the client uses. In TR7, the Network Fingerprinting factor group of Bot Protection adds the fingerprint to the bot score: Malware Ja3 flags known malware JA3s, Bot Ja4 flags the JA4s of known bots and automation tools, and Ja4 Tool Impersonation flags a client that claims to be a browser but carries a library fingerprint; Tls Ua Mismatch in the Cross-Signal Consistency group compares the families of the fingerprint and of the User-Agent. A known client is exempted in the Bot Protection Whitelist Entries list with a JA4 fingerprint or JA4 family row; the values can be written to logs or headers with the %JA3_FINGERPRINT and %JA4_FINGERPRINT Smart Variables.

Where It Is Used in TR7

Where	Field / label	What for
Left Monitor Panel → Bot/DDoS Protected vServices → vService → Bot/DDoS Management → Bot Protection → Factors	Network Fingerprinting group: Malware Ja3, Bot Ja4 and, only on HTTP vServices, Ja4 Tool Impersonation; Cross-Signal Consistency group: Tls Ua Mismatch, only on HTTP vServices	Turning on and off the factors that rely on the fingerprint
Bot Protection → Edit	Bot Protection Whitelist Entries → row type JA4 fingerprint or JA4 family	Exempting a known client or client family from bot protection
vService → Bot/DDoS Event Logs	TLS Fingerprint (JA4), Identity Consistency (TLS & UA), JA4 (raw) on the Bot tab of the record preview; on the filter strip, the Identity Consistency (TLS & UA) group and the TLS Fingerprint (JA4) group, which can be added to the strip later	Seeing the client family resolved from the fingerprint and its consistency with the User-Agent
Fields that select a Smart Variable (log format, adding a header…)	%JA3_FINGERPRINT, %JA4_FINGERPRINT (General TLS information)	Writing the fingerprint to the log or to the header going to the Backend Service

• The general structure and the classes of the bot score: What is a bot score; what do the Clean, Suspicious, Bot and Bad Bot classes mean?
• The fingerprint is read on connections whose TLS terminates on TR7; the factors of the Network Fingerprinting group other than Ja4 Tool Impersonation work on L7 TCP vServices as well (factors on L7 TCP vServices).

Common Misconceptions

• "Making the User-Agent look like a browser hides the bot." The fingerprint reveals the TLS library used; when the browser claim and the library fingerprint contradict each other, Ja4 Tool Impersonation is triggered.
• "The same fingerprint indicates a single client." The fingerprint identifies the software, not the person; all the clients that use the same browser version can carry the same fingerprint. For this reason, an exemption by fingerprint can cover an entire client family.
• "Tls Ua Mismatch is a definite sign of a bot." A real browser behind a corporate intermediate server that performs TLS inspection carries the fingerprint of the intermediate server; for this reason, the weight of the factor is moderate.

How it is done in the documentation

• Factors · Network Fingerprinting
• Factors · Cross-Signal Consistency
• Bot Protection Edit · Bot Protection Whitelist Entries
• Event Logs · Bot Tab
• Variables · The general TLS information

Related questions

• What is a bot score; what do the Clean, Suspicious, Bot and Bad Bot classes mean?
• What is a bot; how is the difference between a good bot and a bad bot handled in TR7?
• How do I detect bots; can I allow good bots (Googlebot etc.) and block bad ones?