TEXT-SAFETY-SCAN(1)

NAME
text-safety-scan - Run all configured text-safety plugins across files or stdin

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).