Features • Installation • Usage • Running tlsx • Join Discord
A fast and configurable TLS grabber focused on TLS based **data collection and analysis**. # Features  - Fast And fully configurable TLS Connection - Multiple **Modes for TLS Connection** - Multiple **TLS probes** - **Auto TLS Fallback** for older TLS version - **Pre Handshake** TLS connection (early termination) - Customizable **Cipher / SNI / TLS** selection - **JARM/JA3** TLS Fingerprint - **TLS Misconfigurations** - **ASN,CIDR,IP,HOST,** and **URL** input - STD **IN/OUT** and **TXT/JSON** output ## Installation tlsx requires **Go 1.24** to install successfully. To install, just run the below command or download pre-compiled binary from [release page](https://github.com/projectdiscovery/tlsx/releases). ```console go install github.com/projectdiscovery/tlsx/cmd/tlsx@latest ``` ## Usage ```console tlsx -h ``` This will display help for the tool. Here are all the switches it supports. ```console TLSX is a tls data gathering and analysis toolkit. Usage: tlsx [flags] Flags: INPUT: -u, -host string[] target host to scan (-u INPUT1,INPUT2) -l, -list string target list to scan (-l INPUT_FILE) -p, -port string[] target port to connect (default 443) SCAN-MODE: -sm, -scan-mode string tls connection mode to use (ctls, ztls, openssl, auto) (default "auto") -ps, -pre-handshake enable pre-handshake tls connection (early termination) using ztls -sa, -scan-all-ips scan all ips for a host (default false) -iv, -ip-version string[] ip version to use (4, 6) (default 4) PROBES: -san display subject alternative names -cn display subject common names -so display subject organization name -tv, -tls-version display used tls version -cipher display used cipher -hash string display certificate fingerprint hashes (md5,sha1,sha256) -jarm display jarm fingerprint hash -ja3 display ja3 fingerprint hash (using ztls) -wc, -wildcard-cert display host with wildcard ssl certificate -tps, -probe-status display tls probe status -ve, -version-enum enumerate and display supported tls versions -ce, -cipher-enum enumerate and display supported cipher -ct, -cipher-type value ciphers types to enumerate. possible values: all/secure/insecure/weak (comma-separated) (default all) -ch, -client-hello include client hello in json output (ztls mode only) -sh, -server-hello include server hello in json output (ztls mode only) -se, -serial display certificate serial number MISCONFIGURATIONS: -ex, -expired display host with host expired certificate -ss, -self-signed display host with self-signed certificate -mm, -mismatched display host with mismatched certificate -re, -revoked display host with revoked certificate -un, -untrusted display host with untrusted certificate CONFIGURATIONS: -config string path to the tlsx configuration file -r, -resolvers string[] list of resolvers to use -cc, -cacert string client certificate authority file -ci, -cipher-input string[] ciphers to use with tls connection -sni string[] tls sni hostname to use -rs, -random-sni use random sni when empty -rps, -rev-ptr-sni perform reverse PTR to retrieve SNI from IP -min-version string minimum tls version to accept (ssl30,tls10,tls11,tls12,tls13) -max-version string maximum tls version to accept (ssl30,tls10,tls11,tls12,tls13) -cert, -certificate include certificates in json output (PEM format) -tc, -tls-chain include certificates chain in json output -vc, -verify-cert enable verification of server certificate -ob, -openssl-binary string OpenSSL Binary Path -hf, -hardfail strategy to use if encountered errors while checking revocation status -proxy string socks5 proxy to use for tlsx OPTIMIZATIONS: -c, -concurrency int number of concurrent threads to process (default 300) -cec, -cipher-concurrency int cipher enum concurrency for each target (default 10) -timeout int tls connection timeout in seconds (default 5) -retry int number of retries to perform for failures (default 3) -delay string duration to wait between each connection per thread (eg: 200ms, 1s) UPDATE: -up, -update update tlsx to latest version -duc, -disable-update-check disable automatic tlsx update check OUTPUT: -o, -output string file to write output to -j, -json display output in jsonline format -dns display unique hostname from SSL certificate response -ro, -resp-only display tls response only -silent display silent output -nc, -no-color disable colors in cli output -v, -verbose display verbose output -version display project version PDCP: -pd, -dashboard upload or view output in the PDCP UI dashboard -pdu, -dashboard-upload string upload tlsx output file (JSONL format) to the PDCP UI dashboard -auth string PDCP API key for authentication -tid, -team-id string upload asset results to a specified team ID -aid, -asset-id string upload new assets to an existing asset ID -aname, -asset-name string asset group name DEBUG: -health-check, -hc run diagnostic check up ``` ## Using tlsx as library Examples of using tlsx as library are provided in the [examples](examples/) folder. ## Running tlsx ### Input for tlsx **tlsx** requires **ip** to make TLS connection and accept multiple format as listed below: ```bash AS1449 # ASN input 173.0.84.0/24 # CIDR input 93.184.216.34 # IP input example.com # DNS input example.com:443 # DNS input with port https://example.com:443 # URL input port ``` Input host can be provided using `-host / -u` flag, and multiple values can be provided using comma-separated input, similarly **file** input is supported using `-list / -l` flag. Example of comma-separated host input: ```console $ tlsx -u 93.184.216.34,example.com,example.com:443,https://example.com:443 -silent ``` Example of file based host input: ```console $ tlsx -list host_list.txt ``` **Port Input:** **tlsx** connects on port **443** by default, which can be customized using `-port / -p` flag, single or multiple ports can be specified using comma sperated input or new line delimited file containing list of ports to connect. Example of comma-separated port input: ``` $ tlsx -u hackerone.com -p 443,8443 ``` Example of file based port input: ``` $ tlsx -u hackerone.com -p port_list.txt ``` **Note:** > When input host contains port in it, for example, `8.8.8.8:443` or `hackerone.com:8443`, port specified with host will be used to make TLS connection instead of default or one provided using `-port / -p` flag. ### TLS Probe (default run) This will run the tool against the given CIDR range and returns hosts that accepts tls connection on port 443. ```console $ echo 173.0.84.0/24 | tlsx _____ _ _____ __ |_ _| | / __\ \/ / | | | |__\__ \> < |_| |____|___/_/\_\ v0.0.1 projectdiscovery.io [WRN] Use with caution. You are responsible for your actions. [WRN] Developers assume no liability and are not responsible for any misuse or damage. 173.0.84.69:443 173.0.84.67:443 173.0.84.68:443 173.0.84.66:443 173.0.84.76:443 173.0.84.70:443 173.0.84.72:443 ``` ### SAN/CN Probe TLS certificate contains DNS names under **subject alternative name** and **common name** field that can be extracted using `-san`, `-cn` flag. ```console $ echo 173.0.84.0/24 | tlsx -san -cn -silent 173.0.84.104:443 [uptycspay.paypal.com] 173.0.84.104:443 [api-3t.paypal.com] 173.0.84.104:443 [api-m.paypal.com] 173.0.84.104:443 [payflowpro.paypal.com] 173.0.84.104:443 [pointofsale-s.paypal.com] 173.0.84.104:443 [svcs.paypal.com] 173.0.84.104:443 [uptycsven.paypal.com] 173.0.84.104:443 [api-aa.paypal.com] 173.0.84.104:443 [pilot-payflowpro.paypal.com] 173.0.84.104:443 [pointofsale.paypal.com] 173.0.84.104:443 [uptycshon.paypal.com] 173.0.84.104:443 [api.paypal.com] 173.0.84.104:443 [adjvendor.paypal.com] 173.0.84.104:443 [zootapi.paypal.com] 173.0.84.104:443 [api-aa-3t.paypal.com] 173.0.84.104:443 [uptycsize.paypal.com] ``` For ease of automation, optionally `-resp-only` flag can be used to list only dns names in CLI output. ```console $ echo 173.0.84.0/24 | tlsx -san -cn -silent -resp-only api-aa-3t.paypal.com pilot-payflowpro.paypal.com pointofsale-s.paypal.com uptycshon.paypal.com a.paypal.com adjvendor.paypal.com zootapi.paypal.com api-aa.paypal.com payflowpro.paypal.com pointofsale.paypal.com uptycspay.paypal.com api-3t.paypal.com uptycsize.paypal.com api.paypal.com api-m.paypal.com svcs.paypal.com uptycsven.paypal.com uptycsven.paypal.com a.paypal.com api.paypal.com pointofsale-s.paypal.com pilot-payflowpro.paypal.com ``` **subdomains** obtained from TLS certificates can be further piped to other PD tools for further inspection, here is an example piping tls subdomains to **[dnsx](https://github.com/projectdiscovery/dnsx)** to filter passive subdomains and passing to **[httpx](https://github.com/projectdiscovery/httpx)** to list hosts running active web services. ```console $ echo 173.0.84.0/24 | tlsx -san -cn -silent -resp-only | dnsx -silent | httpx __ __ __ _ __ / /_ / /_/ /_____ | |/ / / __ \/ __/ __/ __ \| / / / / / /_/ /_/ /_/ / | /_/ /_/\__/\__/ .___/_/|_| /_/ v1.2.2 projectdiscovery.io Use with caution. You are responsible for your actions. Developers assume no liability and are not responsible for any misuse or damage. https://api-m.paypal.com https://uptycsize.paypal.com https://api.paypal.com https://uptycspay.paypal.com https://svcs.paypal.com https://adjvendor.paypal.com https://uptycshap.paypal.com https://uptycshon.paypal.com https://pilot-payflowpro.paypal.com https://slc-a-origin-pointofsale.paypal.com https://uptycsven.paypal.com https://api-aa.paypal.com https://api-aa-3t.paypal.com https://uptycsbrt.paypal.com https://payflowpro.paypal.com http://pointofsale-s.paypal.com http://slc-b-origin-pointofsale.paypal.com http://api-3t.paypal.com http://zootapi.paypal.com http://pointofsale.paypal.com ``` ### TLS / Cipher Probe ```console $ subfinder -d hackerone.com | tlsx -tls-version -cipher mta-sts.hackerone.com:443 [TLS1.3] [TLS_AES_128_GCM_SHA256] hackerone.com:443 [TLS1.3] [TLS_AES_128_GCM_SHA256] api.hackerone.com:443 [TLS1.3] [TLS_AES_128_GCM_SHA256] mta-sts.managed.hackerone.com:443 [TLS1.3] [TLS_AES_128_GCM_SHA256] mta-sts.forwarding.hackerone.com:443 [TLS1.3] [TLS_AES_128_GCM_SHA256] www.hackerone.com:443 [TLS1.3] [TLS_AES_128_GCM_SHA256] support.hackerone.com:443 [TLS1.2] [TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256] ``` # TLS Misconfiguration ### Expired / Self Signed / Mismatched / Revoked / Untrusted Certificate A list of host can be provided to tlsx to detect **expired / self-signed / mismatched / revoked / untrusted** certificates. ```console $ tlsx -l hosts.txt -expired -self-signed -mismatched -revoked -untrusted _____ _ _____ __ |_ _| | / __\ \/ / | | | |__\__ \> < |_| |____|___/_/\_\ v0.0.1 projectdiscovery.io [WRN] Use with caution. You are responsible for your actions. [WRN] Developers assume no liability and are not responsible for any misuse or damage. wrong.host.badssl.com:443 [mismatched] self-signed.badssl.com:443 [self-signed] expired.badssl.com:443 [expired] revoked.badssl.com:443 [revoked] untrusted-root.badssl.com:443 [untrusted] ``` ### [JARM](https://engineering.salesforce.com/easily-identify-malicious-servers-on-the-internet-with-jarm-e095edac525a/) TLS Fingerprint ```console $ echo hackerone.com | tlsx -jarm -silent hackerone.com:443 [29d3dd00029d29d00042d43d00041d5de67cc9954cc85372523050f20b5007] ``` ### [JA3](https://github.com/salesforce/ja3) TLS Fingerprint ```console $ echo hackerone.com | tlsx -ja3 -silent hackerone.com:443 [20c9baf81bfe96ff89722899e75d0190] ``` ### JSON Output **tlsx** does support multiple probe flags to query specific data, but all the information is always available in JSON format, for automation and post processing using `-json` output is most convenient option to use. ```console echo example.com | tlsx -json -silent | jq . ``` ```json { "timestamp": "2022-08-22T21:22:59.799053+05:30", "host": "example.com", "ip": "93.184.216.34", "port": "443", "probe_status": true, "tls_version": "tls13", "cipher": "TLS_AES_256_GCM_SHA384", "not_before": "2022-03-14T00:00:00Z", "not_after": "2023-03-14T23:59:59Z", "subject_dn": "CN=www.example.org, O=Internet Corporation for Assigned Names and Numbers, L=Los Angeles, ST=California, C=US", "subject_cn": "www.example.org", "subject_org": [ "Internet Corporation for Assigned Names and Numbers" ], "subject_an": [ "www.example.org", "example.net", "example.edu", "example.com", "example.org", "www.example.com", "www.example.edu", "www.example.net" ], "issuer_dn": "CN=DigiCert TLS RSA SHA256 2020 CA1, O=DigiCert Inc, C=US", "issuer_cn": "DigiCert TLS RSA SHA256 2020 CA1", "issuer_org": [ "DigiCert Inc" ], "fingerprint_hash": { "md5": "c5208a47259d540a6e3404dddb85af91", "sha1": "df81dfa6b61eafdffffe1a250240db5d2e6cee25", "sha256": "7f2fe8d6b18e9a47839256cd97938daa70e8515750298ddba2f3f4b8440113fc" }, "tls_connection": "ctls", "sni": "example.com" } ``` ### PDCP Dashboard Integration **tlsx** supports uploading scan results to the ProjectDiscovery Cloud Platform (PDCP) dashboard for visualization and analysis. #### Uploading Results in Real-Time Enable dashboard upload to automatically upload results as they are discovered: ```console $ tlsx -u example.com -pd -json ``` Results will be automatically uploaded to PDCP and you'll receive a dashboard URL to view them. #### Uploading an Existing File Upload a previously saved JSONL output file to PDCP: ```console $ tlsx -pdu results.jsonl -tid your-team-id -aname "My Scan" ``` #### Configuration Options - `-pd, --dashboard`: Enable real-time upload to PDCP dashboard - `-pdu, --dashboard-upload| ### Pre-Handshake (Early Termination) **tlsx** supports terminating SSL connection early which leads to faster scanning and less connection request (disconnecting after TLS `serverhello` and certificate data is gathered). For more detail, please refer to [Hunting-Certificates-And-Servers](https://github.com/erbbysam/Hunting-Certificates-And-Servers/blob/master/Hunting%20Certificates%20%26%20Servers.pdf) by [@erbbysam](https://twitter.com/erbbysam) An example of using `-pre-handshake` mode: ```console $ tlsx -u example.com -pre-handshake _____ _ _____ __ |_ _| | / __\ \/ / | | | |__\__ \> < |_| |____|___/_/\_\ v0.0.1 projectdiscovery.io [WRN] Use with caution. You are responsible for your actions. [WRN] Developers assume no liability and are not responsible for any misuse or damage. example.com:443 ``` > **Note**: > **pre-handshake** mode utilizes `ztls` (**zcrypto/tls**) which also means the support is limited till `TLS v1.2` as `TLS v1.3` is not supported by `ztls` library. |
