text-safety-scan(1) -- Run all configured text-safety plugins across files or stdin
========================================================================================

<!--
# Copyright (C) 2026 - 2026 ENCRYPTED SUPPORT LLC <adrelanos@whonix.org>
# See the file COPYING for copying conditions.
-->

<!--
# AI-Assisted
-->

## SYNOPSIS

`text-safety-scan` [`--help`] [`--`] [*PATH*...]

`text-safety-scan` < *input*

## DESCRIPTION

Runs every configured text-safety plugin (currently
`unicode-show`(1) and `modeline-show`(1)) against each path argument
or against stdin. All plugins run for every input even if an earlier
plugin reports a finding, so a single invocation gives a complete
picture.

This tool intentionally does NOT do directory recursion, MIME
classification, VCS pruning, or symlink filtering. For directory
trees, use `text-safety-scan-find`(1).

## OPTIONS

* `-h`, `--help`
  Show usage and exit 0.

* `--`
  End of options. Remaining arguments are paths. Required if a path
  begins with `-`. Plugins handle leading-dash paths natively
  (`unicode-show` iterates `argv` then `open()`; `modeline-show`
  forwards via `grep --`).

## EXIT CODES

* `0`
  All plugins clean for all inputs.

* `1`
  At least one plugin reported a finding (e.g. a Unicode hit or a
  Vim/Emacs modeline).

* `2`
  Hard error. Reasons include: an input does not exist, an input is
  a directory, a plugin is not installed, stdin capture failed, etc.

## EXAMPLES

Scan a single file:

    text-safety-scan ./changelog

Scan multiple files explicitly:

    text-safety-scan ./README ./CHANGELOG ./LICENSE

Scan stdin:

    cat ./suspicious.txt | text-safety-scan
    curl -fsSL https://example.invalid/script.sh | text-safety-scan

Scan a file whose name begins with a hyphen:

    text-safety-scan -- --weird-name

Scan a tree, using find for the recursion (this is what
`text-safety-scan-find`(1) does internally):

    find /repo -type f -print0 | xargs -0 -r text-safety-scan --

Scan a tree but skip the `.git` directory and `*.png` images:

    find /repo -not -path '*/.git/*' -not -name '*.png' -type f -print0 \
      | xargs -0 -r text-safety-scan --

## SECURITY MODEL

`text-safety-scan` is for AUDITING content, not for hardening
against an attacker who can race the scanner. Specifically:

* It is trivial for a scanned file to have malicious text added to it after
  or even during the scan.
* Symlink arguments are followed (`open()` follows links by default).
  The user explicitly passed the path; we defer to that.
* Semantic text content (such as HTML tags, source code, CI annotations, etc.)
  are not sanitized out before being echoed. However, paths are routed through
  `printf %q` before logging, so they cannot inject control characters or shell
  special characters into the output.

The intended deployment is: the caller extracts an archive (or
checks out a tree) into a directory the attacker cannot write to
during the scan, then runs `text-safety-scan`(1).

## SEE ALSO

text-safety-scan-find(1), unicode-show(1), modeline-show(1),
grep-find-unicode-wrapper(1), find(1), xargs(1)

## AUTHOR

This man page has been written by Patrick Schleizer (adrelanos@whonix.org).
