Adding upstream version 3.1.0.upstream/3.1.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 299 insertions, 0 deletions

diff --git a/ssh-audit.1 b/ssh-audit.1
new file mode 100644
index 0000000..df9a26d
--- /dev/null
+++ b/ssh-audit.1
@@ -0,0 +1,299 @@
+.TH SSH-AUDIT 1 "March 13, 2022"
+.SH NAME
+\fBssh-audit\fP \- SSH server & client configuration auditor
+.SH SYNOPSIS
+.B ssh-audit
+.RI [ options ] " <target_host>"
+.SH DESCRIPTION
+.PP
+\fBssh-audit\fP analyzes the configuration of SSH servers & clients, then warns the user of weak, obsolete, and/or untested cryptographic primitives.  It is very useful for hardening SSH tunnels, which by default tend to be optimized for compatibility, not security.
+.PP
+See <https://www.ssh\-audit.com/> for official hardening guides for common platforms.
+
+.SH OPTIONS
+.TP
+.B -h, \-\-help
+.br
+Print short summary of options.
+
+.TP
+.B -1, \-\-ssh1
+.br
+Only perform an audit using SSH protocol version 1.
+
+.TP
+.B -2, \-\-ssh2
+.br
+Only perform an audit using SSH protocol version 2.
+
+.TP
+.B -4, \-\-ipv4
+.br
+Prioritize the usage of IPv4.
+
+.TP
+.B -6, \-\-ipv6
+.br
+Prioritize the usage of IPv6.
+
+.TP
+.B -b, \-\-batch
+.br
+Enables grepable output.
+
+.TP
+.B -c, \-\-client\-audit
+.br
+Starts a server on port 2222 to audit client software configuration.  Use -p/--port=<port> to change port and -t/--timeout=<secs> to change listen timeout.
+
+.TP
+.B -d, \-\-debug
+.br
+Enable debug output.
+
+.TP
+.B -g, \-\-gex-test=<x[,y,...] | min1:pref1:max1[,min2:pref2:max2,...] | x-y[:step]>
+.br
+Runs a Diffie-Hellman Group Exchange modulus size test against a server.
+
+Diffie-Hellman requires the client and server to agree on a generator value and a modulus value.  In the "Group Exchange" implementation of Diffie-Hellman, the client specifies the size of the modulus in bits by providing the server with minimum, preferred and maximum values. The server then finds a group that best matches the client's request, returning the corresponding generator and modulus.  For a full explanation of this process see RFC 4419 and its successors.
+
+This test acts as a client by providing an SSH server with the size of a modulus and then obtains the size of the modulus returned by the server.
+
+Three types of syntax are supported:
+
+  1. <x[,y,...]>
+
+     A comma delimited list of modulus sizes.
+     A test is performed against each value in the list where it acts as the minimum, preferred and maximum modulus size.
+
+  2. <min:pref:max[,min:pref:max,...]>
+
+     A set of three colon delimited values denoting minimum, preferred and maximum modulus size.
+     A test is performed against each set.
+     Multiple sets can specified as a comma separated list.
+
+  3. <x-y[:step]>
+
+     A range of modulus sizes with an optional step value. Step defaults to 1 if omitted.
+     If the left value is greater than the right value, then the sequence operates from right to left.
+     A test is performed against each value in the range where it acts as the minimum, preferred and maximum modulus size.
+
+Duplicates are excluded from the return value.
+
+.TP
+.B -j, \-\-json
+.br
+Output results in JSON format.  Specify twice (-jj) to enable indent printing (useful for debugging).
+
+.TP
+.B -l, \-\-level=<info|warn|fail>
+.br
+Specify the minimum output level.  Default is info.
+
+.TP
+.B -L, \-\-list-policies
+.br
+List all official, built-in policies for common systems.  Their full names can then be passed to -P/--policy.
+
+.TP
+.B \-\-lookup=<alg1,alg2,...>
+.br
+Look up the security information of an algorithm(s) in the internal database.  Does not connect to a server.
+
+.TP
+.B -m, \-\-manual
+.br
+Print the man page (Windows only).
+
+.TP
+.B -M, \-\-make-policy=<custom_policy.txt>
+.br
+Creates a policy based on the target server.  Useful when other servers should be compared to the target server's custom configuration (i.e.: a cluster environment).  Note that the resulting policy can be edited manually.
+
+.TP
+.B -n, \-\-no-colors
+.br
+Disable color output.
+
+.TP
+.B -p, \-\-port=<port>
+.br
+The TCP port to connect to when auditing a server, or the port to listen on when auditing a client.
+
+.TP
+.B -P, \-\-policy=<"built-in policy name" | path/to/custom_policy.txt>
+.br
+Runs a policy audit against a target using the specified policy (see \fBPOLICY AUDIT\fP section for detailed description of this mode of operation).  Combine with -c/--client-audit to audit a client configuration instead of a server.  Use -L/--list-policies to list all official, built-in policies for common systems.
+
+.TP
+.B -t, \-\-timeout=<secs>
+.br
+The timeout, in seconds, for creating connections and reading data from the socket.  Default is 5.
+
+.TP
+.B -T, \-\-targets=<hosts.txt>
+.br
+A file containing a list of target hosts.  Each line must have one host, in the format of HOST[:PORT].  Use --threads to control concurrent scans.
+
+.TP
+.B     \-\-threads=<threads>
+.br
+The number of threads to use when scanning multiple targets (with -T/--targets).  Default is 32.
+
+.TP
+.B -v, \-\-verbose
+.br
+Enable verbose output.
+
+
+.SH STANDARD AUDIT
+.PP
+By default, \fBssh-audit\fP performs a standard audit.  That is, it enumerates all host key types, key exchanges, ciphers, MACs, and other information, then color-codes them in output to the user.  Cryptographic primitives with potential issues are displayed in yellow; primitives with serious flaws are displayed in red.
+
+
+.SH POLICY AUDIT
+.PP
+When the -P/--policy option is used, \fBssh-audit\fP performs a policy audit.  The target's host key types, key exchanges, ciphers, MACs, and other information is compared to a set of expected values defined in the specified policy file.  If everything matches, only a short message stating a passing result is reported.  Otherwise, the field(s) that did not match are reported.
+
+.PP
+Policy auditing is helpful for ensuring a group of related servers are properly hardened to an exact specification.
+
+.PP
+The set of official built-in policies can be viewed with -L/--list-policies.  Multiple servers can be audited with -T/--targets=<servers.txt>.  Custom policies can be made from an ideal target server with -M/--make-policy=<custom_policy.txt>.
+
+
+.SH EXAMPLES
+.LP
+Basic server auditing:
+.RS
+.nf
+ssh-audit localhost
+ssh-audit 127.0.0.1
+ssh-audit 127.0.0.1:222
+ssh-audit ::1
+ssh-audit [::1]:222
+.fi
+.RE
+
+.LP
+To run a standard audit against many servers (place targets into servers.txt, one on each line in the format of HOST[:PORT]):
+.RS
+.nf
+ssh-audit -T servers.txt
+.fi
+.RE
+
+.LP
+To audit a client configuration (listens on port 2222 by default; connect using "ssh -p 2222 anything@localhost"):
+.RS
+.nf
+ssh-audit -c
+.fi
+.RE
+
+.LP
+To audit a client configuration, with a listener on port 4567:
+.RS
+.nf
+ssh-audit -c -p 4567
+.fi
+.RE
+
+.LP
+To list all official built-in policies (hint: use their full names with -P/--policy):
+.RS
+.nf
+ssh-audit -L
+.fi
+.RE
+
+.LP
+To run a built-in policy audit against a server (hint: use -L to see list of built-in policies):
+.RS
+.nf
+ssh-audit -P "Hardened Ubuntu Server 20.04 LTS (version 1)" targetserver
+.fi
+.RE
+
+
+.LP
+To run a custom policy audit against a server (hint: use -M/--make-policy to create a custom policy file):
+.RS
+.nf
+ssh-audit -P path/to/server_policy.txt targetserver
+.fi
+.RE
+
+.LP
+To run a policy audit against a client:
+.RS
+.nf
+ssh-audit -c -P ["policy name" | path/to/client_policy.txt]
+.fi
+.RE
+
+.LP
+To run a policy audit against many servers:
+.RS
+.nf
+ssh-audit -T servers.txt -P ["policy name" | path/to/server_policy.txt]
+.fi
+.RE
+
+.LP
+To create a policy based on a target server (which can be manually edited; see official built-in policies for syntax examples):
+.RS
+.nf
+ssh-audit -M new_policy.txt targetserver
+.fi
+.RE
+
+.LP
+To run a Diffie-Hellman Group Exchange modulus size test using the values 2000 bits, 3000 bits, 4000 bits and 5000 bits:
+.RS
+.nf
+ssh-audit targetserver --gex-test=2000,3000,4000,5000
+.fi
+.RE
+
+.LP
+To run a Diffie-Hellman Group Exchange modulus size test where 2048 bits is the minimum, 3072 bits is the preferred and 5000 bits is the maximum:
+.RS
+.nf
+ssh-audit targetserver --gex-test=2048:3072:5000
+.fi
+.RE
+
+.LP
+To run a Diffie-Hellman Group Exchange modulus size test from 0 bits to 5120 bits in increments of 1024 bits:
+.RS
+.nf
+ssh-audit targetserver --gex-test=0-5120:1024
+.fi
+.RE
+
+.SH RETURN VALUES
+When a successful connection is made and all algorithms are rated as "good", \fBssh-audit\fP returns 0.  Other possible return values are:
+
+.RS
+.nf
+1 = connection error
+2 = at least one algorithm warning was found
+3 = at least one algorithm failure was found
+<any other non-zero value> = unknown error
+.fi
+.RE
+
+.SH SSH HARDENING GUIDES
+Hardening guides for common platforms can be found at: <https://www.ssh\-audit.com/>
+
+.SH BUG REPORTS
+Please file bug reports as a Github Issue at: <https://github.com/jtesta/ssh\-audit/issues>
+
+.SH AUTHOR
+.LP
+\fBssh-audit\fP was originally written by Andris Raugulis <moo@arthepsy.eu>, and maintained from 2015 to 2017.
+.br
+.LP
+Maintainership was assumed and development was resumed in 2017 by Joe Testa <jtesta@positronsecurity.com>.