shareclean 0.2.0__py3-none-any.whl

shareclean/__init__.py

@@ -0,0 +1,4 @@
+"""ShareClean: sanitize sensitive values before sharing text publicly."""
+
+__version__ = "0.2.0"
+version = "0.2.0"

shareclean/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m shareclean`."""
+
+from shareclean.cli import main
+
+raise SystemExit(main())

shareclean/cli.py

@@ -0,0 +1,308 @@
+"""CLI entry point for ShareClean."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from shareclean import __version__
+from shareclean.config import ConfigError, ShareCleanConfig, load_config
+from shareclean.detectors import DEFAULT_REDACTION_LABEL, get_rules
+from shareclean.io_utils import ShareCleanIOError, read_input, write_output
+from shareclean.redactor import sanitize
+from shareclean.report import format_brief_count, format_json_report, format_text_report
+from shareclean.selectors import (
+    SelectorError,
+    findings_for_check,
+    parse_selector_values,
+)
+
+EXIT_OK = 0
+EXIT_FINDING = 1
+EXIT_USER = 2
+EXIT_INTERNAL = 3
+
+
+def _redaction_label(value: str) -> str:
+    if value == "":
+        raise argparse.ArgumentTypeError("must not be empty")
+    if "\n" in value or "\r" in value:
+        raise argparse.ArgumentTypeError("must stay on one line")
+    return value
+
+
+def _add_config_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--config",
+        metavar="FILE",
+        default=None,
+        help="Load ShareClean config from FILE instead of auto-discovery.",
+    )
+    parser.add_argument(
+        "--profile",
+        metavar="NAME",
+        default=None,
+        help="Use a named ShareClean config profile.",
+    )
+    parser.add_argument(
+        "--redact-email",
+        dest="redact_email",
+        action="store_true",
+        default=None,
+        help="Enable email address detection for this run.",
+    )
+    parser.add_argument(
+        "--no-redact-email",
+        "--no-email",
+        dest="redact_email",
+        action="store_false",
+        default=None,
+        help=(
+            "Disable email address detection for this run. "
+            "--no-email is deprecated; use --no-redact-email."
+        ),
+    )
+    parser.add_argument(
+        "--redact-private-ip",
+        dest="redact_private_ip",
+        action="store_true",
+        default=None,
+        help="Enable detection and redaction of RFC 1918 private IP addresses.",
+    )
+    parser.add_argument(
+        "--no-redact-private-ip",
+        dest="redact_private_ip",
+        action="store_false",
+        default=None,
+        help="Disable detection and redaction of RFC 1918 private IP addresses.",
+    )
+    parser.add_argument(
+        "--redaction-label",
+        default=None,
+        type=_redaction_label,
+        metavar="TEXT",
+        help=(
+            "Replacement text for generic secrets such as passwords, API keys, "
+            f"Bearer tokens, and connection string passwords. Default: "
+            f"{DEFAULT_REDACTION_LABEL!r}."
+        ),
+    )
+    parser.add_argument(
+        "--fail-on",
+        action="append",
+        default=None,
+        metavar="SELECTORS",
+        help=(
+            "In --check mode, fail on selectors such as severity:high, "
+            "category:token, or rule:SC003."
+        ),
+    )
+    parser.add_argument(
+        "--ignore-for-check",
+        action="append",
+        default=None,
+        metavar="SELECTORS",
+        help=(
+            "In --check mode, exclude matching findings from the exit decision "
+            "without disabling detection or redaction."
+        ),
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shareclean",
+        description=(
+            "Sanitize sensitive values in logs and text before sharing publicly. "
+            "Reads from a file or stdin; writes sanitized text to stdout (or --output)."
+        ),
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        default=None,
+        metavar="FILE",
+        help="Input file to sanitize. Reads from stdin if omitted.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Print the ShareClean version and exit.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        default=False,
+        help=(
+            "Exit 1 if matching findings are detected; do not write sanitized "
+            "output. Useful in CI pipelines and Git hooks."
+        ),
+    )
+    parser.add_argument(
+        "--output",
+        metavar="FILE",
+        default=None,
+        help="Write sanitized text to FILE instead of stdout.",
+    )
+    parser.add_argument(
+        "--report",
+        action="store_true",
+        default=False,
+        help="Print a full redaction report to stderr after processing.",
+    )
+    parser.add_argument(
+        "--report-format",
+        choices=["text", "json"],
+        default="text",
+        metavar="{text,json}",
+        help="Format for --report output: 'text' (default) or 'json'.",
+    )
+    _add_config_options(parser)
+    return parser
+
+
+def _build_config_show_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shareclean config show",
+        description="Print the effective ShareClean configuration.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Print the ShareClean version and exit.",
+    )
+    _add_config_options(parser)
+    return parser
+
+
+def _cli_config_values(args: argparse.Namespace) -> dict[str, object]:
+    return {
+        "redact_email": args.redact_email,
+        "redact_private_ip": args.redact_private_ip,
+        "redaction_label": args.redaction_label,
+        "fail_on": args.fail_on,
+        "ignore_for_check": args.ignore_for_check,
+    }
+
+
+def _load_effective_config(args: argparse.Namespace) -> ShareCleanConfig:
+    return load_config(
+        config_path=args.config,
+        cli_profile=args.profile,
+        cli_values=_cli_config_values(args),
+    )
+
+
+def _extract_config_show_args(argv: list[str]) -> list[str] | None:
+    for index in range(len(argv) - 1):
+        if argv[index] == "config" and argv[index + 1] == "show":
+            return argv[:index] + argv[index + 2:]
+    return None
+
+
+def _print_check_summary(total: int, failing: int) -> None:
+    if failing:
+        print(
+            f"Found {failing} check-failing sensitive item(s) "
+            f"out of {total} total finding(s). No output written.",
+            file=sys.stderr,
+        )
+    elif total:
+        print(
+            f"No check-failing sensitive items found. "
+            f"{total} finding(s) still detected and no output written.",
+            file=sys.stderr,
+        )
+    else:
+        print("No sensitive items found. No output written.", file=sys.stderr)
+
+
+def _run_config_show(argv: list[str]) -> int:
+    parser = _build_config_show_parser()
+    args = parser.parse_args(argv)
+    try:
+        config = _load_effective_config(args)
+    except ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_USER
+    print(json.dumps(config.to_public_dict(), indent=2))
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run ShareClean and return a process exit code."""
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+    config_show_args = _extract_config_show_args(raw_args)
+    if config_show_args is not None:
+        return _run_config_show(config_show_args)
+
+    parser = _build_parser()
+    args = parser.parse_args(raw_args)
+
+    try:
+        if not args.check and (args.fail_on is not None or args.ignore_for_check is not None):
+            print(
+                "Error: --fail-on and --ignore-for-check require --check.",
+                file=sys.stderr,
+            )
+            return EXIT_USER
+
+        config = _load_effective_config(args)
+
+        try:
+            fail_on = parse_selector_values(config.fail_on)
+            ignore_for_check = parse_selector_values(config.ignore_for_check)
+        except SelectorError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return EXIT_USER
+
+        try:
+            text, input_name = read_input(args.file)
+        except ShareCleanIOError as exc:
+            print(str(exc), file=sys.stderr)
+            return EXIT_USER
+
+        rules = get_rules(
+            redact_email=config.redact_email,
+            redact_private_ip=config.redact_private_ip,
+            redaction_label=config.redaction_label,
+        )
+        result = sanitize(text, rules)
+
+        if args.check:
+            failing = findings_for_check(
+                result.findings,
+                fail_on=fail_on,
+                ignore_for_check=ignore_for_check,
+            )
+            _print_check_summary(result.replacement_count, len(failing))
+            return EXIT_FINDING if failing else EXIT_OK
+
+        try:
+            write_output(result.cleaned_text, args.output, args.file)
+        except ShareCleanIOError as exc:
+            print(str(exc), file=sys.stderr)
+            return EXIT_USER
+
+        if args.output:
+            print(f"Output written to: {args.output}", file=sys.stderr)
+
+        if args.report:
+            if args.report_format == "json":
+                print(format_json_report(result, input_name), file=sys.stderr)
+            else:
+                print(format_text_report(result, input_name), file=sys.stderr)
+        else:
+            print(format_brief_count(result), file=sys.stderr)
+
+        return EXIT_OK
+
+    except ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_USER
+    except Exception as exc:  # noqa: BLE001 - catch-all for internal errors
+        print(f"Internal error: {exc}", file=sys.stderr)
+        return EXIT_INTERNAL

shareclean/config.py

@@ -0,0 +1,312 @@
+"""Configuration loading for ShareClean."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from shareclean.detectors import DEFAULT_REDACTION_LABEL
+
+try:  # pragma: no cover - exercised on Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - exercised on Python 3.10
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+BOOL_TRUE = frozenset({"true", "1", "yes", "on"})
+BOOL_FALSE = frozenset({"false", "0", "no", "off"})
+
+ENV_REDACT_EMAIL = "SHARECLEAN_REDACT_EMAIL"
+ENV_REDACT_PRIVATE_IP = "SHARECLEAN_REDACT_PRIVATE_IP"
+ENV_REDACTION_LABEL = "SHARECLEAN_REDACTION_LABEL"
+ENV_PROFILE = "SHARECLEAN_PROFILE"
+ENV_FAIL_ON = "SHARECLEAN_FAIL_ON"
+ENV_IGNORE_FOR_CHECK = "SHARECLEAN_IGNORE_FOR_CHECK"
+
+ROOT_KEYS = frozenset({
+    "redact_email",
+    "redact_private_ip",
+    "redaction_label",
+    "profile",
+    "fail_on",
+    "ignore_for_check",
+    "profiles",
+})
+PROFILE_KEYS = frozenset({
+    "redact_email",
+    "redact_private_ip",
+    "redaction_label",
+    "fail_on",
+    "ignore_for_check",
+})
+
+
+class ConfigError(ValueError):
+    """Raised for user-facing configuration errors."""
+
+
+@dataclass(frozen=True)
+class ShareCleanConfig:
+    redact_email: bool = True
+    redact_private_ip: bool = False
+    redaction_label: str = DEFAULT_REDACTION_LABEL
+    profile: str = "default"
+    fail_on: list[str] | None = None
+    ignore_for_check: list[str] | None = None
+
+    def with_lists(self) -> "ShareCleanConfig":
+        return replace(
+            self,
+            fail_on=list(self.fail_on or []),
+            ignore_for_check=list(self.ignore_for_check or []),
+        )
+
+    def to_public_dict(self) -> dict[str, Any]:
+        data = asdict(self.with_lists())
+        return data
+
+
+def _config_error(path: Path, message: str) -> ConfigError:
+    return ConfigError(f"Config error in {path}: {message}")
+
+
+def _format_toml_error(path: Path, exc: tomllib.TOMLDecodeError) -> ConfigError:
+    line = getattr(exc, "lineno", None)
+    column = getattr(exc, "colno", None)
+    if line is not None and column is not None:
+        return ConfigError(f"Config error in {path}:{line}:{column}: {exc}")
+    return ConfigError(f"Config error in {path}: {exc}")
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as exc:
+        raise _format_toml_error(path, exc) from exc
+    except OSError as exc:
+        raise ConfigError(f"Config error in {path}: cannot read file") from exc
+    if not isinstance(data, dict):
+        raise _config_error(path, "top-level TOML value must be a table")
+    return data
+
+
+def _shareclean_table_from_pyproject(path: Path) -> dict[str, Any] | None:
+    data = _load_toml(path)
+    tool = data.get("tool")
+    if not isinstance(tool, dict):
+        return None
+    table = tool.get("shareclean")
+    if table is None:
+        return None
+    if not isinstance(table, dict):
+        raise _config_error(path, "[tool.shareclean] must be a table")
+    return table
+
+
+def _find_config(start: Path | None = None) -> tuple[Path, dict[str, Any]] | None:
+    current = (start or Path.cwd()).resolve()
+    if current.is_file():
+        current = current.parent
+
+    while True:
+        dotfile = current / ".shareclean.toml"
+        pyproject = current / "pyproject.toml"
+        dotfile_table = _load_toml(dotfile) if dotfile.exists() else None
+        pyproject_table = (
+            _shareclean_table_from_pyproject(pyproject)
+            if pyproject.exists()
+            else None
+        )
+
+        if dotfile_table is not None and pyproject_table is not None:
+            raise ConfigError(
+                "Config error: both ShareClean config files exist in the same "
+                f"directory: {dotfile} and {pyproject}"
+            )
+        if dotfile_table is not None:
+            return dotfile, dotfile_table
+        if pyproject_table is not None:
+            return pyproject, pyproject_table
+
+        if (current / ".git").exists():
+            return None
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def _load_explicit_config(path_value: str) -> tuple[Path, dict[str, Any]]:
+    path = Path(path_value).expanduser().resolve()
+    if not path.exists():
+        raise ConfigError(f"Config error: config file not found: {path}")
+    if path.name == "pyproject.toml":
+        table = _shareclean_table_from_pyproject(path)
+        if table is None:
+            raise _config_error(path, "missing [tool.shareclean] table")
+        return path, table
+    return path, _load_toml(path)
+
+
+def _validate_label(path: Path | None, value: object) -> str:
+    if not isinstance(value, str):
+        raise _value_error(path, "redaction_label must be a string")
+    if value == "":
+        raise _value_error(path, "redaction_label must not be empty")
+    if "\n" in value or "\r" in value:
+        raise _value_error(path, "redaction_label must stay on one line")
+    return value
+
+
+def _value_error(path: Path | None, message: str) -> ConfigError:
+    if path is None:
+        return ConfigError(f"Config error: {message}")
+    return _config_error(path, message)
+
+
+def _validate_bool(path: Path | None, key: str, value: object) -> bool:
+    if not isinstance(value, bool):
+        raise _value_error(path, f"{key} must be true or false")
+    return value
+
+
+def _validate_string(path: Path | None, key: str, value: object) -> str:
+    if not isinstance(value, str) or not value:
+        raise _value_error(path, f"{key} must be a non-empty string")
+    return value
+
+
+def _validate_selector_list(path: Path | None, key: str, value: object) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise _value_error(path, f"{key} must be a list of selector strings")
+    return list(value)
+
+
+def _validate_table(
+    path: Path | None,
+    table: dict[str, Any],
+    *,
+    profile_table: bool,
+) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
+    allowed = PROFILE_KEYS if profile_table else ROOT_KEYS
+    unknown = sorted(set(table) - allowed)
+    if unknown:
+        raise _value_error(path, f"unknown config key(s): {', '.join(unknown)}")
+
+    values: dict[str, Any] = {}
+    profiles: dict[str, dict[str, Any]] = {}
+    for key, value in table.items():
+        if key == "profiles":
+            if not isinstance(value, dict):
+                raise _value_error(path, "profiles must be a table")
+            for profile_name, profile_values in value.items():
+                if not isinstance(profile_name, str) or not profile_name:
+                    raise _value_error(path, "profile names must be non-empty strings")
+                if not isinstance(profile_values, dict):
+                    raise _value_error(path, f"profile {profile_name!r} must be a table")
+                profile_config, _ = _validate_table(
+                    path,
+                    profile_values,
+                    profile_table=True,
+                )
+                profiles[profile_name] = profile_config
+            continue
+        if key in {"redact_email", "redact_private_ip"}:
+            values[key] = _validate_bool(path, key, value)
+        elif key == "redaction_label":
+            values[key] = _validate_label(path, value)
+        elif key == "profile":
+            values[key] = _validate_string(path, key, value)
+        elif key in {"fail_on", "ignore_for_check"}:
+            values[key] = _validate_selector_list(path, key, value)
+    return values, profiles
+
+
+def _apply_values(config: ShareCleanConfig, values: dict[str, Any]) -> ShareCleanConfig:
+    data = asdict(config)
+    for key, value in values.items():
+        data[key] = value
+    return ShareCleanConfig(**data)
+
+
+def _parse_env_bool(name: str, raw: str) -> bool:
+    normalized = raw.strip().lower()
+    if normalized in BOOL_TRUE:
+        return True
+    if normalized in BOOL_FALSE:
+        return False
+    raise ConfigError(
+        f"Config error: {name} must be one of true, 1, yes, on, false, 0, no, off"
+    )
+
+
+def _env_values(environ: dict[str, str]) -> tuple[dict[str, Any], str | None]:
+    values: dict[str, Any] = {}
+    profile = None
+    if ENV_REDACT_EMAIL in environ:
+        values["redact_email"] = _parse_env_bool(
+            ENV_REDACT_EMAIL,
+            environ[ENV_REDACT_EMAIL],
+        )
+    if ENV_REDACT_PRIVATE_IP in environ:
+        values["redact_private_ip"] = _parse_env_bool(
+            ENV_REDACT_PRIVATE_IP,
+            environ[ENV_REDACT_PRIVATE_IP],
+        )
+    if ENV_REDACTION_LABEL in environ:
+        values["redaction_label"] = _validate_label(None, environ[ENV_REDACTION_LABEL])
+    if ENV_PROFILE in environ:
+        profile = _validate_string(None, ENV_PROFILE, environ[ENV_PROFILE])
+    if ENV_FAIL_ON in environ:
+        values["fail_on"] = [environ[ENV_FAIL_ON]]
+    if ENV_IGNORE_FOR_CHECK in environ:
+        values["ignore_for_check"] = [environ[ENV_IGNORE_FOR_CHECK]]
+    return values, profile
+
+
+def load_config(
+    *,
+    config_path: str | None = None,
+    cli_profile: str | None = None,
+    cli_values: dict[str, Any] | None = None,
+    environ: dict[str, str] | None = None,
+    start: Path | None = None,
+) -> ShareCleanConfig:
+    """Load ShareClean configuration using the documented precedence order."""
+    path: Path | None = None
+    table: dict[str, Any] = {}
+    profiles: dict[str, dict[str, Any]] = {}
+
+    if config_path is not None:
+        path, table = _load_explicit_config(config_path)
+    else:
+        discovered = _find_config(start)
+        if discovered is not None:
+            path, table = discovered
+
+    base_values, profiles = _validate_table(path, table, profile_table=False)
+    config = _apply_values(ShareCleanConfig(), base_values)
+
+    env_values, env_profile = _env_values(environ or dict(os.environ))
+    selected_profile = config.profile
+    if env_profile is not None:
+        selected_profile = env_profile
+    if cli_profile is not None:
+        selected_profile = cli_profile
+
+    if selected_profile != "default":
+        if selected_profile not in profiles:
+            raise _value_error(path, f"unknown profile: {selected_profile}")
+        config = _apply_values(config, profiles[selected_profile])
+
+    config = replace(config, profile=selected_profile)
+    config = _apply_values(config, env_values)
+    if cli_values:
+        config = _apply_values(
+            config,
+            {key: value for key, value in cli_values.items() if value is not None},
+        )
+    return config.with_lists()