Man Page on Windows

[thecliguy]

I'm contemplating whether it would be possible make the man page available in Windows.

This is not a complete solution, these are just my initial thoughts exploring what would be required and how we might go about doing it... Any thoughts, feedback or suggestions would be welcome...

Converting the man page to a readable format for the Windows console

Since Windows doesn't have a manual reader, the man page would need to be converted to a format that can be rendered in the Windows console. This would have to be performed as part of the build process when there's a new release.

One option would be to simply convert it to plain text output. This conversion can be achieved as follows:

MANWIDTH=80 man ./ssh-audit.1 > ssh_audit_windows_man.txt

In Windows 10, the console is capable of interpreting ANSI escape sequences (also known as VT escape sequences). So another option would be to convert the man page to ANSI escape sequence formatted output, this would preserve any typographical emphasis that's present in the original man page, such as bold and underlined text. This conversion can be achieved as follows:

# * man outputs a backspace-overwrite sequence rather than an ANSI escape 
#   sequence.
# * 'MAN_KEEP_FORMATTING' preserves the backspace-overwrite sequence when 
#   redirected to a file or a pipe.
# * The 'ul' command converts the backspace-overwrite sequence to an ANSI escape 
#   sequence.

MANWIDTH=80 MAN_KEEP_FORMATTING=1 man ./ssh-audit.1 | ul > ssh_audit_windows_man.txt

Example of an ANSI escape sequence formatted man page on Windows 10

import os
os.system("color")

f = open('c:\\bitbucket\\ssh_audit_windows_man.txt', encoding="utf-8")
file_contents = f.read()
print (file_contents)
f.close()

Displaying the man page

Displaying the man page could perhaps be invoked using a command line parameter such as:

ssh-audit.exe --manual

Packaging the converted man page

Currently the Windows package is a standalone executable with no external dependencies. Ideally any solution that's adopted would preserve this.

Does anyone know of a way that the man page (in its converted format) could be embedded into the ssh-audit executable without having to ship an external text file?

[WSLUser]

Well ssh has a man page so I'd suggest looking there. Cygwin ssh would likely be your best bet.

[jtesta]

Does anyone know of a way that the man page (in its converted format) could be embedded into the ssh-audit executable without having to ship an external text file?

Not offhand. But PyInstaller's documentation should describe how to do this.

I'd be happy to this feature in, if you were interested in working on it.

[thecliguy]

@jtesta Let's say we do find a way to ship the man page (in its converted format) within the ssh-audit executable...

You'd need to add some steps to your Windows build process to produce the ANSI escape sequence formatted version of the man page (as described above). Are you OK with this?

I simply cannot find a way to easily render man pages on Windows in their native format. There's probably some library that exists for this purpose but I am opposed to adding any third party libraries into a project unless absolutely essential.

[jtesta]

You'd need to add some steps to your Windows build process to produce the ANSI escape sequence formatted version of the man page (as described above). Are you OK with this?

Yep. Every time the ssh-audit.1 file is updated, I could run a update_windows_man_page.sh script to create ssh-audit-windows-man-page.txt with the escape sequences preserved in it.

There's probably some library that exists for this purpose but I am opposed to adding any third party libraries into a project unless absolutely essential.

One of the original design goals of ssh-audit was to run with no external dependencies. The Windows build is a special case, however. Before PyInstaller is run, dependencies can be installed with pip. However, I'm pretty sure that wouldn't be needed. Colors can be enabled with the SetConsoleMode() Win32 API call (for an example, see https://github.com/rbsec/sslscan/blob/1530435c4eb7de0bc4eb47eda481497bf61b4d63/sslscan.c#L3654). After that, ANSI escape sequences work just fine (see https://github.com/rbsec/sslscan/blob/1530435c4eb7de0bc4eb47eda481497bf61b4d63/sslscan.h#L99).

I don't know off-hand how to call SetConsoleMode() from Python code, however...

[thecliguy]

What if instead of update_windows_man_page.sh producing a text file, it produced a python file, where it populates a string with the ANSI escape sequence formatted version of the man page?

WINDOWS_MAN_PAGE = '<ANSI Escape Sequence Formatted Value>'

Could ssh-audit then reference WINDOWS_MAN_PAGE as a variable so we don't have to package the man page as a text file?

[jtesta]

On Wed, 2021-01-20 at 14:58 -0800, thecliguy wrote: What if instead of update_windows_man_page.sh producing a text file, it produced a python file, where it populates a string with the ANSI escape sequence formatted version of the man page? WINDOWS_MAN_PAGE = '<ANSI Escape Sequence Formatted Value>' Could ssh-audit then reference WINDOWS_MAN_PAGE as a variable so we don't have to package the man page as a text file?

I was thinking that, actually. Then the code can do something like: ``` if sys.platform == "win32": import windows_man_page do_terminal_color_setup() # Somehow... print(WINDOWS_MAN_PAGE) ``` Two concerns about the above strategy: 1.) PyInstaller might not automatically package windows_man_page.py; it might need to be explicitly told (somehow), and 2.) pylint and/or flake8 might not like conditional imports.

…

-- Joseph S. Testa II Founder & Principal Security Consultant Positron Security

[thecliguy]

Here's another way we could approach it that avoids both of those potential problems...

Add WINDOWS_MAN_PAGE = '' to globals.py.

When performing a windows build, run update_windows_man_page.sh, it will perform a find and replace against globals.py, populating WINDOWS_MAN_PAGE with the ANSI escape sequence formatted version of the man page.

When a user invokes ssh-audit --manual, if WINDOWS_MAN_PAGE is not an empty string then print it to the console.

What do you think?

[jtesta]

What do you think?

Perfect!

[thecliguy]

I am making an assumption that PyInstaller automatically packages globals.py. Is that correct?

[jtesta]

I am making an assumption that PyInstaller automatically packages globals.py. Is that correct?

Yep.

[thecliguy]

@jtesta

I've written a function to:

• Determine if Windows supports ANSI escape sequences (support was first added in Windows 10 version 1511).
• If ANSI is supported then print the manual text, else strip the ANSI escape sequences and print a plain text version of the manual.

The function is invoked using the --manual or -m parameters.

I've a couple of implementation related questions for you...

1. Since this function is intended for use on Windows only, I think it makes sense to suppress its usage on other platforms. Are you happy doing this as follows in process_commandline?

        sopts = 'h1246M:p:P:jbcnvl:t:T:L'
        lopts = ['help', 'ssh1', 'ssh2', 'ipv4', 'ipv6', 'make-policy=', 'port=', 'policy=', 'json', 'batch', 'client-audit', 'no-colors', 'verbose', 'level=', 'timeout=', 'targets=', 'list-policies', 'lookup=']

        # The manual options are intended for use on Windows only.
        # Users of other operating systems should read the man page.
        if sys.platform == 'win32':
            sopts += 'm'
            lopts.append('manual')

2. Do you want to hide -m and --manual in usage on non-Windows platforms or just make its purpose clear by including Windows only in the explanation text, EG: -m, --manual print the man page (Windows only)?

[jtesta]

Do you want to hide -m and --manual in usage on non-Windows platforms or just make its purpose clear by including Windows only in the explanation text, EG: -m, --manual print the man page (Windows only)?

Perhaps `usage()` should explicitly tell the user that -m/--manual is for Windows only. And if it's used on a non-Windows OS, we print an error that it's not supported on this platform (I think this should answer your first question too).

[thecliguy]

@jtesta Thank you, that makes sense. I'll proceed on that basis.

In PACKAGING it says that the Windows package is built against Python 3.7.x. I see that PyInstaller (4.2 stable) now supports up to Python 3.9, see downloads. Do you want to continue building against Python 3.7.x or move to 3.9.x? Should I open a new issue for this?

[jtesta]

Do you want to continue building against Python 3.7.x or move to 3.9.x?

I'll switch to Python 3.9 for Windows builds, then.

Should I open a new PR for this?

To update PACKAGING? That wouldn't be necessary. I'll update it myself with tweaks after each time I package a new release.

[thecliguy]

@jtesta PR submitted, see #93.