Merge pull request #14 from ben-grande/stprint

Add safe terminal printing program

Author: adrelanos

.github/workflows/lint.yml

@@ -0,0 +1,49 @@
+---
+name: Lint scripts
+on:
+  push:
+    paths:
+      - usr/lib/python3/dist-packages/stdisplay/
+      - .github/workflows/lint.yml
+      - run-tests
+  pull_request:
+    paths:
+      - usr/lib/python3/dist-packages/stdisplay/
+      - .github/workflows/lint.yml
+      - run-tests
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: debian:stable
+          - image: debian:testing
+          - image: debian:unstable
+          - image: ubuntu:latest
+          - image: ubuntu:rolling
+
+    container:
+      image: ${{ matrix.image }}
+
+    steps:
+      - name: Install linters
+        run: |
+          apt-get update --error-on=any
+          apt-get dist-upgrade -y
+          apt-get install -y git python3-pytest pylint mypy black ncurses-term \
+            build-essential debhelper dh-python dh-apparmor
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - uses: actions/checkout@v4
+
+      - name: Test build
+        run: |
+          dpkg-buildpackage -b -i -us -uc
+          apt-get install -y ../helper-scripts*.deb
+      - name: Run linters
+        run: |
+          set -o xtrace
+          ./run-tests

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+.mypy_cache/
+debian/helper-scripts-tests/
+debian/helper-scripts/

debian/control

@@ -44,3 +44,10 @@ Description: Helper scripts useful for Linux Distributions
  .
  Provides the dummy-dependency script for quickly creating and installing
  dummy packages for working around package dependencies.
+
+Package: helper-scripts-tests
+Architecture: all
+Depends: helper-scripts, git, python3-pytest, pylint, mypy, black,
+ ncurses-base, ncurses-term, ${misc:Depends}
+Description: Helper scripts test packages
+ This is a dependency package for tests.

man/stdisplay.1.ronn

@@ -0,0 +1,215 @@
+stdisplay(1) -- Sanitize text to be safely printed to the terminal
+=================================================================
+
+<!--
+# Copyright (C) 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+# Copyright (C) 2025 ENCRYPTED SUPPORT LLC <adrelanos@whonix.org>
+# See the file COPYING for copying conditions.
+-->
+
+## SYNOPSIS
+
+`stprint [TEXT...]`<br>
+`stecho [TEXT...]`<br>
+`stcat [FILE...]`<br>
+`sttee [FILE...]`<br>
+`stsponge [FILE]`<br>
+
+## DESCRIPTION
+
+`stdisplay` is a Python library used to safely print text from untrusted
+sources sanitizing non-ASCII characters and dangerous ANSI escape
+sequenes, from the latter, only a strict subset of SGR (Select Graphic
+Rendition) attributes, line feeds (`\n`) and horizontal tabs (`\t`) are
+allowed).
+
+The following tests are done in order to verify if SGR should be enabled
+and how large it's set should be:
+
+1.  If the environment variable `$NO_COLOR` is set to a non-empty value,
+    SGR is disabled.
+2.  If the environment variable `$COLORTERM` is set to `truecolor`,
+    24-bit SGR is enabled.
+3.  If none of the above matches, the terminal referenced by the
+    environment variable `$TERM` is queried for its `colors` capability,
+    which returns how many colors the terminal supports.
+
+Tools based on this library have no option parameters, everything is
+treated either as text or file, depending on the tool used, therefore,
+`--` is interpreted as text and not end of options.
+
+Each tool behaves as if their shell utility counterpart was used without
+any options:
+
+| Tool     | Sanitizer |
+| -------- | --------- |
+| strint   | printf    |
+| stecho   | echo      |
+| stcat    | cat       |
+| sttee    | tee       |
+| stsponge | sponge    |
+
+## RETURN VALUES
+
+* `0` Successfully printed text.
+* Any other return value is an error.
+
+## EXAMPLE: SGR CONTROL
+
+Enable 24-bit SGR if the terminfo database is outdated:
+
+<code>
+COLORTERM=truecolor stprint "$(printf '%b' "\033[38;2;0;0;255mSome color\033[m")"<br>
+</code>
+
+Disable SGR:
+
+<code>
+NO_COLOR=1 stprint "$(printf '%b' "\033[31mNo color\033[m")"<br>
+TERM=dumb stprint "$(printf '%b' "\033[31mNo color\033[m")"<br>
+</code>
+
+## EXAMPLE: STCAT
+
+Copy standard input to standard output:
+
+<code>
+printf '%s' "${untrusted_string}" | stcat<br>
+stcat < /untrusted/file<br>
+.<br>
+untrusted-cmd 2>&1 | stcat<br>
+# Or with Bash/Zsh syntax:<br>
+stcat &lt; &lt;(untrusted-cmd 2>&1)
+</code>
+
+Concatenate files:
+
+<code>
+stcat /untrusted/file /untrusted/log
+</code>
+
+Piping to a pager (can also be `sttee`):
+
+<code>
+data | stcat | less -R<br>
+GIT_PAGER="stcat | less -R" git log
+</code>
+
+Print a ownership restricted file with external programs:
+
+<code>
+sudo -- stcat /untrusted/log<br>
+</code>
+
+## EXAMPLE: STTEE/STSPONGE
+
+The tools `sttee` and `stsponge` have the same usage but differ when
+writing. While `sttee` always writes to standrd output as soon as
+it is read, `stsponge` only writes to standard output if no file is
+provided and the write is atomic.
+
+Copy standrd input to standard output and optionally to a file:
+
+<code>
+printf '%s' "${untrusted_string}" | sttee<br>
+printf '%s' "${untrusted_string}" | sttee /trusted/file<br>
+sttee /trusted/file < /untrusted/file</br>
+</code>
+
+Only `stsponge` can sanitize a file in-place:
+
+<code>
+stsponge /untrusted/file < /untrusted/file
+</code>
+
+## EXAMPLE: STPRINT/STECHO
+
+The tools `stprint` and `stecho` have the same usage but differ in
+formatting. While `stprint` does print text as is, `stecho` adds a space
+between each argument and a newline at the end of the string.
+
+Print a variable value is simple:
+
+<code>
+stprint "${untrusted_string}"
+</code>
+
+Note that items are joined without word-splitting (no space separation):
+
+<code>
+stprint "${untrusted_string}" "${another_untrusted_string}"
+</code>
+
+To have space separated items, simply add a space between them:
+
+<code>
+stprint "${untrusted_string} ${another_untrusted_string}"<br>
+stprint "${untrusted_string}" " ${another_untrusted_string}"
+</code>
+
+Print with heredoc to avoid quoting problems:
+
+<code>
+stprint &lt;&lt;EOF<br>
+${untrusted_string}<br>
+EOF
+</code>
+
+### EXAMPLE: STPRINT WITH VARIABLES
+
+Print a variable as is:
+
+<code>
+var="$(stprint "${untrusted_string}")"<br>
+## Or Bash/Zsh syntax:<br>
+printf -v var '%s' "$(stprint "${red}Hey${nocolor}: ${untrusted_string}")"<br>
+.<br>
+## Raw print:<br>
+printf '%s' "${var}"
+</code>
+
+Interpret wanted escapes before passing them:
+
+<code>
+red="$(printf '%b' "\033[31m")"<br>
+nocolor="$(printf '%b' "\033[m")"<br>
+## Or Bash/Zsh syntax:<br>
+red=$"\033[31m"<br>
+nocolor=$"\033[m"<br>
+.<br>
+## Raw assignment:<br>
+var="$(stprint "${red}Hey${nocolor}: ${untrusted_string}")"
+</code>
+
+### EXAMPLE: STPRINT MISUSE
+
+*Warning*: Reinterpreting the escapes from the data returned from
+`stprint` is insecure. Stack of escaped escape sequences not interpreted
+before will be evaluated.
+
+Do *NOT* reinterpret the escape sequences on variable assignment (dangerous
+when printing to the terminal later:
+
+<code>
+var="$(stprint "${untrusted_string}")" # OK<br>
+# Or with Bash/Zsh syntax:<br>
+printf -v var "$(stprint "${untrusted_string}")" # DANGER (format is '%b')<br>
+printf -v var '%b' "$(stprint "${untrusted_string}")" # DANGER
+</code>
+
+Do *NOT* reinterpret the escape sequences when printing a variable, one
+more layer of escapes will be interpreted:
+
+<code>
+var="$(stprint "${untrusted_string}")" # OK<br>
+printf "${var}" # DANGER (format is '%b')<br>
+printf '%b' "${var}" # DANGER<br>
+echo -e "${var}" # DANGER<br>
+echo "${var}" # DANGER (may default to use '-e')<br>
+echo -E "${var}" # DANGER (var may have '-e' prefix)
+</code>
+
+## AUTHOR
+
+This man page has been written by Benjamin Grand M. S.
+(ben.grande.b@gmail.com).

pyproject.toml

@@ -0,0 +1,17 @@
+[tool.black]
+line-length = 79
+[tool.mypy]
+strict="yes"
+[tool.pylint.'FORMAT']
+expected-line-ending-format="LF"
+max-line-length=79
+[tool.pylint.'LOGGING']
+logging-format-style="new"
+[tool.pylint.'MESSAGES CONTROL']
+confidence=""
+[tool.pylint.'REPORTS']
+output-format="colorized"
+reports="no"
+[tool.pylint.'STRING']
+check-quote-consistency="yes"
+check-str-concat-over-line-jumps="yes"

run-tests

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -eux
+git_toplevel="$(git rev-parse --show-toplevel)"
+pyrc="${git_toplevel}/pyproject.toml"
+pythonpath="${git_toplevel}/usr/lib/python3/dist-packages"
+export PYTHONPATH="${pythonpath}${PYTHONPATH+":${PYTHONPATH}"}"
+
+pytest=(python3 -m pytest -o 'python_files=*.py')
+black=(black --config="${pyrc}" --color --diff --check)
+pylint=(pylint --rcfile="${pyrc}")
+mypy=(mypy --config-file="${pyrc}")
+
+cd "${pythonpath}/stdisplay/"
+"${pytest[@]}" "${@}"
+"${black[@]}" .
+find . -type f -name "*.py" -print0 | xargs -0 "${pylint[@]}"
+"${mypy[@]}" .
+
+utils=(stprint stecho stcat sttee stsponge)
+cd "${git_toplevel}/usr/bin"
+"${black[@]}" -- "${utils[@]}"
+"${pylint[@]}" -- "${utils[@]}"
+for file in "${utils[@]}"; do
+  "${mypy[@]}" -- "${file}"
+done

usr/bin/stcat

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+
+## SPDX-FileCopyrightText: 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+## SPDX-FileCopyrightText: 2025 ENCRYPTED SUPPORT LLC <adrelanos@whonix.org>
+##
+## SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Safely print stdin or file to stdout."""
+
+from fileinput import input as file_input
+from sys import stdin, stdout
+from stdisplay.stdisplay import stdisplay
+
+
+def main() -> None:
+    """Safely print stdin or file to stdout."""
+    stdin.reconfigure(errors="ignore")  # type: ignore
+    ## File input reads stdin when no file is provided or file is '-'.
+    for untrusted_text in file_input(encoding="ascii"):
+        stdout.write(stdisplay(untrusted_text))
+    stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

usr/bin/stecho

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+## SPDX-FileCopyrightText: 2025 Benjamin Grande M. S. <ben.grande.b@gmail.com>
+## SPDX-FileCopyrightText: 2025 ENCRYPTED SUPPORT LLC <adrelanos@whonix.org>
+##
+## SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Safely print argument to stdout with echo's formatting."""
+
+from sys import argv, stdout
+from stdisplay.stdisplay import stdisplay
+
+
+def main() -> None:
+    """Safely print argument to stdout with echo's formatting."""
+    if len(argv) > 1:
+        untrusted_text = " ".join(argv[1:])
+        stdout.write(stdisplay(untrusted_text))
+    stdout.write("\n")
+    stdout.flush()
+
+
+if __name__ == "__main__":
+    main()