diff --git a/Usage-Documentation.md b/Usage-Documentation.md new file mode 100644 index 0000000..c362574 --- /dev/null +++ b/Usage-Documentation.md @@ -0,0 +1,104 @@ +Usage +The normal use case is probably just testssl.sh , see first picture right hand above (a deliberately bad configuration). + +Starting testssl.sh with no params will give you a general idea how to use it: +userid@somehost:~ % testssl.sh + +testssl.sh + + -h, --help what you're looking at + -b, --banner displays banner + version of testssl.sh + -v, --version same as previous + -V, --local pretty print all local ciphers + -V, --local which local ciphers with are available? + (if pattern not a number: word match) + +testssl.sh URI ("testssl.sh URI" does everything except -E) + + -e, --each-cipher checks each local cipher remotely + -E, --cipher-per-proto checks those per protocol + -f, --ciphers checks common cipher suites + -p, --protocols checks TLS/SSL protocols (including SPDY/HTTP2) + -y, --spdy, --npn checks for SPDY/NPN + -Y, --http2, --alpn checks for HTTP2/ALPN + -S, --server-defaults displays the server's default picks and certificate info + -P, --server-preference displays the server's picks: protocol+cipher + -x, --single-cipher tests matched of ciphers + (if not a number: word match) + -c, --client-simulation test client simulations, see which client negotiates with cipher and protocol + -H, --header, --headers tests HSTS, HPKP, server/app banner, security headers, cookie, reverse proxy, IPv4 address + + -U, --vulnerable tests all vulnerabilities + -B, --heartbleed tests for heartbleed vulnerability + -I, --ccs, --ccs-injection tests for CCS injection vulnerability + -R, --renegotiation tests for renegotiation vulnerabilities + -C, --compression, --crime tests for CRIME vulnerability + -T, --breach tests for BREACH vulnerability + -O, --poodle tests for POODLE (SSL) vulnerability + -Z, --tls-fallback checks TLS_FALLBACK_SCSV mitigation + -F, --freak tests for FREAK vulnerability + -A, --beast tests for BEAST vulnerability + -J, --logjam tests for LOGJAM vulnerability + -D, --drown tests for DROWN vulnerability + -s, --pfs, --fs, --nsa checks (perfect) forward secrecy settings + -4, --rc4, --appelbaum which RC4 ciphers are being offered? + +special invocations: + -t, --starttls does a default run against a STARTTLS enabled + --xmpphost for STARTTLS enabled XMPP it supplies the XML stream to-'' domain -- sometimes needed + --mx tests MX records from high to low priority (STARTTLS, port 25) + --ip a) tests the supplied v4 or v6 address instead of resolving host(s) in URI + b) arg "one" means: just test the first DNS returns (useful for multiple IPs) + --file mass testing option: Reads command lines from , one line per instance. + Comments via # allowed, EOF signals end of . Implicitly turns on "--warnings batch" + +partly mandatory parameters: + URI host|host:port|URL|URL:port (port 443 is assumed unless otherwise specified) + pattern an ignore case word pattern of cipher hexcode or any other string in the name, kx or bits + protocol is one of the STARTTLS protocols ftp,smtp,pop3,imap,xmpp,telnet,ldap + (for the latter two you need e.g. the supplied openssl) + +tuning options (can also be preset via environment variables): + --bugs enables the "-bugs" option of s_client, needed e.g. for some buggy F5s + --assume-http if protocol check fails it assumes HTTP protocol and enforces HTTP checks + --ssl-native fallback to checks with OpenSSL where sockets are normally used + --openssl use this openssl binary (default: look in $PATH, $RUN_DIR of testssl.sh) + --proxy : connect via the specified HTTP proxy + -6 use also IPv6. Works only with supporting OpenSSL version and IPv6 connectivity + --sneaky leave less traces in target logs: user agent, referer + +output options (can also be preset via environment variables): + --warnings "batch" doesn't wait for keypress, "off" or "false" skips connection warning + --quiet don't output the banner. By doing this you acknowledge usage terms normally appearing in the banner + --wide wide output for tests like RC4, BEAST. PFS also with hexcode, kx, strength, RFC name + --show-each for wide outputs: display all ciphers tested -- not only succeeded ones + --mapping don't display the RFC Cipher Suite Name + --color <0|1|2> 0: no escape or other codes, 1: b/w escape codes, 2: color (default) + --colorblind swap green and blue in the output + --debug <0-6> 1: screen output normal but keeps debug output in /tmp/. 2-6: see "grep -A 5 '^DEBUG=' testssl.sh" + +file output options (can also be preset via environment variables): + --log, --logging logs stdout to in current working directory + --logfile logs stdout to if file is a dir or to specified log file + --json additional output of findings to JSON file in cwd + --jsonfile additional output to JSON and output JSON to the specified file + --csv additional output of findings to CSV file in cwd + --csvfile set output to CSV and output CSV to the specified file + --append if or exists rather append then overwrite + +All options requiring a value can also be called with '=' e.g. testssl.sh -t=smtp --wide --openssl=/usr/bin/openssl . + + is always the last parameter. + +Need HTML output? Just pipe through "aha" (ANSI HTML Adapter: github.com/theZiz/aha) like + + "testssl.sh | aha >output.html" + +userid@somehost:~ % + +You are free to check any port – supposed there's any SSL enabled service (TCP) listening. For the service HTTPS you can also supply a full URL. A STARTTLS check would be invoked with testssl.sh -t pop3 pop.o2online.de:110. Other examples: +testssl.sh --starttls smtp .:587 +testssl.sh --starttls ftp .:21 +testssl.sh -t xmpp .:5222 +testssl.sh -t xmpp --xmpphost .:5222 +testssl.sh --starttls imap .:143 \ No newline at end of file