linuxfabrik-lib 4.4.0__tar.gz → 5.0.0__tar.gz

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linuxfabrik-lib
-Version: 4.4.0
+Version: 5.0.0
 Summary: Python libraries used in various Linuxfabrik projects, including the 'Linuxfabrik Monitoring Plugins' project.
 Author-email: "Linuxfabrik GmbH, Zurich, Switzerland" <info@linuxfabrik.ch>
 License: This is free and unencumbered software released into the public domain.

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/base.py

@@ -11,7 +11,7 @@
 """Provides very common every-day functions."""
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026051002'
+__version__ = '2026061201'
 
 import html
 import numbers
@@ -119,6 +119,9 @@ def cu(msg=None):
     tb = format_exc() if has_traceback else None
 
     if msg is not None:
+        # Normalize line endings to LF (see oao); error output may also carry
+        # CRLF, for example when a Windows command prints its error to stdout.
+        msg = msg.replace('\r\n', '\n').replace('\r', '\n')
         msg = (
             txt.sanitize_sensitive_data(msg).strip().replace('<', "'").replace('>', "'")
         )
@@ -628,6 +631,10 @@ def oao(msg, state=STATE_OK, perfdata='', always_ok=False):
     (and exits with code 2)
 
     """
+    # Normalize line endings to LF. Output captured on Windows (or read from a
+    # file or HTTP response) can carry CRLF or stray CR, which a web UI showing
+    # the output with `white-space: pre-wrap` would render as an extra line break.
+    msg = msg.replace('\r\n', '\n').replace('\r', '\n')
     msg = html.escape(
         txt.sanitize_sensitive_data(msg.strip()),
         quote=False,

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/db_mysql.py

@@ -20,7 +20,7 @@ from .globals import STATE_UNKNOWN
 warnings.filterwarnings('ignore', category=UserWarning, module='pymysql')
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026060201'
+__version__ = '2026061201'
 
 try:
     import pymysql.cursors
@@ -302,7 +302,9 @@ def _align_session_collation(conn):
         # Whitelist identifiers to keep the formatted `SET NAMES` safe from
         # any caller-controlled value (the row comes from a system view, but
         # defence in depth doesn't cost anything).
-        if not (re.match(r'^[A-Za-z0-9_]+$', cs) and re.match(r'^[A-Za-z0-9_]+$', coll)):
+        if not (
+            re.match(r'^[A-Za-z0-9_]+$', cs) and re.match(r'^[A-Za-z0-9_]+$', coll)
+        ):
             return
         with conn.cursor() as cursor:
             cursor.execute(f'set names {cs} collate {coll}')
@@ -541,10 +543,10 @@ def get_server_info(banner=None):
     from . import shell
 
     for command in (
-        'mysqld --version',
-        'mariadbd --version',
-        'mariadb --version',
-        'mysql --version',
+        ['mysqld', '--version'],
+        ['mariadbd', '--version'],
+        ['mariadb', '--version'],
+        ['mysql', '--version'],
     ):
         success, result = shell.shell_exec(command)
         if not success:

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/disk.py

@@ -13,7 +13,7 @@ partitions, grepping a file, etc.
 """
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026060801'
+__version__ = '2026061201'
 
 import csv
 import os
@@ -747,7 +747,14 @@ def udevadm(device, _property):
     >>> udevadm('/dev/linuxfabrik', 'DEVNAME')
     ''
     """
-    success, result = shell.shell_exec(f'udevadm info --query=property --name={device}')
+    # Only query real device nodes under /dev. Resolving the path first defends
+    # against a crafted `device` that points elsewhere or smuggles arguments.
+    device = os.path.realpath(device)
+    if not device.startswith('/dev/'):
+        return ''
+    success, result = shell.shell_exec(
+        ['udevadm', 'info', '--query=property', f'--name={device}']
+    )
     if not success:
         return ''
     stdout, _, _ = result

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/distro.py

@@ -17,15 +17,13 @@ Source Code is taken, converted, shortened and modified from:
 """
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2025061001'
+__version__ = '2026061201'
 
 
 import os
 import platform
 import re
 
-from . import shell
-
 # --- Static mappings ---
 
 OSDIST_LIST = (
@@ -430,15 +428,22 @@ def get_distribution_facts():
     distro = facts.get('distribution_file_variety', 'distribution')
     facts['os_family'] = _map_os_family(distro)  # returns 'RedHat', for example
 
-    # hardcoded command, no user input; shell=True needed to source the file
-    cmd = '. /etc/os-release && echo "$NAME $VERSION"'
-    success, result = shell.shell_exec(cmd, shell=True)  # nosec B604
-    if not success:
+    # read NAME and VERSION from /etc/os-release
+    values = {}
+    try:
+        with open('/etc/os-release', encoding='utf-8') as os_release:
+            for line in os_release:
+                line = line.strip()
+                if not line or line.startswith('#') or '=' not in line:
+                    continue
+                key, value = line.split('=', 1)
+                values[key] = value.strip().strip('"').strip("'")
+    except OSError:
         return facts
 
-    stdout, _, _ = result
-    facts['os_info'] = (
-        stdout.strip()
-    )  # returns 'Fedora Linux 41 (Workstation Edition)', for example
+    # returns 'Fedora Linux 41 (Workstation Edition)', for example
+    facts['os_info'] = ' '.join(
+        part for part in (values.get('NAME'), values.get('VERSION')) if part
+    )
 
     return facts

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/dmidecode.py

@@ -14,7 +14,7 @@ Copied and refactored from py-dmidecode (https://github.com/zaibon/py-dmidecode)
 """
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026060201'
+__version__ = '2026061201'
 
 import re
 
@@ -511,7 +511,7 @@ def get_data():
         ...
     }
     """
-    success, result = shell.shell_exec('sudo dmidecode')
+    success, result = shell.shell_exec(['sudo', 'dmidecode'])
     if not success:
         return False
 

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/endoflifedate.py

@@ -15,11 +15,11 @@ Internet."""
 # pylint: disable=C0302
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026060201'  # adapt this if something in this script changed fundamentally
+__version__ = '2026061001'  # adapt this if something in this script changed fundamentally
 
 ENDOFLIFE_DATE = {
 
-    'https://endoflife.date/api/apache.json': [
+    'https://endoflife.date/api/apache-http-server.json': [
     {   'cycle': '2.4',
         'eol': False,
         'latest': '2.4.67',
@@ -503,22 +503,22 @@ ENDOFLIFE_DATE = {
     'https://endoflife.date/api/gitlab.json': [
     {   'cycle': '19.0',
         'eol': '2026-08-20',
-        'latest': '19.0.1',
-        'latestReleaseDate': '2026-05-26',
+        'latest': '19.0.2',
+        'latestReleaseDate': '2026-06-10',
         'lts': False,
         'releaseDate': '2026-05-21',
         'support': '2026-06-18'},
     {   'cycle': '18.11',
         'eol': '2026-07-16',
-        'latest': '18.11.4',
-        'latestReleaseDate': '2026-05-26',
+        'latest': '18.11.5',
+        'latestReleaseDate': '2026-06-10',
         'lts': False,
         'releaseDate': '2026-04-16',
         'support': '2026-05-21'},
     {   'cycle': '18.10',
         'eol': '2026-06-18',
-        'latest': '18.10.7',
-        'latestReleaseDate': '2026-05-26',
+        'latest': '18.10.8',
+        'latestReleaseDate': '2026-06-10',
         'lts': False,
         'releaseDate': '2026-03-19',
         'support': '2026-04-16'},
@@ -956,7 +956,7 @@ ENDOFLIFE_DATE = {
     {   'cycle': '12.4',
         'eol': '2027-05-24',
         'latest': '12.4.4',
-        'latestReleaseDate': '2026-06-04',
+        'latestReleaseDate': '2026-06-09',
         'lts': False,
         'releaseDate': '2026-02-24',
         'support': '2026-04-17'},
@@ -1927,8 +1927,8 @@ ENDOFLIFE_DATE = {
     'https://endoflife.date/api/matomo.json': [
     {   'cycle': '5',
         'eol': False,
-        'latest': '5.11.0',
-        'latestReleaseDate': '2026-06-09',
+        'latest': '5.11.1',
+        'latestReleaseDate': '2026-06-12',
         'lts': False,
         'releaseDate': '2023-12-18',
         'support': True},
@@ -2297,6 +2297,12 @@ ENDOFLIFE_DATE = {
 
 
     'https://endoflife.date/api/nextcloud.json': [
+    {   'cycle': '34',
+        'eol': '2027-06-30',
+        'latest': '34.0.0',
+        'latestReleaseDate': '2026-06-08',
+        'lts': False,
+        'releaseDate': '2026-06-09'},
     {   'cycle': '33',
         'eol': '2027-02-28',
         'latest': '33.0.5',
@@ -2944,16 +2950,16 @@ ENDOFLIFE_DATE = {
     'https://endoflife.date/api/python.json': [
     {   'cycle': '3.14',
         'eol': '2030-10-31',
-        'latest': '3.14.5',
-        'latestReleaseDate': '2026-05-10',
+        'latest': '3.14.6',
+        'latestReleaseDate': '2026-06-10',
         'lts': False,
         'pep': 'PEP-0745',
         'releaseDate': '2025-10-07',
         'support': '2027-10-01'},
     {   'cycle': '3.13',
         'eol': '2029-10-31',
-        'latest': '3.13.13',
-        'latestReleaseDate': '2026-04-07',
+        'latest': '3.13.14',
+        'latestReleaseDate': '2026-06-10',
         'lts': False,
         'pep': 'PEP-0719',
         'releaseDate': '2024-10-07',
@@ -3273,7 +3279,7 @@ ENDOFLIFE_DATE = {
     ],
 
 
-    'https://endoflife.date/api/rocketchat.json': [
+    'https://endoflife.date/api/rocket-chat.json': [
     {   'cycle': '8.4',
         'eol': '2026-10-31',
         'latest': '8.4.3',

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/lftest.py

@@ -13,12 +13,13 @@
 import contextlib
 import os
 import re
+import shlex
 import tempfile
 
 from . import base, disk, shell
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026060202'
+__version__ = '2026061201'
 
 
 def run(test_instance, plugin, testcase):
@@ -73,8 +74,10 @@ def run(test_instance, plugin, testcase):
     ...             with self.subTest(id=t['id']):
     ...                 lib.lftest.run(self, self.check, t)
     """
+    # params come from the trusted testcase definition; tokenize them the way a
+    # shell would so quoted multi-word values stay intact, then build the argv.
     params = testcase.get('params', '')
-    cmd = f'{plugin} {params} --test={testcase["test"]}'.strip()
+    cmd = [plugin, *shlex.split(params), f'--test={testcase["test"]}']
     stdout, stderr, retc = base.coe(shell.shell_exec(cmd))
 
     test_instance.assertEqual(
@@ -133,7 +136,6 @@ def attach_tests(test_class, tests, plugin_attr='check'):
     ### Example
     >>> class TestCheck(unittest.TestCase):
     ...     check = '../my-plugin'
-    ...
     >>> attach_tests(TestCheck, TESTS)
     >>>
     >>> if __name__ == '__main__':
@@ -157,6 +159,7 @@ def attach_tests(test_class, tests, plugin_attr='check'):
         def _make(captured_testcase):
             def _method(self):
                 run(self, getattr(self, plugin_attr), captured_testcase)
+
             return _method
 
         setattr(test_class, method_name, _make(testcase))
@@ -222,6 +225,7 @@ def attach_each(test_class, items, action, id_func=str):
         def _make(captured_item):
             def _method(self):
                 action(self, captured_item)
+
             return _method
 
         setattr(test_class, method_name, _make(item))
@@ -339,8 +343,7 @@ def run_container(
         from testcontainers.core.wait_strategies import LogMessageWaitStrategy
     except ImportError as e:
         raise RuntimeError(
-            'testcontainers is not installed; run '
-            "`pip install testcontainers`"
+            'testcontainers is not installed; run `pip install testcontainers`'
         ) from e
 
     c = DockerContainer(image)
@@ -456,12 +459,15 @@ def _run_mysql_compatible_resolved(image_ref, command, seed):
             # in favour of `mariadb`; sclorg c10s ships both; MySQL
             # ships `mysql` only. Prefer `mariadb`, fall back to
             # `mysql` so all flavours work.
-            container.exec([
-                'sh', '-c',
-                'if command -v mariadb >/dev/null 2>&1; then CLIENT=mariadb; '
-                'else CLIENT=mysql; fi; '
-                f'"$CLIENT" -utest -ptest test -e "{seed}"',
-            ])
+            container.exec(
+                [
+                    'sh',
+                    '-c',
+                    'if command -v mariadb >/dev/null 2>&1; then CLIENT=mariadb; '
+                    'else CLIENT=mysql; fi; '
+                    f'"$CLIENT" -utest -ptest test -e "{seed}"',
+                ]
+            )
 
         host = container.get_container_host_ip()
         port = container.get_exposed_port(3306)
@@ -574,7 +580,8 @@ def run_mysql_compatible_from_containerfile(
     ... ) as (container, defaults_file):
     ...     result = subprocess.run(
     ...         ['python3', '../mysql-traffic', f'--defaults-file={defaults_file}'],
-    ...         capture_output=True, text=True,
+    ...         capture_output=True,
+    ...         text=True,
     ...     )
     """
     try:
@@ -592,6 +599,8 @@ def run_mysql_compatible_from_containerfile(
     dockerfile_name = os.path.basename(abspath)
     tag = f'lfmp-mysql-{dockerfile_name}'.lower().replace('_', '-')
 
+    # No parenthesized context managers: they are Python 3.10+ syntax and break
+    # parsing on RHEL 8's default Python 3.6.
     with (
         DockerImage(
             path=build_dir,
@@ -600,7 +609,9 @@ def run_mysql_compatible_from_containerfile(
             clean_up=False,
         ) as image,
         _run_mysql_compatible_resolved(
-            str(image.tag), command, seed,
+            str(image.tag),
+            command,
+            seed,
         ) as result,
     ):
         yield result

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/linuxfabrik_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linuxfabrik-lib
-Version: 4.4.0
+Version: 5.0.0
 Summary: Python libraries used in various Linuxfabrik projects, including the 'Linuxfabrik Monitoring Plugins' project.
 Author-email: "Linuxfabrik GmbH, Zurich, Switzerland" <info@linuxfabrik.ch>
 License: This is free and unencumbered software released into the public domain.

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/nextcloud.py

@@ -11,10 +11,11 @@
 """This library collects some Nextcloud related functions."""
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026041401'
+__version__ = '2026061201'
 
 import json
 import os
+import shlex
 import shutil
 
 from . import disk, shell
@@ -80,16 +81,17 @@ def run_occ(path, cmd, _format='json'):
     # get the owner of config.php
     user = disk.get_owner(os.path.join(path, 'config/config.php'))
     occ = os.path.join(path, 'occ')
-    # When running a command as a UID, many shells require
-    # that the `#` be escaped with a backslash (`\`).
-    sudo_cmd = f'sudo -u \\#{user} {php} {occ} {cmd}'
+    # Run occ as the numeric UID of the config.php owner. `sudo -u '#<uid>'` selects
+    # the user by UID; the `#` only needs escaping for a shell, which we do not use.
+    sudo_cmd = ['sudo', '-u', f'#{user}', php, occ, *shlex.split(cmd)]
 
     success, result = shell.shell_exec(sudo_cmd)
     stdout, stderr, rc = result
 
     # Prefer the return code to decide success/failure, not stderr presence
     if not success or rc != 0:
-        return False, f'Error running `{sudo_cmd}`: rc={rc}\n{stderr or stdout}'
+        cmd_display = ' '.join(sudo_cmd)
+        return False, f'Error running `{cmd_display}`: rc={rc}\n{stderr or stdout}'
 
     # If we expect JSON, try to parse it; otherwise return text
     if str(_format).lower() == 'json':

{linuxfabrik_lib-4.4.0 → linuxfabrik_lib-5.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "linuxfabrik-lib"
-version = "4.4.0"
+version = "5.0.0"
 description = "Python libraries used in various Linuxfabrik projects, including the 'Linuxfabrik Monitoring Plugins' project."
 readme = "README.md"
 authors = [

linuxfabrik_lib-5.0.0/shell.py

@@ -0,0 +1,204 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8; py-indent-offset: 4 -*-
+#
+# Author:  Linuxfabrik GmbH, Zurich, Switzerland
+# Contact: info (at) linuxfabrik (dot) ch
+#          https://www.linuxfabrik.ch/
+# License: The Unlicense, see LICENSE file.
+
+# https://github.com/Linuxfabrik/monitoring-plugins/blob/main/CONTRIBUTING.rst
+
+"""Communicates with the Shell on Linux and Windows."""
+
+__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
+__version__ = '2026061202'
+
+
+import os
+import shutil
+import subprocess  # nosec B404 - this library is the subprocess helper
+
+from . import txt
+
+RETC_SSHPASS = {
+    1: 'Invalid command line argument',
+    2: 'Conflicting arguments given',
+    3: 'General runtime error',
+    4: 'Unrecognized response from ssh (parse error)',
+    5: 'Invalid/incorrect password',
+    6: 'Host public key is unknown. sshpass exits without confirming the new key.',
+    7: 'IP public key changed. sshpass exits without confirming the new key.',
+}
+
+
+def shell_exec(cmd, env=None, stdin='', cwd=None, timeout=None, lc_all='C'):
+    """
+    Execute a command in a subprocess, given as a list of arguments (argv).
+
+    The command is always run with `shell=False`, so no shell is involved: arguments are passed
+    verbatim to the executable and are never interpreted for pipes (`|`), redirection, globbing,
+    variable expansion or any other shell metacharacter. This makes the helper safe to call with
+    untrusted argument values: a value like `|reboot|` or `; rm -rf /` ends up as one literal
+    argument, not as a command.
+
+    Because there is no shell, `cmd` must be a list (argv). Passing a string raises `TypeError`.
+    Build the command as a list, for example `['df', '--human-readable', mountpoint]`, where
+    `mountpoint` may be untrusted. A genuine pipeline (`a | b`) has to be expressed in code by
+    running the stages and connecting them explicitly, or by post-processing the first command's
+    output; it can no longer be expressed as a shell string.
+
+    ### Parameters
+    - **cmd** (`list`):
+      The command to execute, as a list of arguments (argv), e.g. `['ls', '-l', '/tmp']`.
+      The first element is the program, the rest are its arguments.
+    - **env** (`dict`, optional):
+      A dictionary of environment variables to merge with the current OS environment.
+      Defaults to the current environment.
+    - **stdin** (`str`, optional):
+      A string to pass as standard input to the command. Defaults to an empty string.
+    - **cwd** (`str`, optional):
+      Working directory in which to execute the command. Defaults to None (current directory).
+    - **timeout** (`int` or `float`, optional):
+      Maximum time (in seconds) to allow the command to run. If exceeded, the process is
+      terminated. Defaults to None (no timeout).
+    - **lc_all** (`str`, optional):
+      Value to set for the `LC_ALL` environment variable, forcing command output locale.
+      Defaults to `'C'` (POSIX "C" locale, i.e., English).
+
+    ### Returns
+    - **tuple**:
+      - On success:
+        `(True, (stdout, stderr, return_code))`
+        - **stdout** (`str`): Standard output of the command (decoded to text).
+        - **stderr** (`str`): Standard error of the command (decoded to text).
+        - **return_code** (`int`): Exit status of the command.
+      - On failure:
+        `(False, error_message)` — a string describing the error.
+
+    ### Notes
+    - The environment is merged with `env` and always includes `LC_ALL=<lc_all>`, forcing output
+      to the specified locale.
+    - Exceptions such as `OSError`, `ValueError`, or other execution errors during process
+      creation are caught and reported as `(False, <error message>)`.
+    - If the process exceeds the specified `timeout`, it is killed, and the function returns
+      `(False, "Timeout after <timeout> seconds.")`.
+    """
+    if not isinstance(cmd, (list, tuple)):
+        raise TypeError(
+            'shell_exec() requires cmd as a list of arguments '
+            f'(for example ["df", "-h"]), got {type(cmd).__name__}.'
+        )
+
+    env = {**os.environ.copy(), **(env or {})}
+    env['LC_ALL'] = lc_all
+
+    try:
+        p = subprocess.Popen(  # nosec B603 - shell=False, cmd is an argv list, no shell interpretation
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            shell=False,
+            cwd=cwd,
+        )
+    except (OSError, ValueError, Exception) as e:
+        return False, f'Error "{e}" while calling command "{cmd}"'
+
+    try:
+        stdout, stderr = p.communicate(
+            input=txt.to_bytes(stdin) if stdin else None,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        p.kill()
+        p.communicate()
+        return False, f'Timeout after {timeout} seconds.'
+
+    # Decode the captured bytes. On Windows, console programs (query, schtasks,
+    # w32tm, ...) write their piped output in the OEM / console output code page
+    # (e.g. cp437, cp850), not UTF-8 and not the ANSI code page, so a username
+    # like "müller" would otherwise be mangled (Linuxfabrik/monitoring-plugins#681).
+    if os.name == 'nt':
+        encoding, errors = _windows_output_encoding(), 'replace'
+    else:
+        encoding, errors = 'utf-8', 'surrogateescape'
+    return True, (
+        txt.to_text(stdout, encoding=encoding, errors=errors),
+        txt.to_text(stderr, encoding=encoding, errors=errors),
+        p.returncode,
+    )
+
+
+def _windows_output_encoding():
+    """
+    Best-effort code page name for decoding a Windows subprocess's piped output.
+
+    Console programs emit their pipe output in the OEM / console output code page, not UTF-8 and
+    not the ANSI code page (`chcp 65001` has no effect on a pipe; see PEP 528). Prefer the console
+    output code page, fall back to the OEM code page when the process has no console (for example
+    when run headless by a monitoring agent), and fall back to UTF-8 if neither is available.
+
+    ### Returns
+    - **str**: A Python codec name such as `'cp437'`, or `'utf-8'` as a last resort.
+    """
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        code_page = kernel32.GetConsoleOutputCP() or kernel32.GetOEMCP()
+        if code_page:
+            return f'cp{code_page}'
+    except (OSError, AttributeError, ValueError):
+        pass
+    return 'utf-8'
+
+
+def safe_cli_value(value, name='value'):
+    """
+    Reject a value that a called program could misinterpret as an option.
+
+    Building a command as an argument list (argv) and running it with `shell_exec()` prevents
+    shell injection, but it does not stop a value that starts with `-` from being picked up as an
+    *option* by the program being run, for example an ssh destination `-oProxyCommand=...` (remote
+    code execution) or a `ping` target `-f` (flood). Use this for values that reach a command as a
+    positional argument or as a command target, where option-style values have no legitimate
+    meaning. Values that are bound to an explicit option (`--name=<value>` or `-H <value>`) do not
+    need this guard.
+
+    ### Parameters
+    - **value** (`any`): The value to check. Non-string values pass through unchanged.
+    - **name** (`str`, optional): Human-readable name used in the error message. Defaults to
+      `'value'`.
+
+    ### Returns
+    - **tuple**: `(True, value)` if the value is safe, else `(False, error_message)`. The shape
+      is suitable for `lib.base.coe()`.
+
+    ### Example
+    >>> host = lib.base.coe(lib.shell.safe_cli_value(args.HOSTNAME, '--hostname'))
+    """
+    if isinstance(value, str) and value.startswith('-'):
+        return False, f'Refusing {name} that starts with "-": {value}'
+    return True, value
+
+
+def which(name):
+    """
+    Locate an executable in the system PATH, like the `which` command.
+
+    Thin wrapper around `shutil.which()` so callers do not need to import it
+    directly and the lookup stays consistent across consumers.
+
+    ### Parameters
+    - **name** (`str`): Program name to look for (e.g. `lynis`).
+
+    ### Returns
+    - **str or None**: The absolute path to the executable, or `None` if it is
+      not found in PATH.
+
+    ### Example
+    >>> which('sh')
+    '/usr/bin/sh'
+    """
+    return shutil.which(name)