secretshield 0.1.0__py3-none-any.whl

secretshield/__init__.py

@@ -0,0 +1,44 @@
+"""
+secretshield: detect and redact likely secrets before they reach
+Python's terminal output or logging system.
+
+Importing this package automatically enables protection for
+``sys.stdout``, ``sys.stderr``, and the standard ``logging`` module::
+
+    import secretshield
+
+    api_key = "example-secret-value"
+    print("API key:", api_key)
+    # API key: ********
+    # \u26a0 secretshield: Potential secret detected and redacted.
+
+Protection can be toggled manually with :func:`enable` / :func:`disable`,
+and behavior can be tuned with :func:`configure`.
+"""
+
+from __future__ import annotations
+
+from .config import Config, configure, get_config, reset_config
+from .detector import Match, detect
+from .guardian import disable, enable, is_enabled
+from .redactor import redact
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "enable",
+    "disable",
+    "is_enabled",
+    "configure",
+    "get_config",
+    "reset_config",
+    "Config",
+    "detect",
+    "redact",
+    "Match",
+]
+
+# Automatically protect stdout/stderr/logging as soon as secretshield is
+# imported, per the tool's core promise: "import it and you're protected."
+enable()

secretshield/cli.py

@@ -0,0 +1,168 @@
+"""
+Command-line interface for secretshield.
+
+Provides two commands:
+
+* ``secretshield run <script.py> [args...]`` -- run a Python script with
+  secretshield protection enabled for stdout/stderr/logging.
+* ``secretshield scan <path>`` -- scan a text file (or directory of text
+  files) for likely secrets without executing anything. This is a static
+  scan, distinct from runtime protection.
+"""
+
+from __future__ import annotations
+
+import argparse
+import runpy
+import sys
+from pathlib import Path
+
+from . import __version__
+from .detector import detect
+
+# Reasonable default set of extensions to consider "text" when scanning a
+# directory. Binary files and common non-source directories are skipped.
+_SCAN_EXTENSIONS = {
+    ".py", ".txt", ".md", ".env", ".yml", ".yaml", ".json",
+    ".ini", ".cfg", ".toml", ".sh", ".js", ".ts",
+}
+_SKIP_DIR_NAMES = {".git", "__pycache__", "node_modules", ".venv", "venv"}
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    script_path = Path(args.script)
+    if not script_path.is_file():
+        print(f"secretshield: error: no such file: {script_path}", file=sys.stderr)
+        return 1
+
+    # Enable protection for the duration of the script's execution.
+    from . import enable
+
+    enable()
+
+    # Make the script's own arguments available to it via sys.argv, and
+    # ensure its directory is importable the way `python script.py` would.
+    sys.argv = [str(script_path), *args.script_args]
+    script_dir = str(script_path.resolve().parent)
+    if script_dir not in sys.path:
+        sys.path.insert(0, script_dir)
+
+    try:
+        runpy.run_path(str(script_path), run_name="__main__")
+    except SystemExit as exc:
+        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)
+        return 1
+    return 0
+
+
+def _scan_text(text: str, entropy_threshold: float) -> list[str]:
+    findings = []
+    try:
+        matches = detect(text, entropy_threshold=entropy_threshold)
+    except Exception:
+        return findings
+    for match in matches:
+        findings.append(f"  - {match.kind} at offset {match.start}-{match.end}")
+    return findings
+
+
+def _iter_scan_files(root: Path):
+    if root.is_file():
+        yield root
+        return
+    for path in root.rglob("*"):
+        if any(part in _SKIP_DIR_NAMES for part in path.parts):
+            continue
+        if path.is_file() and path.suffix.lower() in _SCAN_EXTENSIONS:
+            yield path
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    target = Path(args.path)
+    if not target.exists():
+        print(f"secretshield: error: no such path: {target}", file=sys.stderr)
+        return 1
+
+    total_findings = 0
+    for file_path in _iter_scan_files(target):
+        try:
+            text = file_path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            continue
+
+        findings = _scan_text(text, entropy_threshold=args.entropy_threshold)
+        if findings:
+            total_findings += len(findings)
+            print(f"{file_path}")
+            for line in findings:
+                print(line)
+
+    if total_findings == 0:
+        print("secretshield: scan complete, no potential secrets found.")
+    else:
+        print(
+            f"\nsecretshield: scan complete, {total_findings} potential "
+            "secret(s) found."
+        )
+    return 1 if total_findings else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="secretshield",
+        description=(
+            "secretshield: detect and redact likely secrets before they "
+            "reach Python's terminal output or logging system."
+        ),
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"secretshield {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    run_parser = subparsers.add_parser(
+        "run", help="Run a Python script with secretshield protection enabled."
+    )
+    run_parser.add_argument("script", help="Path to the Python script to run.")
+    run_parser.add_argument(
+        "script_args",
+        nargs=argparse.REMAINDER,
+        help="Arguments to pass through to the script.",
+    )
+    run_parser.set_defaults(func=_cmd_run)
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help=(
+            "Statically scan a file or directory of text files for "
+            "potential secrets (does not execute anything)."
+        ),
+    )
+    scan_parser.add_argument("path", help="File or directory to scan.")
+    scan_parser.add_argument(
+        "--entropy-threshold",
+        type=float,
+        default=4.2,
+        help="Shannon entropy threshold for generic secret detection (default: 4.2).",
+    )
+    scan_parser.set_defaults(func=_cmd_scan)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

secretshield/config.py

@@ -0,0 +1,57 @@
+"""
+Configuration for secretshield.
+
+A single module-level :class:`Config` instance holds the active settings.
+Use :func:`configure` to update it; :func:`get_config` to read it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    """Runtime configuration for secretshield."""
+
+    enabled: bool = True
+    redact_with: str = "********"
+    entropy_threshold: float = 4.2
+    notify: bool = True
+
+
+_config = Config()
+
+
+def configure(
+    enabled: bool | None = None,
+    redact_with: str | None = None,
+    entropy_threshold: float | None = None,
+    notify: bool | None = None,
+) -> Config:
+    """
+    Update the active configuration. Only provided (non-None) fields are
+    changed; omitted fields keep their current value.
+    """
+    global _config
+    if enabled is not None:
+        _config.enabled = enabled
+    if redact_with is not None:
+        _config.redact_with = redact_with
+    if entropy_threshold is not None:
+        _config.entropy_threshold = entropy_threshold
+    if notify is not None:
+        _config.notify = notify
+    return _config
+
+
+def get_config() -> Config:
+    """Return the current active :class:`Config` instance."""
+    return _config
+
+
+def reset_config() -> Config:
+    """Reset configuration back to defaults. Primarily useful for tests."""
+    global _config
+    _config = Config()
+    return _config

secretshield/detector.py

@@ -0,0 +1,125 @@
+"""
+Secret detection logic.
+
+Combines pattern-based matching (for well-known secret formats) with a
+generic high-entropy scan (for random-looking tokens that don't match a
+known shape). Entropy detection is intentionally conservative and is used
+as a supplement, never as the sole detection strategy, to avoid excessive
+false positives.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from . import patterns
+
+
+@dataclass(frozen=True)
+class Match:
+    """A single detected secret span within a piece of text."""
+
+    start: int
+    end: int
+    value: str
+    kind: str
+
+    def __len__(self) -> int:
+        return self.end - self.start
+
+
+def _shannon_entropy(s: str) -> float:
+    """Return the Shannon entropy (bits per character) of a string."""
+    if not s:
+        return 0.0
+    freq: dict[str, int] = {}
+    for ch in s:
+        freq[ch] = freq.get(ch, 0) + 1
+    length = len(s)
+    entropy = 0.0
+    for count in freq.values():
+        p = count / length
+        entropy -= p * math.log2(p)
+    return entropy
+
+
+def _looks_like_real_candidate(token: str) -> bool:
+    """Filter out obvious non-secrets before running entropy checks."""
+    lowered = token.lower()
+    if any(word in lowered for word in patterns.ENTROPY_ALLOWLIST_SUBSTRINGS):
+        return False
+    # Skip strings composed of a single repeated character or simple runs.
+    if len(set(token)) <= 2:
+        return False
+    # Skip pure digit sequences (phone numbers, IDs, timestamps, etc.)
+    if token.isdigit():
+        return False
+    return True
+
+
+def _pattern_matches(text: str) -> list[Match]:
+    matches: list[Match] = []
+    for name, regex in patterns.PATTERNS:
+        for m in regex.finditer(text):
+            if name == "generic_labeled_secret":
+                # Only redact the captured value, not the label/key name.
+                start, end = m.span(patterns.GENERIC_VALUE_GROUP)
+                value = m.group(patterns.GENERIC_VALUE_GROUP)
+            else:
+                start, end = m.span()
+                value = m.group()
+            if not value:
+                continue
+            matches.append(Match(start=start, end=end, value=value, kind=name))
+    return matches
+
+
+def _entropy_matches(text: str, threshold: float) -> list[Match]:
+    matches: list[Match] = []
+    for m in patterns.ENTROPY_CANDIDATE_RE.finditer(text):
+        token = m.group()
+        if not _looks_like_real_candidate(token):
+            continue
+        entropy = _shannon_entropy(token)
+        if entropy >= threshold:
+            matches.append(
+                Match(start=m.start(), end=m.end(), value=token, kind="high_entropy")
+            )
+    return matches
+
+
+def _merge_overlapping(matches: list[Match]) -> list[Match]:
+    """Merge/deduplicate overlapping spans, keeping the widest match."""
+    if not matches:
+        return []
+    ordered = sorted(matches, key=lambda m: (m.start, -(m.end - m.start)))
+    merged: list[Match] = [ordered[0]]
+    for current in ordered[1:]:
+        last = merged[-1]
+        if current.start < last.end:
+            # Overlaps with previous match; keep whichever is wider.
+            if (current.end - current.start) > (last.end - last.start):
+                merged[-1] = current
+            continue
+        merged.append(current)
+    return merged
+
+
+def detect(text: str, entropy_threshold: float = 4.2) -> list[Match]:
+    """
+    Detect likely secrets within ``text``.
+
+    Returns a list of :class:`Match` objects sorted by position. This
+    combines known-pattern detection with generic high-entropy detection.
+    Overlapping matches are merged so a single secret isn't reported twice.
+    """
+    if not text:
+        return []
+    try:
+        found = _pattern_matches(text)
+        found.extend(_entropy_matches(text, entropy_threshold))
+    except Exception:
+        # Detection must never crash the host application.
+        return []
+    return _merge_overlapping(found)

secretshield/guardian.py

@@ -0,0 +1,222 @@
+"""
+Core guardian logic: wraps sys.stdout/sys.stderr and the logging module so
+that secrets are redacted before they are ever written out.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any, TextIO
+
+from . import notifications
+from .config import get_config
+from .redactor import redact
+
+# Sentinel attribute used to mark a stream as already wrapped, so repeated
+# enable() calls don't stack wrappers on top of each other.
+_WRAPPED_MARKER = "_secretshield_wrapped"
+
+# Module-level state tracking whether protection is currently active and
+# what the original (unwrapped) streams / logging factory were, so
+# disable() can cleanly restore them.
+_state: dict[str, Any] = {
+    "active": False,
+    "orig_stdout": None,
+    "orig_stderr": None,
+}
+
+# Guard against re-entrant redaction triggered by secretshield's own
+# console warnings being written through a wrapped stream.
+_in_write = False
+
+
+class _GuardedStream:
+    """A drop-in replacement for a text stream that redacts secrets."""
+
+    def __init__(self, wrapped: TextIO) -> None:
+        self._wrapped = wrapped
+        setattr(self, _WRAPPED_MARKER, True)
+
+    def write(self, s: str) -> int:
+        global _in_write
+        config = get_config()
+
+        if not config.enabled or _in_write:
+            return self._wrapped.write(s)
+
+        _in_write = True
+        try:
+            safe_text, was_redacted = redact(
+                s,
+                entropy_threshold=config.entropy_threshold,
+                redact_with=config.redact_with,
+            )
+        except Exception:
+            # Never let a detection failure prevent output entirely.
+            safe_text, was_redacted = s, False
+        finally:
+            _in_write = False
+
+        result = self._wrapped.write(safe_text)
+
+        if was_redacted and config.notify:
+            notifications.notify_console()
+
+        return result
+
+    def flush(self) -> None:
+        self._wrapped.flush()
+
+    def isatty(self) -> bool:
+        try:
+            return self._wrapped.isatty()
+        except Exception:
+            return False
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate any other attribute access (encoding, buffer, etc.) to
+        # the wrapped stream so behavior stays consistent with a normal
+        # file-like object.
+        return getattr(self._wrapped, name)
+
+
+def _wrap_stream(stream: TextIO) -> TextIO:
+    if getattr(stream, _WRAPPED_MARKER, False):
+        return stream
+    return _GuardedStream(stream)
+
+
+def _redact_record(record: logging.LogRecord) -> None:
+    """Redact secrets from a LogRecord's msg and args, in place."""
+    config = get_config()
+    if not config.enabled:
+        return
+
+    try:
+        redacted_any = False
+
+        if isinstance(record.msg, str):
+            new_msg, changed = redact(
+                record.msg,
+                entropy_threshold=config.entropy_threshold,
+                redact_with=config.redact_with,
+            )
+            record.msg = new_msg
+            redacted_any = redacted_any or changed
+
+        if record.args:
+            if isinstance(record.args, dict):
+                new_args = {}
+                for key, value in record.args.items():
+                    if isinstance(value, str):
+                        new_value, changed = redact(
+                            value,
+                            entropy_threshold=config.entropy_threshold,
+                            redact_with=config.redact_with,
+                        )
+                        new_args[key] = new_value
+                        redacted_any = redacted_any or changed
+                    else:
+                        new_args[key] = value
+                record.args = new_args
+            else:
+                new_args = []
+                for value in record.args:
+                    if isinstance(value, str):
+                        new_value, changed = redact(
+                            value,
+                            entropy_threshold=config.entropy_threshold,
+                            redact_with=config.redact_with,
+                        )
+                        new_args.append(new_value)
+                        redacted_any = redacted_any or changed
+                    else:
+                        new_args.append(value)
+                record.args = tuple(new_args)
+
+        if redacted_any and config.notify:
+            notifications.notify_console()
+
+    except Exception:
+        # Logging must never break because of a detection failure.
+        pass
+
+
+# We protect logging by wrapping the global LogRecord factory rather than
+# using a Filter. Filters attached to a specific Logger (e.g. the root
+# logger) are only consulted by the logger that originated the call, so a
+# filter on the root logger would NOT see records from child loggers
+# (logging.getLogger(__name__).warning(...)). The record factory, on the
+# other hand, is invoked for every LogRecord created anywhere in the
+# process, which gives us reliable, hierarchy-independent coverage.
+_log_filter_installed = False
+_orig_log_record_factory = None
+
+
+def _guarded_log_record_factory(*args: Any, **kwargs: Any) -> logging.LogRecord:
+    record = _orig_log_record_factory(*args, **kwargs)  # type: ignore[misc]
+    _redact_record(record)
+    return record
+
+
+def _install_logging_protection() -> None:
+    global _log_filter_installed, _orig_log_record_factory
+    if _log_filter_installed:
+        return
+    _orig_log_record_factory = logging.getLogRecordFactory()
+    logging.setLogRecordFactory(_guarded_log_record_factory)
+    _log_filter_installed = True
+
+
+def _remove_logging_protection() -> None:
+    global _log_filter_installed, _orig_log_record_factory
+    if _log_filter_installed and _orig_log_record_factory is not None:
+        logging.setLogRecordFactory(_orig_log_record_factory)
+    _orig_log_record_factory = None
+    _log_filter_installed = False
+
+
+def enable() -> None:
+    """
+    Enable secretshield protection for ``sys.stdout``, ``sys.stderr``, and
+    the standard ``logging`` module. Safe to call multiple times; repeated
+    calls do not create duplicate wrappers.
+    """
+    if _state["active"]:
+        return
+
+    _state["orig_stdout"] = sys.stdout
+    _state["orig_stderr"] = sys.stderr
+
+    sys.stdout = _wrap_stream(sys.stdout)
+    sys.stderr = _wrap_stream(sys.stderr)
+
+    _install_logging_protection()
+
+    _state["active"] = True
+
+
+def disable() -> None:
+    """
+    Disable secretshield protection, restoring the original ``sys.stdout``
+    and ``sys.stderr`` streams and removing the logging filter.
+    """
+    if not _state["active"]:
+        return
+
+    if _state["orig_stdout"] is not None:
+        sys.stdout = _state["orig_stdout"]
+    if _state["orig_stderr"] is not None:
+        sys.stderr = _state["orig_stderr"]
+
+    _remove_logging_protection()
+
+    _state["orig_stdout"] = None
+    _state["orig_stderr"] = None
+    _state["active"] = False
+
+
+def is_enabled() -> bool:
+    """Return True if secretshield protection is currently active."""
+    return bool(_state["active"])

secretshield/notifications.py

@@ -0,0 +1,73 @@
+"""
+Notification system for secretshield.
+
+Notifications never include the detected secret value, only a generic
+warning. Desktop notifications are best-effort and optional: if the
+underlying OS mechanism is unavailable, failures are swallowed silently
+so the host application is never disrupted.
+"""
+
+from __future__ import annotations
+
+import sys
+
+WARNING_MESSAGE = "\u26a0 secretshield: Potential secret detected and redacted."
+
+# Guards against recursive notification loops (e.g. a notification
+# triggering logging which triggers detection which triggers another
+# notification).
+_in_notification = False
+
+
+def notify_console(stream=None) -> None:
+    """
+    Print the safe warning message to the given stream (defaults to the
+    *original*, unwrapped stderr to avoid re-triggering detection).
+    """
+    global _in_notification
+    if _in_notification:
+        return
+    _in_notification = True
+    try:
+        target = stream if stream is not None else sys.__stderr__
+        if target is None:
+            return
+        target.write(WARNING_MESSAGE + "\n")
+        target.flush()
+    except Exception:
+        # Notifications must never crash the host application.
+        pass
+    finally:
+        _in_notification = False
+
+
+def notify_desktop(title: str = "secretshield", message: str = WARNING_MESSAGE) -> None:
+    """
+    Best-effort desktop notification. Optional and silent on failure.
+    Does not perform any network activity. If no desktop notification
+    backend is available, this is a no-op.
+    """
+    try:
+        import subprocess  # local import: only needed for this optional path
+
+        if sys.platform == "darwin":
+            script = f'display notification "{message}" with title "{title}"'
+            subprocess.run(
+                ["osascript", "-e", script],
+                check=False,
+                capture_output=True,
+                timeout=2,
+            )
+        elif sys.platform.startswith("linux"):
+            subprocess.run(
+                ["notify-send", title, message],
+                check=False,
+                capture_output=True,
+                timeout=2,
+            )
+        # Other platforms (e.g. Windows) are intentionally no-ops unless a
+        # user wires up their own backend; failing silently is preferred
+        # over adding heavier optional dependencies.
+    except Exception:
+        # Desktop notifications are optional; never let this raise.
+        pass

secretshield/patterns.py

@@ -0,0 +1,102 @@
+"""
+Regex patterns used to detect well-known secret formats.
+
+Each entry in ``PATTERNS`` is a tuple of ``(name, compiled_regex)``. These
+patterns intentionally target *shapes* of known credential formats (AWS
+keys, GitHub tokens, JWTs, etc.) rather than relying purely on entropy,
+which keeps the false-positive rate low.
+
+None of the values in this module are real credentials. They are regular
+expressions only.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Each pattern is (name, compiled regex). Order matters only in that more
+# specific patterns are listed before more generic ones.
+PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    (
+        "aws_access_key_id",
+        re.compile(r"\b(AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[0-9A-Z]{16}\b"),
+    ),
+    (
+        "aws_secret_access_key",
+        re.compile(
+            r"(?i)\baws(.{0,20})?(secret|access)?(.{0,20})?key(.{0,20})?"
+            r"['\"]?\s*[:=]\s*['\"]?[A-Za-z0-9/+=]{40}['\"]?"
+        ),
+    ),
+    (
+        "github_token",
+        re.compile(r"\b(ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,255}\b"),
+    ),
+    (
+        "openai_api_key",
+        re.compile(r"\bsk-[A-Za-z0-9]{20,}(?:T3BlbkFJ[A-Za-z0-9]{20,})?\b"),
+    ),
+    (
+        "slack_token",
+        re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,48}\b"),
+    ),
+    (
+        "stripe_key",
+        re.compile(r"\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{16,}\b"),
+    ),
+    (
+        "google_api_key",
+        re.compile(r"\bAIza[0-9A-Za-z\-_]{35}\b"),
+    ),
+    (
+        "jwt",
+        re.compile(
+            r"\bey[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b"
+        ),
+    ),
+    (
+        "bearer_token",
+        re.compile(r"(?i)\bbearer\s+[A-Za-z0-9\-._~+/]{10,}=*"),
+    ),
+    (
+        "private_key_block",
+        re.compile(
+            r"-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----"
+            r"[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----"
+        ),
+    ),
+    (
+        "generic_labeled_secret",
+        re.compile(
+            r"""(?ix)
+            \b(api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key|
+               client[_-]?secret|auth[_-]?token|private[_-]?key)
+            \b
+            \s*
+            [:=]
+            \s*
+            ['\"]?
+            (?P<value>[A-Za-z0-9\-_/+.=]{8,})
+            ['\"]?
+            """
+        ),
+    ),
+]
+
+# Group name used by the generic labeled-secret pattern to isolate the
+# value portion (so we don't redact the label itself, only the secret).
+GENERIC_VALUE_GROUP = "value"
+
+# Characters considered when computing Shannon entropy for generic
+# high-entropy token detection. Long runs of base64/hex-like strings are
+# candidates; short common words are filtered out by min length checks.
+ENTROPY_CANDIDATE_RE = re.compile(r"\b[A-Za-z0-9+/_\-]{20,}={0,2}\b")
+
+# Words that commonly appear as long identifiers but are NOT secrets.
+# Used to reduce false positives in entropy-based detection.
+ENTROPY_ALLOWLIST_SUBSTRINGS = (
+    "lorem",
+    "ipsum",
+    "example",
+    "placeholder",
+)

secretshield/redactor.py

@@ -0,0 +1,49 @@
+"""
+Redaction logic: turns detected secrets into safe placeholder text.
+"""
+
+from __future__ import annotations
+
+from .detector import Match, detect
+
+
+def redact(
+    text: str,
+    entropy_threshold: float = 4.2,
+    redact_with: str = "********",
+) -> tuple[str, bool]:
+    """
+    Redact any detected secrets in ``text``.
+
+    Returns a tuple of ``(redacted_text, was_redacted)``. ``was_redacted``
+    is ``True`` if at least one secret was found and replaced. The
+    original secret value is never present in the returned string.
+    """
+    if not text:
+        return text, False
+
+    try:
+        matches: list[Match] = detect(text, entropy_threshold=entropy_threshold)
+    except Exception:
+        # Detection failures must never break output; fail open (no redaction)
+        # rather than raise, but never leak partial state.
+        return text, False
+
+    if not matches:
+        return text, False
+
+    # Rebuild the string, replacing each match span with the placeholder.
+    # Process in order, tracking an offset since replacement length may
+    # differ from the original match length.
+    result_parts: list[str] = []
+    cursor = 0
+    for match in sorted(matches, key=lambda m: m.start):
+        if match.start < cursor:
+            # Overlap already consumed by a previous replacement; skip.
+            continue
+        result_parts.append(text[cursor:match.start])
+        result_parts.append(redact_with)
+        cursor = match.end
+
+    result_parts.append(text[cursor:])
+    return "".join(result_parts), True

secretshield-0.1.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: secretshield
+Version: 0.1.0
+Summary: Detect and redact likely secrets before they reach Python's terminal output or logging system.
+Author: secretshield contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Sam3360/secretshield
+Project-URL: Repository, https://github.com/Sam3360/secretshield
+Project-URL: Issues, https://github.com/Sam3360/secretshield/issues
+Keywords: security,secrets,redaction,logging,stdout,credentials
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# secretshield
+
+`secretshield` is a local Python security utility that detects likely
+secrets (API keys, tokens, passwords, private keys, and other
+credential-shaped strings) and redacts them **before** they are printed
+through Python's terminal output (`stdout`/`stderr`) or the standard
+`logging` module.
+
+```python
+import secretshield
+
+api_key = "sk-example1234567890abcdefFAKEKEY"
+print("API key:", api_key)
+```
+
+```text
+API key: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+The real secret value never appears in the redacted output, in
+secretshield's own warning messages, or in any exception it raises.
+
+## Why it exists
+
+Secrets end up in terminal output and logs more often than anyone
+intends: a debug `print()` left in accidentally, a stack trace that
+includes a config dict, a `logger.info()` call that dumps request
+headers. `secretshield` is a small, dependency-free safety net for
+exactly that class of mistake during local development and debugging.
+
+It is **not** a replacement for secret management, code review, or
+static-analysis security tooling — see [Limitations](#limitations) below.
+
+## Installation
+
+```bash
+pip install secretshield
+```
+
+For local development, from a cloned copy of this repository:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10 or newer. No third-party runtime dependencies.
+
+## Basic usage
+
+Protection for `sys.stdout`, `sys.stderr`, and `logging` is enabled the
+moment you import the package:
+
+```python
+import secretshield
+
+password = "hunter2-example-not-real"
+print("Using password:", password)
+```
+
+```text
+Using password: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+You can also toggle protection manually:
+
+```python
+import secretshield
+
+secretshield.disable()   # protection off
+secretshield.enable()    # protection back on (idempotent, safe to call repeatedly)
+secretshield.is_enabled()
+```
+
+### Detecting or redacting text directly
+
+You don't need to route text through stdout/logging to use the
+detection and redaction logic:
+
+```python
+from secretshield import detect, redact
+
+matches = detect("aws_key=AKIAABCDEFGHIJKLMNOP")
+# [Match(start=8, end=28, value='AKIA...', kind='aws_access_key_id')]
+
+safe_text, was_redacted = redact("aws_key=AKIAABCDEFGHIJKLMNOP")
+# ("aws_key=********", True)
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+* [`examples/basic.py`](examples/basic.py) — a fake secret printed to
+  the terminal.
+* [`examples/logging_demo.py`](examples/logging_demo.py) — a fake secret
+  logged via both `%s`-style arguments and an f-string.
+
+Run either with:
+
+```bash
+python examples/basic.py
+python examples/logging_demo.py
+```
+
+## CLI
+
+```bash
+secretshield --help
+secretshield --version
+```
+
+### `run` — execute a script with runtime protection
+
+```bash
+secretshield run app.py [args...]
+```
+
+Runs `app.py` as `__main__` with `sys.stdout`, `sys.stderr`, and
+`logging` protected for the duration of the script's execution. This is
+useful for wrapping an existing script without editing its source.
+
+### `scan` — static file/directory scanning
+
+```bash
+secretshield scan .
+secretshield scan path/to/file.py
+```
+
+Scans a file, or recursively scans a directory of text-like files
+(`.py`, `.txt`, `.md`, `.env`, `.yml`, `.json`, `.ini`, `.toml`, `.sh`,
+`.js`, `.ts`, etc.), reporting the *kind* and *location* of any likely
+secrets found. `scan` does **not** execute any code and does **not**
+print the secret values themselves — only where they were found. It
+exits with status `1` if anything was found, `0` otherwise, so it can be
+used as a pre-commit or CI check.
+
+**`scan` is static analysis; `run` (and the automatic protection on
+import) is runtime redaction.** They are separate features: `scan`
+looks at file contents on disk, `run`/import-time protection looks at
+what a running program actually writes out.
+
+## Configuration
+
+```python
+import secretshield
+
+secretshield.configure(
+    enabled=True,             # master on/off switch
+    redact_with="********",   # placeholder used in place of a secret
+    entropy_threshold=4.2,    # bits/char threshold for generic detection
+    notify=True,              # print the "potential secret" warning
+)
+```
+
+Sensible defaults mean most projects need zero configuration.
+
+## Detection methods
+
+`secretshield` combines two strategies:
+
+1. **Known-format pattern matching** — regexes tuned to the shape of
+   common credential formats: AWS access keys, GitHub tokens, OpenAI-style
+   keys, Slack tokens, Stripe keys, Google API keys, JWTs, bearer tokens,
+   PEM-style private-key blocks, and generic `key = value` pairs whose
+   label looks like `api_key`, `secret`, `token`, `password`, etc.
+2. **Generic high-entropy detection** — a Shannon-entropy check over
+   long, non-dictionary-like character runs, used to catch random-looking
+   secrets that don't match a known format. This is intentionally used
+   as a *supplement*, not the primary mechanism, because entropy alone
+   produces far too many false positives on things like hashes, UUIDs,
+   and encoded binary data that aren't secrets.
+
+## Architecture
+
+```text
+secretshield/
+├── patterns.py       # regexes for known secret formats
+├── detector.py        # detect(): pattern + entropy matching -> Match objects
+├── redactor.py         # redact(): turns Match spans into "********"
+├── config.py            # configure()/get_config(): runtime settings
+├── notifications.py      # safe, secret-free console/desktop warnings
+├── guardian.py             # stdout/stderr wrapping + logging record-factory hook
+└── cli.py                    # `secretshield` command-line entry point
+```
+
+Key design points:
+
+* **Stream wrapping**, not monkey-patching `print`: `sys.stdout` and
+  `sys.stderr` are replaced with a thin wrapper object that redacts on
+  `write()` and delegates everything else (`flush`, `isatty`, attribute
+  access) to the original stream.
+* **Logging protection** hooks `logging.setLogRecordFactory`, not a
+  `Filter` on the root logger. Filters attached to the root logger are
+  only consulted by the logger that originated a given call, so a
+  root-only filter would miss records from `logging.getLogger(__name__)`
+  child loggers. The record factory is invoked for every `LogRecord`
+  created anywhere in the process, so both `record.msg` (f-strings /
+  pre-formatted messages) and `record.args` (`%s`-style lazy arguments)
+  are reliably covered regardless of logger hierarchy.
+* **Re-entrancy guards** prevent secretshield's own warning output from
+  being fed back into detection/logging and causing recursive loops.
+* Detection and redaction failures are caught and swallowed — a bug in
+  secretshield should never crash or block the host application's
+  normal output.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite covers known-token detection, entropy detection, false
+positives, single/multiple/repeated secrets, multiline text, stdout,
+stderr, logging (`%s` args and f-strings), enable/disable idempotency,
+and stream restoration. All secrets used in tests and examples are fake.
+
+## Limitations
+
+`secretshield` protects **Python's own `stdout`, `stderr`, and `logging`
+output within the current process.** It is a helpful safety net, not a
+comprehensive security boundary. Specifically, it does **not**:
+
+* Prevent secrets from appearing in **screenshots** or screen recordings.
+* Prevent **clipboard** leaks.
+* Prevent secrets written via **arbitrary file writes** (e.g. `open(...).write(...)`,
+  `json.dump`, writing to a database).
+* Protect **other applications** or processes outside this Python
+  interpreter.
+* Redact output from **arbitrary subprocesses** — only output written
+  through this process's own `sys.stdout`/`sys.stderr`/`logging` is
+  covered, not everything a spawned subprocess itself prints to its own
+  inherited file descriptors before Python sees it.
+* Prevent **network leaks** (secrets sent over HTTP, sockets, etc.).
+* Catch **every possible way** a secret can leave a computer. Detection
+  is pattern- and entropy-based and can miss unusual or obfuscated
+  formats, and can occasionally over- or under-match.
+
+Treat `secretshield` as a defense-in-depth safety net for accidental
+local exposure during development and debugging — not as a substitute
+for proper secret management (vaults, environment isolation, `.gitignore`
+discipline, secret scanning in CI, least-privilege credentials, etc.).
+
+## Security considerations
+
+* secretshield performs **no network calls** and collects **no
+  telemetry**. All detection and redaction happens locally, in-process.
+* Desktop notifications (if you wire up your own backend beyond the
+  built-in best-effort `notify-send`/`osascript` calls) are optional and
+  fail silently if unavailable — they never crash the host application.
+* Because detection is heuristic, it can produce false negatives (a real
+  secret slips through) or false positives (harmless text gets redacted).
+  Tune `entropy_threshold` and, where needed, extend `patterns.py` for
+  your own credential formats.
+
+## Contributing
+
+Issues and pull requests are welcome. Please:
+
+1. Add tests for any new detection pattern or behavior change.
+2. Use only fake/example credentials in tests, examples, and docs —
+   never real secrets.
+3. Keep the standard-library-only dependency policy unless there's a
+   strong reason to add a dependency, and discuss it in an issue first.
+4. Run `pytest` before opening a PR.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

secretshield-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+secretshield/__init__.py,sha256=SkxDSh_6HeD3XZA4GapBCkJjZgGCMiWzpyKm7mJ9qxg,1146
+secretshield/cli.py,sha256=E7ueu8R02RiaSYqAg353HCEt_S-iz3VEv9bdpRlE4Do,5190
+secretshield/config.py,sha256=n0gjy6KEWWfM1sokX_NaZro2NUFFElUeC4gp-pMvzrM,1393
+secretshield/detector.py,sha256=00yHZMHZtAmgVBSdwJKvZUNPNtil3w6hluf8qpN1fp4,3965
+secretshield/guardian.py,sha256=OAlKxs89cvLpz9-E-vcieHxV2kdMFtkr4vy3-Jv7xbs,7078
+secretshield/notifications.py,sha256=z9_0Ahcjx6ciX93dAdjMGAjzB5cKmSdeNRhNYmLiCsY,2446
+secretshield/patterns.py,sha256=iOAuG0f1oxJVEkAvGRoqAFMOEYrfh6SmDw6y6v3Di28,3068
+secretshield/redactor.py,sha256=HKuvrowwBp3w9vKW2nboX7_uvdSenWp_vrrwlBJJiDQ,1537
+secretshield-0.1.0.dist-info/licenses/LICENSE,sha256=evWX6Xn2-RiZD62EhcIAPXeFjqT9MmAGXmmRXax98bI,1082
+secretshield-0.1.0.dist-info/METADATA,sha256=BMiZol3Dd7v93vV6dhmving-hlbx7TrKxMn1grUz4TU,10954
+secretshield-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+secretshield-0.1.0.dist-info/entry_points.txt,sha256=H_hdDswYwoiLoGbxqGEW0FW1kDgg7NXyQAtEsmAlVKg,55
+secretshield-0.1.0.dist-info/top_level.txt,sha256=903lcxIpnUvvGImf4-bkNR0HvLJ2_8vq668k8_rDu6Y,13
+secretshield-0.1.0.dist-info/RECORD,,

secretshield-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

secretshield-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+secretshield = secretshield.cli:main

secretshield-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 secretshield contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

secretshield-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+secretshield