# `latexrestricted` — Python library for creating executables compatible with LaTeX restricted shell escape
This Python package is designed to simplify the process of creating Python
executables compatible with [LaTeX](https://www.latex-project.org/) restricted
shell escape. Restricted shell escape allows LaTeX to run trusted executables
as part of compiling documents. These executables have restricted access to
the file system and restricted ability to launch subprocesses.
`latexrestricted` provides access to LaTeX configuration and implements
wrappers around Python's
[`pathlib.Path`](https://docs.python.org/3/library/pathlib.html) and
[`subprocess.run()`](https://docs.python.org/3/library/subprocess.html#subprocess.run)
that follow LaTeX security settings.
## Usage considerations
### Importing
`latexrestricted` should be imported as soon as possible during the
initialization of an executable. When it is imported, it sets the current
working directory as the TeX working directory. If it is imported after the
current working directory is changed, then the TeX working directory will be
set incorrectly and security restrictions will fail.
### Failure modes on systems with multiple TeX installations
`latexrestricted` works correctly when used on systems with no more than one
[TeX Live](https://www.tug.org/texlive/) installation and no more than one
[MiKTeX](https://miktex.org/) installation. If multiple TeX Live
installations or multiple MiKTeX installations are present, it is not always
possible for `latexrestricted` to determine the correct TeX Live or MiKTeX
installation, and in these cases the first installation on `PATH` is used.
**In these cases, `latexrestricted` may fail to return the correct TeX
configuration values, and there is no way to detect this.** See
`LatexConfig._init_tex_paths()` for implementation details.
* Multiple TeX Live installations: The correct installation will be used
under non-Windows operating systems. Under Windows, the first
installation on `PATH` is used.
* Multiple MiKTeX installations: Under all operating systems, the first
installation on `PATH` is used.
The user can avoid any issues with multiple installations by modifying `PATH`
to put the correct TeX Live or MiKTeX installation first.
## LaTeX configuration
```
from latexrestricted import latex_config
```
The `latex_config` instance of the `LatexConfig` class provides access to
LaTeX configuration and related environment variables. If there are errors in
determining LaTeX configuration (for example, a TeX installation cannot be
located), then `latexrestricted.LatexConfigError` is raised.
### `latex_config` attributes and properties
Paths:
* `tex_cwd: str`: Current working directory when `latexrestricted` was
first imported.
* `texlive_bin: str | None` and `texlive_kpsewhich: str | None`: If an
executable using `latexrestricted` is launched via `\ShellEscape` with TeX
Live, these will be the paths to the TeX Live `bin/` directory and the TeX
Live `kpsewhich` executable. Otherwise, both are `None`.
TeX Live is detected by the absence of a `TEXSYSTEM` environment variable,
or by this variable having a value other than `miktex`. Under non-Windows
operating systems, the `SELFAUTOLOC` environment variable set by `kpathsea`
is used to locate the TeX Live binary directory, so it will be correct even
on systems with multiple TeX Live installations. Under Windows, shell
escape executables are often launched with TeX Live's executable wrapper
`runscript.exe`, which overwrites `SELFAUTOLOC` with the location of the
wrapper. In this case, the TeX Live binary directory is located by using
Python's `shutil.which()` to search `PATH` for a `tlmgr` executable with
accompanying `kpsewhich`. On systems with multiple TeX Live installations,
this will give the first TeX Live installation on `PATH`, which is not
guaranteed to be correct unless the user ensures that the correct
installation has precedence on `PATH`.
* `miktex_bin: str | None`, `miktex_initexmf: str | None`, and
`miktex_kpsewhich: str | None`: If an executable using `latexrestricted`
is launched via `\ShellEscape` with MiKTeX, these will be the paths to the
MiKTeX `bin/` directory and the MiKTeX `initexmf` and `kpsewhich`
executables. Otherwise, all are `None`.
MiKTeX is detected by checking the `TEXSYSTEM` environment variable for the
value `miktex`. `TEXSYSTEM` only declares that MiKTeX is in use; unlike the
TeX Live case with `SELFAUTOLOC`, `TEXSYSTEM` does not give the location of
TeX binaries. The location of TeX binaries is determined using Python's
`shutil.which()` to search `PATH` for an `initexmf` executable with
accompanying `kpsewhich`. On systems with multiple MiKTeX installations,
this will give the first MiKTeX installation on `PATH`, which is not
guaranteed to be correct unless the user ensures that the correct
installation has precedence on `PATH`.
File system access:
* `can_read_dotfiles: bool`, `can_read_anywhere: bool`,
`can_write_dotfiles: bool`, `can_write_anywhere: bool`: These summarize
the file system security settings for TeX Live (`openin_any` and
`openout_any` in `texmf.cnf`) and MiKTeX (`[Core]AllowUnsafeInputFiles`
and `[Core]AllowUnsafeOutputFiles` in `miktex.ini`). The `*dotfile`
properties describe whether dotfiles (files with names beginning with `.`)
can be read/written. The `*anywhere` properties describe whether files
anywhere in the file system can be read/written, or only those under the
current working directory, `TEXMFOUTPUT`, and `TEXMF_OUTPUT_DIRECTORY`.
* `can_restricted_shell_escape: bool`: This describes whether restricted
shell escape is possible. It is true when restricted shell escape is
enabled and also when full shell escape is enabled. It is based on TeX
Live's `shell_escape` in `texmf.cnf` and MiKTeX's `[Core]ShellCommandMode`
in `miktex.ini`.
* `prohibited_write_file_extensions: frozenset[str] | None`: Under Windows
(including Cygwin), this is a frozen set of file extensions that cannot be
used in writing files. Under other operating systems, this is `None`.
All file extensions are lower case with a leading period (for example,
`.exe`). These are determined from the `PATHEXT` environment variable, or
use a default fallback if `PATHEXT` is not defined or when under Cygwin.
Other LaTeX configuration variables and environment variables:
* `TEXMFHOME: str | None`: Value of `TEXMFHOME` obtained from `kpsewhich`
or `initexmf`.
* `TEXMFOUTPUT: str | None`: Value of `TEXMFOUTPUT` obtained from environment
variable if defined and otherwise from `kpsewhich` or `initexmf`.
* `TEXMF_OUTPUT_DIRECTORY: str | None`: Value of `TEXMF_OUTPUT_DIRECTORY`
obtained from environment variable.
* `restricted_shell_escape_commands: frozenset[str]`: Permitted restricted
shell escape executables. Obtained from TeX Live's `shell_escape_commands`
in `texmf.cnf` or MiKTeX's `[Core]AllowedShellCommands[]` in `miktex.ini`.
Note that this will contain permitted restricted shell escape executables
even when shell escape is completely disabled; it cannot be used to
determine whether restricted shell escape is permitted. See
`can_restricted_shell_escape` to determine whether restricted shell escape
is permitted.
### `latex_config` methods
* `kpsewhich_find_config_file(file: str)`: Use `kpsewhich` in a subprocess
to find a configuration file (`kpsewhich -f othertext <file>`). Returns
`kpsewhich` output as a string or `None` if there was no output.
* `kpsewhich_find_file(file: str, *, cache: bool = False)`: Use `kpsewhich`
in a subprocess to find a file (`kpsewhich <file>`). Returns `kpsewhich`
output as a string or `None` if there was no output. The optional
argument `cache` caches `kpsewhich` output to minimize subprocesses. This
can be useful when the file system is not being modified and `kpsewhich` is
simply returning values from its own cache.
## Restricted file system access
TeX limits file system access. The file system security settings for TeX Live
(`openin_any` and `openout_any` in `texmf.cnf`) and MiKTeX
(`[Core]AllowUnsafeInputFiles` and `[Core]AllowUnsafeOutputFiles` in
`miktex.ini`) determine whether dotfiles can be read/written and whether files
anywhere in the file system can be read/written, or only those under the
current working directory, `TEXMFOUTPUT`, and `TEXMF_OUTPUT_DIRECTORY`.
The `latexrestricted` package provides `RestrictedPath` subclasses of Python's
[`pathlib.Path`](https://docs.python.org/3/library/pathlib.html) that respect
these security settings or enforce more stringent security. Under Python 3.8,
these subclasses backport the methods `.is_relative_to()` and `.with_stem()`
from Python 3.9. When these subclasses are used to modify the file system,
`latexrestricted.PathSecurityError` is raised if reading/writing a given path
is not permitted.
**With `RestrictedPath` classes, relative paths are always relative to the TeX
working directory.** If the current working directory has been changed to
another location (for example, via `os.chdir()`), then it will temporarily be
switched back to the TeX working directory during any `RestrictedPath`
operations that access the file system.
**The `SafeWrite*` classes should be preferred unless access to additional
write locations is absolutely necessary.** When multiple TeX Live
installations are present under Windows or multiple MiKTeX installations are
present under all operating systems, there is no guarantee that
`latexrestricted` will find the correct installation and thus use the correct
TeX configuration, unless `PATH` has been modified to put the correct
installation first.
```
from latexrestricted import <RestrictedPathClass>
```
### `RestrictedPath` classes
#### `BaseRestrictedPath`
This is the base class for `RestrictedPath` classes. It cannot be used
directly. Subclasses define methods `.readable_dir()`, `.readable_file()`,
`.writable_dir()`, and `.writable_file()` that determine whether a given path
is readable/writable. Most methods for opening, reading, writing, replacing,
and deleting files as well as methods for creating and deleting directories
are supported. Methods related to modifying file permissions and creating
links are not supported. Unsupported methods raise `NotImplementedError`.
#### `StringRestrictedPath` classes
* `StringRestrictedPath`: This follows the approach taken in TeX's file
system security. TeX configuration determines whether dotfiles are
readable/writable and which locations are readable/writable. Paths are
analyzed as strings; the file system is never consulted. When read/write
locations are restricted, paths are restricted using the following criteria:
- All relative paths are relative to the TeX working directory.
- All absolute paths must be under `TEXMF_OUTPUT_DIRECTORY` and
`TEXMFOUTPUT`.
- Paths cannot contain `..` to access a parent directory, even if the
parent directory is a valid location.
When read/write locations are restricted, it is still possible to access
locations outside the TeX working directory, `TEXMF_OUTPUT_DIRECTORY`, and
`TEXMFOUTPUT` if there are symlinks in those locations.
Under Windows (including Cygwin), writing files with file extensions in
`PATHEXT` (for example, `.exe`) is also disabled.
* `SafeStringRestrictedPath`: Same as `StringRestrictedPath`, except that TeX
configuration is ignored and all security settings are at maximum: dotfiles
cannot be read/written, and all reading/writing is limited to the TeX
working directory, `TEXMF_OUTPUT_DIRECTORY`, and `TEXMFOUTPUT`.
* `SafeWriteStringRestrictedPath`: Same as `StringRestrictedPath`, except
that TeX configuration for writing is ignored and all security settings
related to writing are at maximum.
#### `ResolvedRestrictedPath` classes
* `ResolvedRestrictedPath`: This resolves any symlinks in paths using the
file system before determining whether paths are readable/writable. TeX
configuration determines whether dotfiles are readable/writable and which
locations are readable/writable. When read/write locations are restricted,
paths are restricted using the following criteria:
- Resolved paths must be under the TeX working directory,
resolved `TEXMF_OUTPUT_DIRECTORY`, or resolved `TEXMFOUTPUT`.
- All relative paths are resolved relative to the TeX working directory.
- Unlike `StringRestrictedPath`, paths are allowed to contain `..`, and
`TEXMF_OUTPUT_DIRECTORY` and `TEXMFOUTPUT` can be accessed via relative
paths. This is possible since paths are fully resolved with the file
system before being compared with permitted read/write locations.
Because paths are resolved before being compared with permitted read/write
locations, it is not possible to access locations outside the TeX working
directory, `TEXMF_OUTPUT_DIRECTORY`, and `TEXMFOUTPUT` via symlinks in
those locations.
Under Windows (including Cygwin), writing files with file extensions in
`PATHEXT` (for example, `.exe`) is also disabled.
* `SafeResolvedRestrictedPath`: Same as `ResolvedRestrictedPath`, except
that TeX configuration is ignored and all security settings are at maximum:
dotfiles cannot be read/written, and all other reading/writing is limited to
the TeX working directory, `TEXMF_OUTPUT_DIRECTORY`, and `TEXMFOUTPUT`.
* `SafeWriteResolvedRestrictedPath`: Same as `ResolvedRestrictedPath`, except
that TeX configuration for writing is ignored and all security settings
related to writing are at maximum.
#### `RestrictedPath` class methods
* `tex_cwd() -> Self`: TeX working directory.
* `TEXMFOUTPUT() -> Self | None`: Path of `TEXMFOUTPUT` from LaTeX
configuration or environment variable, or `None` if not defined.
* `TEXMF_OUTPUT_DIRECTORY() -> Self | None`: Path of `TEXMF_OUTPUT_DIRECTORY`
from environment variable, or `None` if not defined.
* `tex_roots() -> frozenset[Self]`: All root locations where TeX might write
output, under default configuration with restricted access to the file
system. This includes `tex_cwd()` plus `TEXMFOUTPUT()` and
`TEXMF_OUTPUT_DIRECTORY()` if they are defined.
* `tex_roots_resolved() -> frozenset[Self]`: Same as `tex_roots()` except
all paths are resolved with the file system.
* `tex_roots_with_resolved() -> frozenset[Self]`: Union of `tex_roots()` and
`tex_roots_resolved()`.
* `tex_openout_roots() -> tuple[Self]`: Locations where TeX will attempt to
write with `\openout`, in order. The first element of the tuple is
`TEXMF_OUTPUT_DIRECTORY()` if not `None` and otherwise `tex_cwd()`. If
`TEXMFOUTPUT()` is not `None` and is not already in the tuple, then it is
the second element.
TeX attempts to write to `TEXMFOUTPUT` (if defined) when the default write
location (`TEXMF_OUTPUT_DIRECTORY` if defined, else TeX working directory)
is read-only.
* `tex_texmfoutput_roots() -> frozenset[Self]`: `TEXMFOUTPUT()` and/or
`TEXMF_OUTPUT_DIRECTORY()` if they are defined.
## Restricted subprocesses
When LaTeX runs with restricted shell escape, only executables specified in
TeX configuration can be executed via `\ShellEscape`. The `latexrestricted`
package allows these same executables to run in subprocesses via
`restricted_run()`. This is a wrapper around Python's
[`subprocess.run()`](https://docs.python.org/3/library/subprocess.html#subprocess.run).
```
from latexrestricted import restricted_run
restricted_run(args: list[str], allow_restricted_executables: bool = False)
```
* It is *always* possible to run `kpsewhich` (including `miktex-kpsewhich`)
and `initexmf`. These are necessary to access TeX configuration values.
Running other executables allowed by TeX configuration for restricted shell
escape requires the optional argument `allow_restricted_executables=True`.
In this case, TeX configuration is checked to determine whether restricted
shell escape is enabled, although this should be redundant if
`latexrestricted` itself is being used in a restricted shell escape
executable.
* When `allow_restricted_executables=True`, the executable must be in the same
directory as `kpsewhich` or `initexmf`, as previously located during TeX
configuration detection, or the executable must exist on `PATH`, as found by
Python's `shutil.which()`.
The executable must not be in a location writable by LaTeX. For added
security, locations writable by LaTeX cannot be under the executable parent
directory.
* The executable cannot be a batch file (no `*.bat` or `*.cmd`):
https://docs.python.org/3/library/subprocess.html#security-considerations.
This is enforced by requiring `*.exe` under Windows and completely
prohibiting `*.bat` and `*.cmd` everywhere.
* The subprocess runs with `shell=False`.
`restricted_run()` will raise `latexrestricted.ExecutableNotFoundError` if an
executable (`args[0]`) cannot be found in the same directory as `kpsewhich` or
`initexmf`, or on `PATH`. It will raise
`latexrestricted.UnapprovedExecutableError` when the executable is not in the
approved list of executables from LaTeX configuration
(`latex_config.restricted_shell_escape_commands`). It will raise
`latexrestricted.ExecutablePathSecurityError` if the executable is found and
is in the approved list, but is in an insecure location relative to locations
writable by LaTeX.
## Security limitations with TeX Live and `TEXMFOUTPUT`
TeX Live allows `TEXMFOUTPUT` to be set in a `texmf.cnf` config file. In this
case, `latexrestricted` will retrieve the value of `TEXMFOUTPUT` by running
`kpsewhich --var-value TEXMFOUTPUT` in a subprocess. If the user has modified
`TEXMFOUTPUT` to an unsafe value in a `texmf.cnf` config file, then the
`kpsewhich` executable (and all other TeX-related executables) are potentially
compromised, and `latexrestricted` cannot detect this until *after* running
`kpsewhich`.
It is possible to set `TEXMFOUTPUT` to unsafe values in a `texmf.cnf` config
file. For example, if `TEXMFOUTPUT` is set to a location in the file system
that contains executables, this could allow LaTeX documents to modify those
executables or their resources. With TeX Live, `latexrestricted` retrieves
the value of `TEXMFOUTPUT` by running `kpsewhich`. However, the `kpsewhich`
executable itself could be compromised if `TEXMFOUTPUT` is set to a directory
that contains the `kpsewhich` executable (or other parts of a TeX
installation). If `latexrestricted` detects an unsafe value of `TEXMFOUTPUT`,
it raises `latexrestricted.LatexConfigError`, but this is only possible
*after* running the potentially compromised `kpsewhich` executable to obtain
the value of `TEXMFOUTPUT`. (And if `kpsewhich` is compromised, there is
always the possibility that it will not return the true value of
`TEXMFOUTPUT`.)
While raising a security-related error after running the potentially
compromised executable is not ideal, this will typically have a negligible
impact on overall security. If `TEXMFOUTPUT` is set to a directory that
contains the `kpsewhich` executable (or other parts of a TeX installation),
then all other TeX-related executables are also potentially compromised. If
`latexrestricted` is being used in a Python executable designed for LaTeX
shell escape, then presumably a LaTeX executable is already running, and LaTeX
may invoke additional trusted executables such as `kpsewhich` in shells.
Thus, before `latexrestricted` ever runs `kpsewhich` to retrieve the value of
`TEXMFOUTPUT`, potentially compromised executables would already be running.
Raw data
{
"_id": null,
"home_page": null,
"name": "latexrestricted",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "LaTeX, security, restricted shell escape",
"author": null,
"author_email": "\"Geoffrey M. Poore\" <gpoore@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/69/c2/5174b64463f9530c3d19c47606140b098b2ed6a6cb4ceac8c34b616bafdd/latexrestricted-0.6.2.tar.gz",
"platform": null,
"description": "# `latexrestricted` \u2014 Python library for creating executables compatible with LaTeX restricted shell escape\r\n\r\n\r\nThis Python package is designed to simplify the process of creating Python\r\nexecutables compatible with [LaTeX](https://www.latex-project.org/) restricted\r\nshell escape. Restricted shell escape allows LaTeX to run trusted executables\r\nas part of compiling documents. These executables have restricted access to\r\nthe file system and restricted ability to launch subprocesses.\r\n\r\n`latexrestricted` provides access to LaTeX configuration and implements\r\nwrappers around Python's\r\n[`pathlib.Path`](https://docs.python.org/3/library/pathlib.html) and\r\n[`subprocess.run()`](https://docs.python.org/3/library/subprocess.html#subprocess.run)\r\nthat follow LaTeX security settings.\r\n\r\n\r\n\r\n## Usage considerations\r\n\r\n\r\n### Importing\r\n\r\n`latexrestricted` should be imported as soon as possible during the\r\ninitialization of an executable. When it is imported, it sets the current\r\nworking directory as the TeX working directory. If it is imported after the\r\ncurrent working directory is changed, then the TeX working directory will be\r\nset incorrectly and security restrictions will fail.\r\n\r\n\r\n### Failure modes on systems with multiple TeX installations\r\n\r\n`latexrestricted` works correctly when used on systems with no more than one\r\n[TeX Live](https://www.tug.org/texlive/) installation and no more than one\r\n[MiKTeX](https://miktex.org/) installation. If multiple TeX Live\r\ninstallations or multiple MiKTeX installations are present, it is not always\r\npossible for `latexrestricted` to determine the correct TeX Live or MiKTeX\r\ninstallation, and in these cases the first installation on `PATH` is used.\r\n**In these cases, `latexrestricted` may fail to return the correct TeX\r\nconfiguration values, and there is no way to detect this.** See\r\n`LatexConfig._init_tex_paths()` for implementation details.\r\n\r\n * Multiple TeX Live installations: The correct installation will be used\r\n under non-Windows operating systems. Under Windows, the first\r\n installation on `PATH` is used.\r\n\r\n * Multiple MiKTeX installations: Under all operating systems, the first\r\n installation on `PATH` is used.\r\n\r\nThe user can avoid any issues with multiple installations by modifying `PATH`\r\nto put the correct TeX Live or MiKTeX installation first.\r\n\r\n\r\n\r\n## LaTeX configuration\r\n\r\n```\r\nfrom latexrestricted import latex_config\r\n```\r\n\r\nThe `latex_config` instance of the `LatexConfig` class provides access to\r\nLaTeX configuration and related environment variables. If there are errors in\r\ndetermining LaTeX configuration (for example, a TeX installation cannot be\r\nlocated), then `latexrestricted.LatexConfigError` is raised.\r\n\r\n\r\n### `latex_config` attributes and properties\r\n\r\nPaths:\r\n\r\n* `tex_cwd: str`: Current working directory when `latexrestricted` was\r\n first imported.\r\n\r\n* `texlive_bin: str | None` and `texlive_kpsewhich: str | None`: If an\r\n executable using `latexrestricted` is launched via `\\ShellEscape` with TeX\r\n Live, these will be the paths to the TeX Live `bin/` directory and the TeX\r\n Live `kpsewhich` executable. Otherwise, both are `None`.\r\n\r\n TeX Live is detected by the absence of a `TEXSYSTEM` environment variable,\r\n or by this variable having a value other than `miktex`. Under non-Windows\r\n operating systems, the `SELFAUTOLOC` environment variable set by `kpathsea`\r\n is used to locate the TeX Live binary directory, so it will be correct even\r\n on systems with multiple TeX Live installations. Under Windows, shell\r\n escape executables are often launched with TeX Live's executable wrapper\r\n `runscript.exe`, which overwrites `SELFAUTOLOC` with the location of the\r\n wrapper. In this case, the TeX Live binary directory is located by using\r\n Python's `shutil.which()` to search `PATH` for a `tlmgr` executable with\r\n accompanying `kpsewhich`. On systems with multiple TeX Live installations,\r\n this will give the first TeX Live installation on `PATH`, which is not\r\n guaranteed to be correct unless the user ensures that the correct\r\n installation has precedence on `PATH`.\r\n\r\n* `miktex_bin: str | None`, `miktex_initexmf: str | None`, and\r\n `miktex_kpsewhich: str | None`: If an executable using `latexrestricted`\r\n is launched via `\\ShellEscape` with MiKTeX, these will be the paths to the\r\n MiKTeX `bin/` directory and the MiKTeX `initexmf` and `kpsewhich`\r\n executables. Otherwise, all are `None`.\r\n\r\n MiKTeX is detected by checking the `TEXSYSTEM` environment variable for the\r\n value `miktex`. `TEXSYSTEM` only declares that MiKTeX is in use; unlike the\r\n TeX Live case with `SELFAUTOLOC`, `TEXSYSTEM` does not give the location of\r\n TeX binaries. The location of TeX binaries is determined using Python's\r\n `shutil.which()` to search `PATH` for an `initexmf` executable with\r\n accompanying `kpsewhich`. On systems with multiple MiKTeX installations,\r\n this will give the first MiKTeX installation on `PATH`, which is not\r\n guaranteed to be correct unless the user ensures that the correct\r\n installation has precedence on `PATH`.\r\n\r\nFile system access:\r\n\r\n* `can_read_dotfiles: bool`, `can_read_anywhere: bool`,\r\n `can_write_dotfiles: bool`, `can_write_anywhere: bool`: These summarize\r\n the file system security settings for TeX Live (`openin_any` and\r\n `openout_any` in `texmf.cnf`) and MiKTeX (`[Core]AllowUnsafeInputFiles`\r\n and `[Core]AllowUnsafeOutputFiles` in `miktex.ini`). The `*dotfile`\r\n properties describe whether dotfiles (files with names beginning with `.`)\r\n can be read/written. The `*anywhere` properties describe whether files\r\n anywhere in the file system can be read/written, or only those under the\r\n current working directory, `TEXMFOUTPUT`, and `TEXMF_OUTPUT_DIRECTORY`.\r\n\r\n* `can_restricted_shell_escape: bool`: This describes whether restricted\r\n shell escape is possible. It is true when restricted shell escape is\r\n enabled and also when full shell escape is enabled. It is based on TeX\r\n Live's `shell_escape` in `texmf.cnf` and MiKTeX's `[Core]ShellCommandMode`\r\n in `miktex.ini`.\r\n\r\n* `prohibited_write_file_extensions: frozenset[str] | None`: Under Windows\r\n (including Cygwin), this is a frozen set of file extensions that cannot be\r\n used in writing files. Under other operating systems, this is `None`.\r\n\r\n All file extensions are lower case with a leading period (for example,\r\n `.exe`). These are determined from the `PATHEXT` environment variable, or\r\n use a default fallback if `PATHEXT` is not defined or when under Cygwin.\r\n\r\nOther LaTeX configuration variables and environment variables:\r\n\r\n* `TEXMFHOME: str | None`: Value of `TEXMFHOME` obtained from `kpsewhich`\r\n or `initexmf`.\r\n\r\n* `TEXMFOUTPUT: str | None`: Value of `TEXMFOUTPUT` obtained from environment\r\n variable if defined and otherwise from `kpsewhich` or `initexmf`.\r\n\r\n* `TEXMF_OUTPUT_DIRECTORY: str | None`: Value of `TEXMF_OUTPUT_DIRECTORY`\r\n obtained from environment variable.\r\n\r\n* `restricted_shell_escape_commands: frozenset[str]`: Permitted restricted\r\n shell escape executables. Obtained from TeX Live's `shell_escape_commands`\r\n in `texmf.cnf` or MiKTeX's `[Core]AllowedShellCommands[]` in `miktex.ini`.\r\n\r\n Note that this will contain permitted restricted shell escape executables\r\n even when shell escape is completely disabled; it cannot be used to\r\n determine whether restricted shell escape is permitted. See\r\n `can_restricted_shell_escape` to determine whether restricted shell escape\r\n is permitted.\r\n\r\n\r\n### `latex_config` methods\r\n\r\n* `kpsewhich_find_config_file(file: str)`: Use `kpsewhich` in a subprocess\r\n to find a configuration file (`kpsewhich -f othertext <file>`). Returns\r\n `kpsewhich` output as a string or `None` if there was no output.\r\n\r\n* `kpsewhich_find_file(file: str, *, cache: bool = False)`: Use `kpsewhich`\r\n in a subprocess to find a file (`kpsewhich <file>`). Returns `kpsewhich`\r\n output as a string or `None` if there was no output. The optional\r\n argument `cache` caches `kpsewhich` output to minimize subprocesses. This\r\n can be useful when the file system is not being modified and `kpsewhich` is\r\n simply returning values from its own cache.\r\n\r\n\r\n\r\n## Restricted file system access\r\n\r\nTeX limits file system access. The file system security settings for TeX Live\r\n(`openin_any` and `openout_any` in `texmf.cnf`) and MiKTeX\r\n(`[Core]AllowUnsafeInputFiles` and `[Core]AllowUnsafeOutputFiles` in\r\n`miktex.ini`) determine whether dotfiles can be read/written and whether files\r\nanywhere in the file system can be read/written, or only those under the\r\ncurrent working directory, `TEXMFOUTPUT`, and `TEXMF_OUTPUT_DIRECTORY`.\r\n\r\nThe `latexrestricted` package provides `RestrictedPath` subclasses of Python's\r\n[`pathlib.Path`](https://docs.python.org/3/library/pathlib.html) that respect\r\nthese security settings or enforce more stringent security. Under Python 3.8,\r\nthese subclasses backport the methods `.is_relative_to()` and `.with_stem()`\r\nfrom Python 3.9. When these subclasses are used to modify the file system,\r\n`latexrestricted.PathSecurityError` is raised if reading/writing a given path\r\nis not permitted.\r\n\r\n**With `RestrictedPath` classes, relative paths are always relative to the TeX\r\nworking directory.** If the current working directory has been changed to\r\nanother location (for example, via `os.chdir()`), then it will temporarily be\r\nswitched back to the TeX working directory during any `RestrictedPath`\r\noperations that access the file system.\r\n\r\n**The `SafeWrite*` classes should be preferred unless access to additional\r\nwrite locations is absolutely necessary.** When multiple TeX Live\r\ninstallations are present under Windows or multiple MiKTeX installations are\r\npresent under all operating systems, there is no guarantee that\r\n`latexrestricted` will find the correct installation and thus use the correct\r\nTeX configuration, unless `PATH` has been modified to put the correct\r\ninstallation first.\r\n\r\n```\r\nfrom latexrestricted import <RestrictedPathClass>\r\n```\r\n\r\n### `RestrictedPath` classes\r\n\r\n#### `BaseRestrictedPath`\r\n\r\nThis is the base class for `RestrictedPath` classes. It cannot be used\r\ndirectly. Subclasses define methods `.readable_dir()`, `.readable_file()`,\r\n`.writable_dir()`, and `.writable_file()` that determine whether a given path\r\nis readable/writable. Most methods for opening, reading, writing, replacing,\r\nand deleting files as well as methods for creating and deleting directories\r\nare supported. Methods related to modifying file permissions and creating\r\nlinks are not supported. Unsupported methods raise `NotImplementedError`.\r\n\r\n\r\n#### `StringRestrictedPath` classes\r\n\r\n* `StringRestrictedPath`: This follows the approach taken in TeX's file\r\n system security. TeX configuration determines whether dotfiles are\r\n readable/writable and which locations are readable/writable. Paths are\r\n analyzed as strings; the file system is never consulted. When read/write\r\n locations are restricted, paths are restricted using the following criteria:\r\n\r\n - All relative paths are relative to the TeX working directory.\r\n\r\n - All absolute paths must be under `TEXMF_OUTPUT_DIRECTORY` and\r\n `TEXMFOUTPUT`.\r\n\r\n - Paths cannot contain `..` to access a parent directory, even if the\r\n parent directory is a valid location.\r\n\r\n When read/write locations are restricted, it is still possible to access\r\n locations outside the TeX working directory, `TEXMF_OUTPUT_DIRECTORY`, and\r\n `TEXMFOUTPUT` if there are symlinks in those locations.\r\n\r\n Under Windows (including Cygwin), writing files with file extensions in\r\n `PATHEXT` (for example, `.exe`) is also disabled.\r\n\r\n* `SafeStringRestrictedPath`: Same as `StringRestrictedPath`, except that TeX\r\n configuration is ignored and all security settings are at maximum: dotfiles\r\n cannot be read/written, and all reading/writing is limited to the TeX\r\n working directory, `TEXMF_OUTPUT_DIRECTORY`, and `TEXMFOUTPUT`.\r\n\r\n* `SafeWriteStringRestrictedPath`: Same as `StringRestrictedPath`, except\r\n that TeX configuration for writing is ignored and all security settings\r\n related to writing are at maximum.\r\n\r\n\r\n#### `ResolvedRestrictedPath` classes\r\n\r\n* `ResolvedRestrictedPath`: This resolves any symlinks in paths using the\r\n file system before determining whether paths are readable/writable. TeX\r\n configuration determines whether dotfiles are readable/writable and which\r\n locations are readable/writable. When read/write locations are restricted,\r\n paths are restricted using the following criteria:\r\n\r\n - Resolved paths must be under the TeX working directory,\r\n resolved `TEXMF_OUTPUT_DIRECTORY`, or resolved `TEXMFOUTPUT`.\r\n\r\n - All relative paths are resolved relative to the TeX working directory.\r\n\r\n - Unlike `StringRestrictedPath`, paths are allowed to contain `..`, and\r\n `TEXMF_OUTPUT_DIRECTORY` and `TEXMFOUTPUT` can be accessed via relative\r\n paths. This is possible since paths are fully resolved with the file\r\n system before being compared with permitted read/write locations.\r\n\r\n Because paths are resolved before being compared with permitted read/write\r\n locations, it is not possible to access locations outside the TeX working\r\n directory, `TEXMF_OUTPUT_DIRECTORY`, and `TEXMFOUTPUT` via symlinks in\r\n those locations.\r\n\r\n Under Windows (including Cygwin), writing files with file extensions in\r\n `PATHEXT` (for example, `.exe`) is also disabled.\r\n\r\n* `SafeResolvedRestrictedPath`: Same as `ResolvedRestrictedPath`, except\r\n that TeX configuration is ignored and all security settings are at maximum:\r\n dotfiles cannot be read/written, and all other reading/writing is limited to\r\n the TeX working directory, `TEXMF_OUTPUT_DIRECTORY`, and `TEXMFOUTPUT`.\r\n\r\n* `SafeWriteResolvedRestrictedPath`: Same as `ResolvedRestrictedPath`, except\r\n that TeX configuration for writing is ignored and all security settings\r\n related to writing are at maximum.\r\n\r\n\r\n#### `RestrictedPath` class methods\r\n\r\n* `tex_cwd() -> Self`: TeX working directory.\r\n\r\n* `TEXMFOUTPUT() -> Self | None`: Path of `TEXMFOUTPUT` from LaTeX\r\n configuration or environment variable, or `None` if not defined.\r\n\r\n* `TEXMF_OUTPUT_DIRECTORY() -> Self | None`: Path of `TEXMF_OUTPUT_DIRECTORY`\r\n from environment variable, or `None` if not defined.\r\n\r\n* `tex_roots() -> frozenset[Self]`: All root locations where TeX might write\r\n output, under default configuration with restricted access to the file\r\n system. This includes `tex_cwd()` plus `TEXMFOUTPUT()` and\r\n `TEXMF_OUTPUT_DIRECTORY()` if they are defined.\r\n\r\n* `tex_roots_resolved() -> frozenset[Self]`: Same as `tex_roots()` except\r\n all paths are resolved with the file system.\r\n\r\n* `tex_roots_with_resolved() -> frozenset[Self]`: Union of `tex_roots()` and\r\n `tex_roots_resolved()`.\r\n\r\n* `tex_openout_roots() -> tuple[Self]`: Locations where TeX will attempt to\r\n write with `\\openout`, in order. The first element of the tuple is\r\n `TEXMF_OUTPUT_DIRECTORY()` if not `None` and otherwise `tex_cwd()`. If\r\n `TEXMFOUTPUT()` is not `None` and is not already in the tuple, then it is\r\n the second element.\r\n\r\n TeX attempts to write to `TEXMFOUTPUT` (if defined) when the default write\r\n location (`TEXMF_OUTPUT_DIRECTORY` if defined, else TeX working directory)\r\n is read-only.\r\n\r\n* `tex_texmfoutput_roots() -> frozenset[Self]`: `TEXMFOUTPUT()` and/or\r\n `TEXMF_OUTPUT_DIRECTORY()` if they are defined.\r\n\r\n\r\n## Restricted subprocesses\r\n\r\nWhen LaTeX runs with restricted shell escape, only executables specified in\r\nTeX configuration can be executed via `\\ShellEscape`. The `latexrestricted`\r\npackage allows these same executables to run in subprocesses via\r\n`restricted_run()`. This is a wrapper around Python's\r\n[`subprocess.run()`](https://docs.python.org/3/library/subprocess.html#subprocess.run).\r\n\r\n```\r\nfrom latexrestricted import restricted_run\r\nrestricted_run(args: list[str], allow_restricted_executables: bool = False)\r\n```\r\n\r\n* It is *always* possible to run `kpsewhich` (including `miktex-kpsewhich`)\r\n and `initexmf`. These are necessary to access TeX configuration values.\r\n\r\n Running other executables allowed by TeX configuration for restricted shell\r\n escape requires the optional argument `allow_restricted_executables=True`.\r\n In this case, TeX configuration is checked to determine whether restricted\r\n shell escape is enabled, although this should be redundant if\r\n `latexrestricted` itself is being used in a restricted shell escape\r\n executable.\r\n\r\n* When `allow_restricted_executables=True`, the executable must be in the same\r\n directory as `kpsewhich` or `initexmf`, as previously located during TeX\r\n configuration detection, or the executable must exist on `PATH`, as found by\r\n Python's `shutil.which()`.\r\n\r\n The executable must not be in a location writable by LaTeX. For added\r\n security, locations writable by LaTeX cannot be under the executable parent\r\n directory.\r\n\r\n* The executable cannot be a batch file (no `*.bat` or `*.cmd`):\r\n https://docs.python.org/3/library/subprocess.html#security-considerations.\r\n This is enforced by requiring `*.exe` under Windows and completely\r\n prohibiting `*.bat` and `*.cmd` everywhere.\r\n\r\n* The subprocess runs with `shell=False`.\r\n\r\n`restricted_run()` will raise `latexrestricted.ExecutableNotFoundError` if an\r\nexecutable (`args[0]`) cannot be found in the same directory as `kpsewhich` or\r\n`initexmf`, or on `PATH`. It will raise\r\n`latexrestricted.UnapprovedExecutableError` when the executable is not in the\r\napproved list of executables from LaTeX configuration\r\n(`latex_config.restricted_shell_escape_commands`). It will raise\r\n`latexrestricted.ExecutablePathSecurityError` if the executable is found and\r\nis in the approved list, but is in an insecure location relative to locations\r\nwritable by LaTeX.\r\n\r\n\r\n\r\n## Security limitations with TeX Live and `TEXMFOUTPUT`\r\n\r\nTeX Live allows `TEXMFOUTPUT` to be set in a `texmf.cnf` config file. In this\r\ncase, `latexrestricted` will retrieve the value of `TEXMFOUTPUT` by running\r\n`kpsewhich --var-value TEXMFOUTPUT` in a subprocess. If the user has modified\r\n`TEXMFOUTPUT` to an unsafe value in a `texmf.cnf` config file, then the\r\n`kpsewhich` executable (and all other TeX-related executables) are potentially\r\ncompromised, and `latexrestricted` cannot detect this until *after* running\r\n`kpsewhich`.\r\n\r\nIt is possible to set `TEXMFOUTPUT` to unsafe values in a `texmf.cnf` config\r\nfile. For example, if `TEXMFOUTPUT` is set to a location in the file system\r\nthat contains executables, this could allow LaTeX documents to modify those\r\nexecutables or their resources. With TeX Live, `latexrestricted` retrieves\r\nthe value of `TEXMFOUTPUT` by running `kpsewhich`. However, the `kpsewhich`\r\nexecutable itself could be compromised if `TEXMFOUTPUT` is set to a directory\r\nthat contains the `kpsewhich` executable (or other parts of a TeX\r\ninstallation). If `latexrestricted` detects an unsafe value of `TEXMFOUTPUT`,\r\nit raises `latexrestricted.LatexConfigError`, but this is only possible\r\n*after* running the potentially compromised `kpsewhich` executable to obtain\r\nthe value of `TEXMFOUTPUT`. (And if `kpsewhich` is compromised, there is\r\nalways the possibility that it will not return the true value of\r\n`TEXMFOUTPUT`.)\r\n\r\nWhile raising a security-related error after running the potentially\r\ncompromised executable is not ideal, this will typically have a negligible\r\nimpact on overall security. If `TEXMFOUTPUT` is set to a directory that\r\ncontains the `kpsewhich` executable (or other parts of a TeX installation),\r\nthen all other TeX-related executables are also potentially compromised. If\r\n`latexrestricted` is being used in a Python executable designed for LaTeX\r\nshell escape, then presumably a LaTeX executable is already running, and LaTeX\r\nmay invoke additional trusted executables such as `kpsewhich` in shells.\r\nThus, before `latexrestricted` ever runs `kpsewhich` to retrieve the value of\r\n`TEXMFOUTPUT`, potentially compromised executables would already be running.\r\n",
"bugtrack_url": null,
"license": "latexrestricted Python package Copyright (c) 2024 Geoffrey M. Poore This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3c of this license or (at your option) any later version. The latest version of this license is in https://www.latex-project.org/lppl.txt and version 1.3c or later is part of all distributions of LaTeX version 2008 or later. This work has the LPPL maintenance status `maintained'. The Current Maintainer of this work is Geoffrey M. Poore. This work consists of the files in the latexrestricted Python package. ",
"summary": "Library for creating Python executables compatible with LaTeX restricted shell escape",
"version": "0.6.2",
"project_urls": {
"changelog": "https://github.com/gpoore/latexrestricted/blob/main/CHANGELOG.md",
"homepage": "https://github.com/gpoore/latexrestricted",
"repository": "https://github.com/gpoore/latexrestricted"
},
"split_keywords": [
"latex",
" security",
" restricted shell escape"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c9ab99b0f9516a529efa89e5d1d1abeba620d73beebcceeb5f50f3a01970c8e",
"md5": "4bd83ab7824cff8302fade973639de66",
"sha256": "993bcc1c2a0484e95ce8f167bd8ec19de18cc7386cdb2d1f55d839d036eed590"
},
"downloads": -1,
"filename": "latexrestricted-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bd83ab7824cff8302fade973639de66",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27202,
"upload_time": "2024-11-25T04:24:15",
"upload_time_iso_8601": "2024-11-25T04:24:15.823779Z",
"url": "https://files.pythonhosted.org/packages/3c/9a/b99b0f9516a529efa89e5d1d1abeba620d73beebcceeb5f50f3a01970c8e/latexrestricted-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69c25174b64463f9530c3d19c47606140b098b2ed6a6cb4ceac8c34b616bafdd",
"md5": "5baee23e1d5895948d0f34fa6525031d",
"sha256": "d51d21a41197a581ff29c0f818551f16fa0e6890def929799ac0bde762a7aa60"
},
"downloads": -1,
"filename": "latexrestricted-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "5baee23e1d5895948d0f34fa6525031d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28504,
"upload_time": "2024-11-25T04:24:19",
"upload_time_iso_8601": "2024-11-25T04:24:19.551578Z",
"url": "https://files.pythonhosted.org/packages/69/c2/5174b64463f9530c3d19c47606140b098b2ed6a6cb4ceac8c34b616bafdd/latexrestricted-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 04:24:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gpoore",
"github_project": "latexrestricted",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "latexrestricted"
}
