secretshield 0.13.0__tar.gz → 0.13.2__tar.gz

{secretshield-0.13.0/secretshield.egg-info → secretshield-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secretshield
-Version: 0.13.0
+Version: 0.13.2
 Summary: Stop secrets before they leak -- runtime redaction, multi-language scanning, auto-fix, Git hooks, and CI, all in one CLI.
 Author: Samarth Chugh (Sam3360)
 License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
 
 [![PyPI version](https://img.shields.io/pypi/v/secretshield?color=yellow)](https://pypi.org/project/secretshield/)
 [![Python versions](https://img.shields.io/pypi/pyversions/secretshield)](https://pypi.org/project/secretshield/)
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/secretshield?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=RED&left_text=downloads%2Fmonth)](https://pepy.tech/projects/secretshield)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/secretshield?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=ORANGE&left_text=downloads)](https://pepy.tech/projects/secretshield)
 [![License: MIT](https://img.shields.io/pypi/l/secretshield)](LICENSE)
 
 [Install](#install) · [Demo](#demo) · [Try it](#try-it) · [Homepage 🌐](https://therealsecretshield.freebuff.app/) · [Full usage guide →](https://github.com/Sam3360/secretshield/blob/main/USAGE.md)
@@ -56,6 +56,22 @@ gets that far.
 
 ## Install
 
+**Windows (recommended):** download `secretshield-windows-x64-setup.exe` from the
+[latest release](https://github.com/Sam3360/secretshield/releases/latest), run it, then open a
+**new** terminal and try:
+
+```powershell
+ss --version
+ss scan .
+```
+
+No Python needed, no administrator rights. A portable zip is also available, and Linux and macOS
+get a single-file binary. The builds are not code-signed, so Windows or macOS may show a warning:
+see the [installation guide](https://github.com/Sam3360/secretshield/blob/main/USAGE.md#installation)
+for checksums, upgrading, uninstalling and troubleshooting.
+
+**Python developers:**
+
 ```bash
 pip install secretshield
 ```
@@ -157,3 +173,14 @@ MIT — see [LICENSE](LICENSE).
 Visit the official SecretShield homepage for an overview of the project, features, releases, and more:
 
 **🌐 [therealsecretshield.freebuff.app](https://therealsecretshield.freebuff.app/)**
+
+
+## 🏆 Recognition
+
+SecretShield was recognised as **Best Developer Tool** in [Waycode's Founding 100](https://www.waycode.in/articles/founding-100-eight-projects-different-ideas-one-community-of-builders).
+
+Waycode's Founding 100 brought together builders and their projects, recognising eight projects across different categories.
+
+This recognition highlights SecretShield's work in open-source security tooling and local-first secret detection.
+
+**[Read the announcement →](https://www.waycode.in/articles/founding-100-eight-projects-different-ideas-one-community-of-builders)**

{secretshield-0.13.0 → secretshield-0.13.2}/README.md

@@ -6,7 +6,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/secretshield?color=yellow)](https://pypi.org/project/secretshield/)
 [![Python versions](https://img.shields.io/pypi/pyversions/secretshield)](https://pypi.org/project/secretshield/)
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/secretshield?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=RED&left_text=downloads%2Fmonth)](https://pepy.tech/projects/secretshield)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/secretshield?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=ORANGE&left_text=downloads)](https://pepy.tech/projects/secretshield)
 [![License: MIT](https://img.shields.io/pypi/l/secretshield)](LICENSE)
 
 [Install](#install) · [Demo](#demo) · [Try it](#try-it) · [Homepage 🌐](https://therealsecretshield.freebuff.app/) · [Full usage guide →](https://github.com/Sam3360/secretshield/blob/main/USAGE.md)
@@ -30,6 +30,22 @@ gets that far.
 
 ## Install
 
+**Windows (recommended):** download `secretshield-windows-x64-setup.exe` from the
+[latest release](https://github.com/Sam3360/secretshield/releases/latest), run it, then open a
+**new** terminal and try:
+
+```powershell
+ss --version
+ss scan .
+```
+
+No Python needed, no administrator rights. A portable zip is also available, and Linux and macOS
+get a single-file binary. The builds are not code-signed, so Windows or macOS may show a warning:
+see the [installation guide](https://github.com/Sam3360/secretshield/blob/main/USAGE.md#installation)
+for checksums, upgrading, uninstalling and troubleshooting.
+
+**Python developers:**
+
 ```bash
 pip install secretshield
 ```
@@ -131,3 +147,14 @@ MIT — see [LICENSE](LICENSE).
 Visit the official SecretShield homepage for an overview of the project, features, releases, and more:
 
 **🌐 [therealsecretshield.freebuff.app](https://therealsecretshield.freebuff.app/)**
+
+
+## 🏆 Recognition
+
+SecretShield was recognised as **Best Developer Tool** in [Waycode's Founding 100](https://www.waycode.in/articles/founding-100-eight-projects-different-ideas-one-community-of-builders).
+
+Waycode's Founding 100 brought together builders and their projects, recognising eight projects across different categories.
+
+This recognition highlights SecretShield's work in open-source security tooling and local-first secret detection.
+
+**[Read the announcement →](https://www.waycode.in/articles/founding-100-eight-projects-different-ideas-one-community-of-builders)**

{secretshield-0.13.0 → secretshield-0.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "secretshield"
-version = "0.13.0"
+version = "0.13.2"
 description = "Stop secrets before they leak -- runtime redaction, multi-language scanning, auto-fix, Git hooks, and CI, all in one CLI."
 readme = "README.md"
 license = "MIT"

{secretshield-0.13.0 → secretshield-0.13.2}/secretshield/__init__.py

@@ -23,7 +23,7 @@ from .detector import Match, detect
 from .guardian import disable, enable, is_enabled
 from .redactor import redact
 
-__version__ = "0.13.0"
+__version__ = "0.13.2"
 
 __all__ = [
     "__version__",

{secretshield-0.13.0 → secretshield-0.13.2}/secretshield/cli.py

@@ -20,8 +20,10 @@ the file happens to be ``.py``, ``.js``, or ``.env``.
 from __future__ import annotations
 
 import argparse
+import codecs
 import fnmatch
 import json
+import os
 import runpy
 import sys
 from pathlib import Path
@@ -29,6 +31,7 @@ from pathlib import Path
 from . import __version__, disable, enable, is_enabled
 from .color import green, hyperlink, red, supports_color
 from .detector import detect
+from .inline_ignore import filter_inline_ignored
 
 # --- File type support -----------------------------------------------------
 
@@ -272,6 +275,17 @@ def _cmd_run(args: argparse.Namespace) -> int:
         return int(exc.code) if isinstance(exc.code, int) else 1
     except Exception as exc:  # noqa: BLE001 - surface script errors to the user
         print(f"secretshield: script raised an exception: {exc}", file=sys.stderr)
+        if isinstance(exc, ImportError) and getattr(sys, "frozen", False):
+            # Only the standalone (PyInstaller) build: it bundles SecretShield's
+            # own runtime, not a full Python environment, so a script's other
+            # imports usually can't be found there.
+            print(
+                "secretshield: note: this is the standalone SecretShield build. It bundles "
+                "only the Python modules SecretShield itself needs, so `run` cannot import "
+                "other packages or standard-library modules. Use the pip-installed version "
+                "(pip install secretshield) to run scripts that need them.",
+                file=sys.stderr,
+            )
         return 1
     return 0
 
@@ -458,6 +472,27 @@ def _iter_scan_sources(args: argparse.Namespace, target: Path, include_patterns:
         yield display_path, _read_text_safe(file_path)
 
 
+def _history_sources(history, include_patterns: list, exclude_patterns: list, no_ignore: bool):
+    """Adapt a HistoryScan to the (display_path, text, first_line, commit) shape."""
+    from .history import HistoryError
+
+    def accept(relpath: str) -> bool:
+        path = Path(relpath)
+        # Same rules as the working-tree walk in _iter_scan_files.
+        if not no_ignore and any(part in _SKIP_DIR_NAMES for part in path.parts):
+            return False
+        if not no_ignore and _is_secretshield_meta_file(path.name):
+            return False
+        return _should_scan_file(path, include_patterns, exclude_patterns)
+
+    try:
+        for relpath, text, first_line, commit in history.iter_sources(accept):
+            yield str(Path(relpath)), text, first_line, commit
+    except HistoryError as exc:
+        print(f"secretshield: error: {exc}", file=sys.stderr)
+        history.failed = True
+
+
 def _run_scan(args: argparse.Namespace) -> int:
     from .baseline import (
         baseline_exists,
@@ -551,9 +586,38 @@ def _run_scan(args: argparse.Namespace) -> int:
         # that came from secretshield.toml.
         json_output = sarif_output = False
 
+    history_mode = bool(getattr(args, "history", False))
+    max_commits = getattr(args, "max_commits", None)
+    if max_commits is not None and not history_mode:
+        print("secretshield: error: --max-commits requires --history", file=sys.stderr)
+        return 2
+    if history_mode:
+        clash = None
+        if getattr(args, "staged", False):
+            clash = "--staged"
+        elif getattr(args, "diff", None):
+            clash = "--diff"
+        elif getattr(args, "fix", False):
+            clash = "--fix (a secret in a past commit can't be fixed in place)"
+        elif getattr(args, "baseline", False):
+            clash = "--baseline"
+        elif cli_format == "sarif":
+            clash = "--format sarif (history findings have no file location in the working tree)"
+        if clash:
+            print(f"secretshield: error: --history cannot be combined with {clash}", file=sys.stderr)
+            return 2
+        sarif_output = False  # a sarif default from secretshield.toml doesn't apply here
+
     target = Path(args.path)
     using_explicit_source = bool(getattr(args, "staged", False) or getattr(args, "diff", None))
 
+    if history_mode:
+        from .git import is_git_repo
+
+        if not is_git_repo():
+            print("secretshield: error: not inside a Git repository", file=sys.stderr)
+            return 2
+
     if using_explicit_source:
         from .git import is_git_repo
 
@@ -561,7 +625,7 @@ def _run_scan(args: argparse.Namespace) -> int:
             print("secretshield: error: not inside a Git repository", file=sys.stderr)
             return 2
 
-    if not using_explicit_source and not target.exists():
+    if not using_explicit_source and not history_mode and not target.exists():
         print(f"secretshield: error: no such path: {target}", file=sys.stderr)
         return 1
 
@@ -573,9 +637,36 @@ def _run_scan(args: argparse.Namespace) -> int:
     # endLine, endColumn). Keeps the tuple shape above (used by baseline
     # handling) unchanged and costs nothing for text/json scans.
     sarif_regions: dict[int, tuple[int, int, int, int]] = {}
-    show_progress = _progress_supported() and not (json_output or sarif_output)
-
-    for display_path, text in _iter_scan_sources(args, target, include_patterns, exclude_patterns):
+    show_progress = _progress_supported() and not (json_output or sarif_output or history_mode)
+    honor_inline_ignore = not getattr(args, "no_inline_ignore", False)
+    inline_ignored = 0
+
+    # --history: the same loop below runs over each historical hunk instead of
+    # each file, so every detector and filter behaves exactly as in a normal scan.
+    history = None
+    history_info: dict[int, str] = {}  # id(match) -> full commit hash
+    also_in: dict[int, int] = {}  # id(match) -> other commits containing it
+    if history_mode:
+        from .history import HistoryScan
+
+        pathspec = None if str(target) in (".", "") else str(target)
+        history = HistoryScan(Path.cwd(), pathspec=pathspec, max_commits=max_commits)
+        sources = _history_sources(history, include_patterns, exclude_patterns, args.no_ignore)
+    else:
+        sources = _iter_scan_sources(args, target, include_patterns, exclude_patterns)
+
+    def make_finding(file: str, line: int, match) -> dict:
+        entry = {"file": file, "line": line, "kind": match.kind}
+        commit = history_info.get(id(match))
+        if commit:
+            entry["commit"] = commit[:8]
+            if id(match) in also_in:
+                entry["also_in_commits"] = also_in[id(match)]
+        return entry
+
+    for source in sources:
+        display_path, text = source[0], source[1]
+        line_base = source[2] if len(source) > 2 else 1
         files_scanned += 1
         _progress_update(show_progress, files_scanned)
 
@@ -585,11 +676,18 @@ def _run_scan(args: argparse.Namespace) -> int:
                 m for m in scan_text_with_rules(text, custom_rules) if not _is_placeholder(m.value)
             ]
             file_matches = file_matches + custom_matches
+        if honor_inline_ignore and file_matches:
+            # Applied before everything downstream (baseline, fix, rotate,
+            # JSON/SARIF), so a suppressed finding is simply never seen.
+            file_matches, suppressed = filter_inline_ignored(text, file_matches)
+            inline_ignored += suppressed
         if file_matches:
             matches_by_file[display_path] = file_matches
         for match in file_matches:
-            line_no = _line_number_for_offset(text, match.start)
-            all_findings.append({"file": display_path, "line": line_no, "kind": match.kind})
+            line_no = _line_number_for_offset(text, match.start) + line_base - 1
+            if history is not None:
+                history_info[id(match)] = source[3]
+            all_findings.append(make_finding(display_path, line_no, match))
             matches_with_context.append((display_path, line_no, match))
             if sarif_output:
                 from .sarif import compute_region
@@ -598,6 +696,21 @@ def _run_scan(args: argparse.Namespace) -> int:
 
     _progress_clear(show_progress)
 
+    if history is not None:
+        if history.failed:
+            return 2
+        from .history import dedupe_oldest
+
+        matches_with_context, also_in_found = dedupe_oldest(
+            matches_with_context, history_info, history.rank
+        )
+        also_in.update(also_in_found)
+        matches_with_context.sort(key=lambda item: (item[0], item[1], item[2].kind))
+        matches_by_file = {}
+        for file, _line, m in matches_with_context:
+            matches_by_file.setdefault(file, []).append(m)
+        all_findings = [make_finding(*item) for item in matches_with_context]
+
     project_root = Path.cwd()
 
     # --baseline: write a fresh baseline capturing every current finding,
@@ -614,6 +727,11 @@ def _run_scan(args: argparse.Namespace) -> int:
         ]
         path = write_baseline(project_root, baseline_findings)
         print(f"\u2713 Baseline written to {path} ({len(baseline_findings)} finding(s))")
+        if inline_ignored:
+            print(
+                f"\u2713 {inline_ignored} finding(s) suppressed by inline ignore "
+                "comments (not added to the baseline)"
+            )
         return 0
 
     ignored_by_baseline = 0
@@ -633,9 +751,7 @@ def _run_scan(args: argparse.Namespace) -> int:
             new_matches_by_file.setdefault(file, []).append(m)
         matches_by_file = new_matches_by_file
         matches_with_context = kept_context
-        all_findings = [
-            {"file": file, "line": line, "kind": m.kind} for file, line, m in matches_with_context
-        ]
+        all_findings = [make_finding(file, line, m) for file, line, m in matches_with_context]
 
     if getattr(args, "rotate", False):
         from .rotation import run_rotation
@@ -646,12 +762,19 @@ def _run_scan(args: argparse.Namespace) -> int:
             tree_args = argparse.Namespace(staged=False, diff=None, no_ignore=args.no_ignore)
             return _iter_scan_sources(tree_args, Path.cwd(), [], exclude_patterns)
 
+        rotate_findings = matches_with_context
+        if history is not None:
+            rotate_findings = [
+                (f"{file} @ {history_info[id(m)][:8]}", line, m)
+                for file, line, m in matches_with_context
+            ]
         rotation = run_rotation(
             project_root,
-            matches_with_context,
+            rotate_findings,
             entropy_threshold=entropy_threshold,
             custom_rules=custom_rules,
             iter_sources=_working_tree_sources,
+            allow_autofix=history is None,
         )
         return rotation.exit_code
 
@@ -677,13 +800,24 @@ def _run_scan(args: argparse.Namespace) -> int:
         )
 
     if json_output:
-        payload = {
-            "files_scanned": files_scanned,
-            "matches": all_findings,
-            "secrets_found": len(all_findings),
-        }
+        if history is not None:
+            payload = {
+                "commits_scanned": history.commits_scanned,
+                "matches": all_findings,
+                "secrets_found": len(all_findings),
+            }
+            if history.max_commits_reached:
+                payload["max_commits_reached"] = True
+        else:
+            payload = {
+                "files_scanned": files_scanned,
+                "matches": all_findings,
+                "secrets_found": len(all_findings),
+            }
         if ignored_by_baseline:
             payload["ignored_by_baseline"] = ignored_by_baseline
+        if inline_ignored:
+            payload["inline_ignored"] = inline_ignored
         report = json.dumps(payload, indent=2)
         if output_file is not None:
             written = _write_report(output_file, report + "\n", "JSON")
@@ -701,7 +835,12 @@ def _run_scan(args: argparse.Namespace) -> int:
         label, category = _kind_display(finding["kind"])
         print(f"{red(chr(0x2717), use_color)} {finding['file']}:{finding['line']}")
         print(f"  Potential secret: {label}")
-        print(f"  Type: {category}\n")
+        print(f"  Type: {category}")
+        if "commit" in finding:
+            more = finding.get("also_in_commits")
+            suffix = f" (also in {more} other commit(s))" if more else ""
+            print(f"  Commit: {finding['commit']}{suffix}")
+        print()
 
     if ignored_by_baseline:
         print(
@@ -709,11 +848,32 @@ def _run_scan(args: argparse.Namespace) -> int:
             f"{ignored_by_baseline} existing finding(s) ignored by baseline"
         )
 
+    if inline_ignored:
+        print(
+            f"{green(chr(0x2713), use_color)} "
+            f"{inline_ignored} finding(s) suppressed by inline ignore comments"
+        )
+
+    scanned_label = (
+        _plural(history.commits_scanned, "commit") + " scanned"
+        if history is not None
+        else f"{files_scanned} files scanned"
+    )
+    if history is not None and history.max_commits_reached:
+        print(
+            f"{green(chr(0x2713), use_color)} Stopped after {max_commits} commit(s) "
+            "(--max-commits); older history was not scanned"
+        )
     if all_findings:
-        print(f"{green(chr(0x2713), use_color)} {files_scanned} files scanned")
+        print(f"{green(chr(0x2713), use_color)} {scanned_label}")
         print(f"{red(chr(0x2717), use_color)} {len(all_findings)} potential secret(s) found")
+        if history is not None:
+            print(
+                "\nRemoving a secret from history does not make it safe: revoke it with its "
+                "provider.\nRun `secretshield scan --history --rotate` to be guided through that."
+            )
     else:
-        print(f"{green(chr(0x2713), use_color)} {files_scanned} files scanned")
+        print(f"{green(chr(0x2713), use_color)} {scanned_label}")
         print(f"{green(chr(0x2713), use_color)} No potential secrets found")
 
     exit_code = 1 if all_findings else 0
@@ -797,6 +957,8 @@ def _run_scan_staged(args: argparse.Namespace) -> int:
     print("SecretShield: scanning staged files...\n")
 
     findings: list[dict] = []
+    honor_inline_ignore = not getattr(args, "no_inline_ignore", False)
+    inline_ignored = 0
     for relpath in get_staged_files():
         path = Path(relpath)
         if _is_secretshield_meta_file(path.name):
@@ -810,9 +972,11 @@ def _run_scan_staged(args: argparse.Namespace) -> int:
             matches = detect(content, entropy_threshold=args.entropy_threshold)
         except Exception:
             continue
+        matches = [m for m in matches if not _is_placeholder(m.value)]
+        if honor_inline_ignore and matches:
+            matches, suppressed = filter_inline_ignored(content, matches)
+            inline_ignored += suppressed
         for match in matches:
-            if _is_placeholder(match.value):
-                continue
             label, _category = _kind_display(match.kind)
             findings.append(
                 {
@@ -824,6 +988,12 @@ def _run_scan_staged(args: argparse.Namespace) -> int:
 
     use_color = supports_color(sys.stdout)
 
+    if inline_ignored:
+        print(
+            f"{green(chr(0x2713), use_color)} "
+            f"{inline_ignored} finding(s) suppressed by inline ignore comments\n"
+        )
+
     if not findings:
         print(f"{green(chr(0x2713), use_color)} No secrets detected.")
         return 0
@@ -1339,6 +1509,31 @@ def build_parser() -> argparse.ArgumentParser:
             "__pycache__, .venv, venv, dist, build, coverage, etc.)."
         ),
     )
+    scan_parser.add_argument(
+        "--no-inline-ignore",
+        action="store_true",
+        help=(
+            "Report findings even on lines marked `secretshield:ignore` or "
+            "`secretshield:ignore-next-line`. Use it to audit what inline "
+            "ignore comments are hiding."
+        ),
+    )
+    scan_parser.add_argument(
+        "--history",
+        action="store_true",
+        help=(
+            "Scan every commit in the repository's Git history (all refs) for "
+            "secrets that were ever added, including ones since deleted from "
+            "the working tree. Reports the commit that introduced each one. "
+            "Local and read-only."
+        ),
+    )
+    scan_parser.add_argument(
+        "--max-commits",
+        type=_positive_int,
+        metavar="N",
+        help="With --history, scan only the N most recent commits.",
+    )
     scan_parser.add_argument(
         "--fix",
         action="store_true",
@@ -1404,6 +1599,11 @@ def build_parser() -> argparse.ArgumentParser:
         default=4.2,
         help="Shannon entropy threshold for generic secret detection (default: 4.2).",
     )
+    scan_staged_parser.add_argument(
+        "--no-inline-ignore",
+        action="store_true",
+        help="Report findings even on lines marked `secretshield:ignore`.",
+    )
     scan_staged_parser.set_defaults(func=_cmd_scan_staged)
 
     install_hook_parser = subparsers.add_parser(
@@ -1478,7 +1678,81 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _positive_int(value: str) -> int:
+    try:
+        number = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{value!r} is not a whole number") from None
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be 1 or more")
+    return number
+
+
+# The marks this CLI prints plus a non-ASCII file-name sample. A stream whose
+# encoding and error handler can't encode all of them would crash on a clean
+# scan (U+2713/U+2717 exist in no legacy Windows code page).
+_OUTPUT_PROBE = "\u2713\u2717\u5bc6\u043a"
+
+
+def _explicit_io_error_handler() -> bool:
+    """True if PYTHONIOENCODING names a handler (``encoding:handler``).
+
+    That is the one case where the user asked for a specific handler, even a
+    strict one; anywhere else the handler is just whatever default the
+    interpreter picked.
+    """
+    return bool(os.environ.get("PYTHONIOENCODING", "").partition(":")[2].strip())
+
+
+def _stream_would_crash_on_unicode(stream) -> bool:
+    """Would printing this CLI's symbols raise UnicodeEncodeError on `stream`?
+
+    Decided by actually encoding a sample with the stream's own encoding and
+    error handler, not by the handler's name: ``strict`` raises, and so does
+    ``surrogateescape`` (a common default, including in embedded/frozen
+    interpreters) for any ordinary character the encoding lacks, while a UTF-8
+    stream of any handler is fine.
+    """
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        return True  # unknown: be safe
+    try:
+        codecs.lookup(encoding).incrementalencoder(getattr(stream, "errors", None) or "strict").encode(
+            _OUTPUT_PROBE
+        )
+    except UnicodeEncodeError:
+        return True
+    except (LookupError, TypeError, ValueError):
+        return True
+    return False
+
+
+def _tolerate_unencodable_output() -> None:
+    """Never crash just because the output encoding can't represent a symbol.
+
+    Redirected or piped output on Windows uses a legacy code page (cp1252,
+    cp437, ...) that can't encode the check/cross marks this CLI prints, and
+    a plain `print()` then raises UnicodeEncodeError, even for a clean scan.
+    For a stream that would crash, switch only the *error handler* to
+    "replace" (Python's documented behavior: the character becomes `?`).
+
+    Left alone: a stream that can already encode the output (UTF-8, whatever
+    its handler), and any stream when the user named a handler themselves with
+    ``PYTHONIOENCODING=encoding:handler``.
+    """
+    if _explicit_io_error_handler():
+        return
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure) and _stream_would_crash_on_unicode(stream):
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass  # a stream that can't be reconfigured keeps its behavior
+
+
 def main(argv: list[str] | None = None) -> int:
+    _tolerate_unencodable_output()
     parser = build_parser()
     args = parser.parse_args(argv)