The built-in man page (, ) is now available on Docker, PyPI, and Snap builds, in addition to the Windows build. (#231)

Makefile.docker

@@ -4,6 +4,7 @@ ifeq ($(VERSION),)
 endif
 
 all:
+	./add_builtin_man_page.sh
 	docker buildx create --name multiarch --use || exit 0
 	docker buildx build \
 		--platform linux/amd64,linux/arm64,linux/arm/v7 \

Makefile.pypi

@@ -1,4 +1,5 @@
 all:
+	./add_builtin_man_page.sh
 	rm -rf /tmp/pypi_upload
 	virtualenv -p /usr/bin/python3 /tmp/pypi_upload/
 	cp -R src /tmp/pypi_upload/

README.md

@@ -182,6 +182,7 @@ For convenience, a web front-end on top of the command-line tool is available at
  - Expanded filter of CBC ciphers to flag for the Terrapin vulnerability.  It now includes more rarely found ciphers.
  - Color output is disabled if the `NO_COLOR` environment variable is set (see https://no-color.org/).
  - Fixed parsing of ecdsa-sha2-nistp* CA signatures on host keys.  Additionally, they are now flagged as potentially back-doored, just as standard host keys are.
+ - The built-in man page (`-m`, `--manual`) is now available on Docker, PyPI, and Snap builds, in addition to the Windows build.
 
 ### v3.1.0 (2023-12-20)
  - Added test for the Terrapin message prefix truncation vulnerability ([CVE-2023-48795](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-48795)).

add_builtin_man_page.sh

@@ -3,7 +3,7 @@
 #
 #   The MIT License (MIT)
 #
-#   Copyright (C) 2021 Joe Testa (jtesta@positronsecurity.com)
+#   Copyright (C) 2021-2024 Joe Testa (jtesta@positronsecurity.com)
 #   Copyright (C) 2021 Adam Russell (<adam[at]thecliguy[dot]co[dot]uk>)
 #
 #   Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -26,22 +26,21 @@
 #
 
 ################################################################################
-# update_windows_man_page.sh
+# add_builtin_man_page.sh
 #
 # PURPOSE
-#   Since Windows lacks a manual reader it's necessary to provide an alternative
+#   Since some platforms lack a manual reader it's necessary to provide an
-#   means of reading the man page.
+#   alternative means of reading the man page.
 #
 #   This script should be run as part of the ssh-audit packaging process for
-#   Windows. It populates the 'WINDOWS_MAN_PAGE' variable in 'globals.py' with
+#   Docker, PyPI, Snap, and Windows. It populates the 'BUILTIN_MAN_PAGE'
-#   the contents of the man page. Windows users can then print the content of
+#   variable in 'globals.py' with the contents of the man page. Users can then
-#   'WINDOWS_MAN_PAGE' by invoking ssh-audit with the manual parameters
+#   see the man page with "ssh-audit [--manual|-m]".
-#   (--manual / -m).
 #
-#   Cygwin is required.
+#   Linux or Cygwin is required to run this script.
 #
 # USAGE
-#   update_windows_man_page.sh [-m <path-to-man-page>] [-g <path-to-globals.py>]
+#   add_builtin_man_page.sh [-m <path-to-man-page>] [-g <path-to-globals.py>]
 #
 ################################################################################
 
@@ -102,7 +101,7 @@ command -v sed >/dev/null 2>&1 || { echo >&2 "sed not found."; exit 1; }
 git checkout "${GLOBALS_PY}" > /dev/null 2>&1
 
 # Remove the Windows man page placeholder from 'globals.py'.
-sed -i '/^WINDOWS_MAN_PAGE/d' "${GLOBALS_PY}"
+sed -i '/^BUILTIN_MAN_PAGE/d' "${GLOBALS_PY}"
 
 echo "Processing man page at ${MAN_PAGE} and placing output into ${GLOBALS_PY}..."
 
@@ -116,7 +115,7 @@ echo "Processing man page at ${MAN_PAGE} and placing output into ${GLOBALS_PY}..
 #     escape sequence. Not required under Cygwin because man outputs ANSI escape
 #     codes automatically.
 
-echo WINDOWS_MAN_PAGE = '"""' >> "${GLOBALS_PY}"
+echo BUILTIN_MAN_PAGE = '"""' >> "${GLOBALS_PY}"
 
 if [[ "${PLATFORM}" == CYGWIN* ]]; then
     MANWIDTH=80 MAN_KEEP_FORMATTING=1 man "${MAN_PAGE}" | sed $'s/\u2010/-/g' >> "${GLOBALS_PY}"

build_snap.sh

@@ -3,7 +3,7 @@
 #
 #   The MIT License (MIT)
 #
-#   Copyright (C) 2021 Joe Testa (jtesta@positronsecurity.com)
+#   Copyright (C) 2021-2024 Joe Testa (jtesta@positronsecurity.com)
 #
 #   Permission is hereby granted, free of charge, to any person obtaining a copy
 #   of this software and associated documentation files (the "Software"), to deal
@@ -44,6 +44,9 @@ rm -rf parts/ prime/ snap/ stage/ build/ dist/ src/*.egg-info/ ssh-audit*.snap
 git checkout snapcraft.yaml 2> /dev/null
 git checkout src/ssh_audit/globals.py 2> /dev/null
 
+# Add the built-in manual page.
+./add_builtin_man_page.sh
+
 # Get the version from the globals.py file.
 version=$(grep VERSION src/ssh_audit/globals.py | awk 'BEGIN {FS="="} ; {print $2}' | tr -d '[:space:]')
 

build_windows_executable.sh

@@ -3,7 +3,7 @@
 #
 #   The MIT License (MIT)
 #
-#   Copyright (C) 2021 Joe Testa (jtesta@positronsecurity.com)
+#   Copyright (C) 2021-2024 Joe Testa (jtesta@positronsecurity.com)
 #
 #   Permission is hereby granted, free of charge, to any person obtaining a copy
 #   of this software and associated documentation files (the "Software"), to deal
@@ -77,7 +77,7 @@ fi
 git checkout src/ssh_audit/globals.py 2> /dev/null
 
 # Update the man page.
-./update_windows_man_page.sh
+./add_builtin_man_page.sh
 retval=$?
 if [[ ${retval} != 0 ]]; then
     echo "Failed to run ./update_windows_man_page.sh"

src/ssh_audit/globals.py

@@ -30,8 +30,8 @@ SSH_HEADER = 'SSH-{0}-OpenSSH_8.2'
 # The URL to the Github issues tracker.
 GITHUB_ISSUES_URL = 'https://github.com/jtesta/ssh-audit/issues'
 
-# The man page.  Only filled in on Windows systems.
+# The man page.  Only filled in on Docker, PyPI, Snap, and Windows builds.
-WINDOWS_MAN_PAGE = ''
+BUILTIN_MAN_PAGE = ''
 
 # True when installed from a Snap package, otherwise False.
 SNAP_PACKAGE = False

src/ssh_audit/ssh_audit.py

@@ -39,7 +39,7 @@ from typing import cast, Callable, Optional, Union, Any  # noqa: F401
 from ssh_audit.globals import SNAP_PACKAGE
 from ssh_audit.globals import SNAP_PERMISSIONS_ERROR
 from ssh_audit.globals import VERSION
-from ssh_audit.globals import WINDOWS_MAN_PAGE
+from ssh_audit.globals import BUILTIN_MAN_PAGE
 from ssh_audit.algorithm import Algorithm
 from ssh_audit.algorithms import Algorithms
 from ssh_audit.auditconf import AuditConf
@@ -1416,23 +1416,21 @@ def target_worker_thread(host: str, port: int, shared_aconf: AuditConf) -> Tuple
     return ret, string_output
 
 
-def windows_manual(out: OutputBuffer) -> int:
+def builtin_manual(out: OutputBuffer) -> int:
-    '''Prints the man page on Windows.  Returns an exitcodes.* flag.'''
+    '''Prints the man page (Docker, PyPI, Snap, and Windows builds only).  Returns an exitcodes.* flag.'''
 
-    retval = exitcodes.GOOD
 
-    if sys.platform != 'win32':
+    builtin_man_page = BUILTIN_MAN_PAGE
-        out.fail("The '-m' and '--manual' parameters are reserved for use on Windows only.\nUsers of other operating systems should read the man page.")
+    if builtin_man_page == "":
-        retval = exitcodes.FAILURE
+        out.fail("The '-m' and '--manual' parameters are reserved for use in Docker, PyPI, Snap,\nand Windows builds only.  Users of other platforms should read the system man\npage.")
-        return retval
+        return exitcodes.FAILURE
 
     # If colors are disabled, strip the ANSI color codes from the man page.
-    windows_man_page = WINDOWS_MAN_PAGE
     if not out.use_colors:
-        windows_man_page = re.sub(r'\x1b\[\d+?m', '', windows_man_page)
+        builtin_man_page = re.sub(r'\x1b\[\d+?m', '', builtin_man_page)
 
-    out.info(windows_man_page)
+    out.info(builtin_man_page)
-    return retval
+    return exitcodes.GOOD
 
 
 def get_permitted_syntax_for_gex_test() -> Dict[str, str]:
@@ -1526,7 +1524,7 @@ def main() -> int:
         # to output a plain text version of the man page.
         if (sys.platform == 'win32') and ('colorama' not in sys.modules):
             out.use_colors = False
-        retval = windows_manual(out)
+        retval = builtin_manual(out)
         out.write()
         sys.exit(retval)
 

ssh-audit.1

@@ -1,4 +1,4 @@
-.TH SSH-AUDIT 1 "January 28, 2024"
+.TH SSH-AUDIT 1 "February 16, 2024"
 .SH NAME
 \fBssh-audit\fP \- SSH server & client configuration auditor
 .SH SYNOPSIS
@@ -104,7 +104,7 @@ Look up the security information of an algorithm(s) in the internal database.  D
 .TP
 .B -m, \-\-manual
 .br
-Print the man page (Windows only).
+Print the man page (Docker, PyPI, Snap, and Windows builds only).
 
 .TP
 .B -M, \-\-make-policy=<custom_policy.txt>