secretshield 0.6.0__tar.gz → 0.7.0__tar.gz

secretshield-0.7.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: secretshield
+Version: 0.7.0
+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
+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: 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
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 🛡️ SecretShield
+
+**Your secrets shouldn't end up in your terminal, your logs, or your commit history.**
+
+[![PyPI version](https://img.shields.io/pypi/v/secretshield?color=blue)](https://pypi.org/project/secretshield/)
+[![Python versions](https://img.shields.io/pypi/pyversions/secretshield)](https://pypi.org/project/secretshield/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/secretshield)](https://pypi.org/project/secretshield/)
+[![License: MIT](https://img.shields.io/pypi/l/secretshield)](LICENSE)
+
+[Install](#install) · [Demo](#demo) · [Try it](#try-it) · [Full usage guide →](https://github.com/Sam3360/secretshield/blob/main/USAGE.md)
+
+</div>
+
+---
+
+You've done this. Everyone has: a stray `print()` left in from
+debugging, a log line that dumps a config dict, a hardcoded key that
+slips past review. SecretShield catches it before it leaves your
+machine — redacted from your terminal output automatically, scanned
+out of your codebase on demand, and blocked from your commits if it
+gets that far.
+
+## Demo
+
+[![SecretShield Demo](https://img.youtube.com/vi/g95lNIhWsXM/maxresdefault.jpg)](https://youtu.be/g95lNIhWsXM)
+
+**[▶ Watch the full demo on YouTube](https://youtu.be/g95lNIhWsXM)**
+
+## Install
+
+```bash
+pip install secretshield
+```
+
+## Try it
+
+```python
+import secretshield
+
+api_key = "sk-example1234567890abcdefFAKEKEY"
+print("API key:", api_key)
+```
+
+```text
+API key: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+No config, no code changes — the moment you import it, stdout, stderr,
+and `logging` are protected.
+
+Scan a project:
+
+```bash
+secretshield scan .
+```
+
+Set a project up in one step — config file, Git hook, CI workflow:
+
+```bash
+secretshield init
+```
+
+*(Every command also works via the shorter `ss` alias.)*
+
+## What it does
+
+| | |
+|---|---|
+| 🖥️ **Runtime protection** | `import secretshield` redacts secrets from `stdout`, `stderr`, and `logging` automatically |
+| 🔍 **Static scanning** | `secretshield scan .` finds hardcoded secrets across Python, JS/TS, HTML, YAML, `.env`, and more |
+| 🔧 **Auto-Fix** | `scan . --fix` moves a hardcoded Python or JS/TS secret into `.env` and rewrites the code — only when it's unambiguous |
+| 🪝 **Git hook** | `install-hook` blocks a commit before a secret reaches your history |
+| ⚙️ **GitHub Actions** | `github-action` generates a workflow that scans every push and PR |
+
+No required dependencies, no telemetry, no network calls. Everything
+runs locally, in your own process.
+
+## Custom rules
+
+Have a credential format of your own? Drop a
+`.secretshield-rules.toml` in your project root:
+
+```toml
+[[rules]]
+name = "My API Key"
+pattern = "MYAPP_[A-Za-z0-9]{32}"
+```
+
+`secretshield scan .` picks it up automatically — no flag needed.
+Validate the file with `secretshield rules check`, or create a rule
+interactively with `secretshield rule create`.
+
+For the full command reference, configuration options, and exactly how
+Auto-Fix decides what's safe to rewrite, see the
+**[usage guide](https://github.com/Sam3360/secretshield/blob/main/USAGE.md)**.
+
+## Limitations
+
+Runtime protection covers this Python process's `stdout`/`stderr`/
+`logging` — not screenshots, the clipboard, or other applications.
+Auto-Fix only rewrites Python and JS/TS, and only unambiguous
+assignments; anything less certain is reported, not modified. Treat
+SecretShield as a strong safety net, not a replacement for proper
+secret management. Details in the [usage guide](https://github.com/Sam3360/secretshield/blob/main/USAGE.md#limitations).
+
+## Contributing
+
+Issues and PRs welcome. Add tests for new detection patterns or
+behavior changes, use only fake credentials in tests/examples, and run
+`pytest` before opening a PR.
+
+## [☕](https://github.com/sponsors/Sam3360/) Get me a coffee
+
+If you find this project useful, consider [supporting its development through GitHub Sponsors](https://github.com/sponsors/Sam3360/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

secretshield-0.7.0/README.md

@@ -0,0 +1,121 @@
+<div align="center">
+
+# 🛡️ SecretShield
+
+**Your secrets shouldn't end up in your terminal, your logs, or your commit history.**
+
+[![PyPI version](https://img.shields.io/pypi/v/secretshield?color=blue)](https://pypi.org/project/secretshield/)
+[![Python versions](https://img.shields.io/pypi/pyversions/secretshield)](https://pypi.org/project/secretshield/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/secretshield)](https://pypi.org/project/secretshield/)
+[![License: MIT](https://img.shields.io/pypi/l/secretshield)](LICENSE)
+
+[Install](#install) · [Demo](#demo) · [Try it](#try-it) · [Full usage guide →](https://github.com/Sam3360/secretshield/blob/main/USAGE.md)
+
+</div>
+
+---
+
+You've done this. Everyone has: a stray `print()` left in from
+debugging, a log line that dumps a config dict, a hardcoded key that
+slips past review. SecretShield catches it before it leaves your
+machine — redacted from your terminal output automatically, scanned
+out of your codebase on demand, and blocked from your commits if it
+gets that far.
+
+## Demo
+
+[![SecretShield Demo](https://img.youtube.com/vi/g95lNIhWsXM/maxresdefault.jpg)](https://youtu.be/g95lNIhWsXM)
+
+**[▶ Watch the full demo on YouTube](https://youtu.be/g95lNIhWsXM)**
+
+## Install
+
+```bash
+pip install secretshield
+```
+
+## Try it
+
+```python
+import secretshield
+
+api_key = "sk-example1234567890abcdefFAKEKEY"
+print("API key:", api_key)
+```
+
+```text
+API key: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+No config, no code changes — the moment you import it, stdout, stderr,
+and `logging` are protected.
+
+Scan a project:
+
+```bash
+secretshield scan .
+```
+
+Set a project up in one step — config file, Git hook, CI workflow:
+
+```bash
+secretshield init
+```
+
+*(Every command also works via the shorter `ss` alias.)*
+
+## What it does
+
+| | |
+|---|---|
+| 🖥️ **Runtime protection** | `import secretshield` redacts secrets from `stdout`, `stderr`, and `logging` automatically |
+| 🔍 **Static scanning** | `secretshield scan .` finds hardcoded secrets across Python, JS/TS, HTML, YAML, `.env`, and more |
+| 🔧 **Auto-Fix** | `scan . --fix` moves a hardcoded Python or JS/TS secret into `.env` and rewrites the code — only when it's unambiguous |
+| 🪝 **Git hook** | `install-hook` blocks a commit before a secret reaches your history |
+| ⚙️ **GitHub Actions** | `github-action` generates a workflow that scans every push and PR |
+
+No required dependencies, no telemetry, no network calls. Everything
+runs locally, in your own process.
+
+## Custom rules
+
+Have a credential format of your own? Drop a
+`.secretshield-rules.toml` in your project root:
+
+```toml
+[[rules]]
+name = "My API Key"
+pattern = "MYAPP_[A-Za-z0-9]{32}"
+```
+
+`secretshield scan .` picks it up automatically — no flag needed.
+Validate the file with `secretshield rules check`, or create a rule
+interactively with `secretshield rule create`.
+
+For the full command reference, configuration options, and exactly how
+Auto-Fix decides what's safe to rewrite, see the
+**[usage guide](https://github.com/Sam3360/secretshield/blob/main/USAGE.md)**.
+
+## Limitations
+
+Runtime protection covers this Python process's `stdout`/`stderr`/
+`logging` — not screenshots, the clipboard, or other applications.
+Auto-Fix only rewrites Python and JS/TS, and only unambiguous
+assignments; anything less certain is reported, not modified. Treat
+SecretShield as a strong safety net, not a replacement for proper
+secret management. Details in the [usage guide](https://github.com/Sam3360/secretshield/blob/main/USAGE.md#limitations).
+
+## Contributing
+
+Issues and PRs welcome. Add tests for new detection patterns or
+behavior changes, use only fake credentials in tests/examples, and run
+`pytest` before opening a PR.
+
+## [☕](https://github.com/sponsors/Sam3360/) Get me a coffee
+
+If you find this project useful, consider [supporting its development through GitHub Sponsors](https://github.com/sponsors/Sam3360/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{secretshield-0.6.0 → secretshield-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "secretshield"
-version = "0.6.0"
+version = "0.7.0"
 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.6.0 → secretshield-0.7.0}/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.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "__version__",

{secretshield-0.6.0 → secretshield-0.7.0}/secretshield/autofix/fixer.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from typing import Callable
 
 from ..detector import detect
+from ..custom_rules import scan_text_with_rules
 from . import javascript as jsfix
 from . import python as pyfix
 from .env import append_env_example_var, append_env_var, unique_env_key
@@ -86,6 +87,7 @@ def run_autofix(
     entropy_threshold: float = 4.2,
     print_func: Callable[[str], None] = _default_print,
     input_func: Callable[[str], str] = _default_input,
+    custom_rules: list | None = None,
 ) -> FixSummary:
     """
     Run the interactive Auto-Fix flow.
@@ -94,6 +96,12 @@ def run_autofix(
     `secretshield.detector.Match` objects found in that file (already
     filtered for placeholders by the caller). Files are processed in
     sorted order for deterministic output.
+
+    `custom_rules` (optional): the same `.secretshield-rules.toml`
+    rules used to build `findings_by_file`, if any. Needed here too so
+    that the internal re-scan (used to get fresh, accurate line numbers
+    after an `import os` insertion) can re-locate a match that only a
+    custom rule -- not a built-in pattern -- would find.
     """
     summary = FixSummary()
     env_path = project_root / ".env"
@@ -163,9 +171,13 @@ def run_autofix(
             source = pyfix.insert_import_os(source)
 
         # Re-scan the (possibly import-adjusted) source fresh, so line
-        # numbers reflect the current content exactly.
+        # numbers reflect the current content exactly. Custom rules are
+        # merged in too, so a match only a custom rule (not a built-in
+        # pattern) would find isn't lost here.
         try:
             current_matches = detect(source, entropy_threshold=entropy_threshold)
+            if custom_rules:
+                current_matches = current_matches + scan_text_with_rules(source, custom_rules)
         except Exception:
             current_matches = []
 

{secretshield-0.6.0 → secretshield-0.7.0}/secretshield/cli.py

@@ -408,6 +408,7 @@ def _iter_scan_sources(args: argparse.Namespace, target: Path, include_patterns:
 
 def _run_scan(args: argparse.Namespace) -> int:
     from .baseline import baseline_exists, compute_finding_id, load_baseline_ids, write_baseline
+    from .custom_rules import load_custom_rules, scan_text_with_rules
     from .project_config import load_project_config
 
     project_cfg = load_project_config()
@@ -428,6 +429,20 @@ def _run_scan(args: argparse.Namespace) -> int:
 
     exclude_patterns.extend(load_ignore_patterns(Path.cwd()))
 
+    # Custom rules (.secretshield-rules.toml), if present, become
+    # additional detectors alongside the built-in patterns -- no flag
+    # required. A broken rules file never blocks the scan (valid rules
+    # in the same file still load and run); it's surfaced as a single
+    # warning pointing at `rules check` rather than silently ignored.
+    custom_rules, custom_rule_errors = load_custom_rules(Path.cwd())
+    if custom_rule_errors:
+        print(
+            f"secretshield: warning: {len(custom_rule_errors)} invalid custom "
+            f"rule(s) in .secretshield-rules.toml -- run `secretshield rules "
+            f"check` for details.",
+            file=sys.stderr,
+        )
+
     json_output = bool(args.json) or (project_cfg.output_format == "json")
 
     target = Path(args.path)
@@ -455,6 +470,11 @@ def _run_scan(args: argparse.Namespace) -> int:
         _progress_update(show_progress, files_scanned)
 
         file_matches = _scan_text_matches(text, entropy_threshold=entropy_threshold)
+        if custom_rules:
+            custom_matches = [
+                m for m in scan_text_with_rules(text, custom_rules) if not _is_placeholder(m.value)
+            ]
+            file_matches = file_matches + custom_matches
         if file_matches:
             matches_by_file[display_path] = file_matches
         for match in file_matches:
@@ -503,7 +523,12 @@ def _run_scan(args: argparse.Namespace) -> int:
     if getattr(args, "fix", False):
         from .autofix import run_autofix
 
-        summary = run_autofix(project_root, matches_by_file, entropy_threshold=entropy_threshold)
+        summary = run_autofix(
+            project_root,
+            matches_by_file,
+            entropy_threshold=entropy_threshold,
+            custom_rules=custom_rules,
+        )
         return 1 if summary.fixed < summary.detected else 0
 
     if json_output:
@@ -734,6 +759,124 @@ def _cmd_init(args: argparse.Namespace) -> int:
     return 0
 
 
+# --- `rules` / `rule create` commands -----------------------------------
+
+
+def _cmd_rules_check(args: argparse.Namespace) -> int:
+    from .custom_rules import load_custom_rules, rules_file_path
+
+    use_color = supports_color(sys.stdout)
+    path = rules_file_path(Path.cwd())
+
+    if not path.exists():
+        print(f"No {path.name} found.")
+        return 0
+
+    rules, errors = load_custom_rules(Path.cwd())
+
+    print("SecretShield Rules\n")
+
+    if errors:
+        for err in errors:
+            if err.name:
+                print(f'{red(chr(0x2717), use_color)} Invalid custom rule "{err.name}"')
+                print(f"  {err.message}")
+            else:
+                label = f"rule #{err.rule_index + 1}" if err.rule_index is not None else path.name
+                print(f"{red(chr(0x2717), use_color)} {label}: {err.message}")
+        return 1
+
+    print(f"{green(chr(0x2713), use_color)} {path.name}")
+    print(f"{green(chr(0x2713), use_color)} {len(rules)} rule(s) loaded")
+    print(f"{green(chr(0x2713), use_color)} All patterns are valid")
+    return 0
+
+
+def _cmd_rules_list(args: argparse.Namespace) -> int:
+    from .custom_rules import load_custom_rules, rules_file_path
+
+    path = rules_file_path(Path.cwd())
+    if not path.exists():
+        print(f"No {path.name} found.")
+        return 0
+
+    rules, errors = load_custom_rules(Path.cwd())
+
+    if not rules and not errors:
+        print("No custom rules defined.")
+        return 0
+
+    if rules:
+        print("SecretShield Custom Rules\n")
+        for i, rule in enumerate(rules, start=1):
+            print(f"{i}. {rule.name}")
+            print(f"   {rule.pattern}")
+
+    if errors:
+        use_color = supports_color(sys.stdout)
+        print(
+            f"\n{red(chr(0x2717), use_color)} {len(errors)} rule(s) failed to load "
+            f"-- run `secretshield rules check` for details."
+        )
+    return 0
+
+
+def _cmd_rules_no_subcommand(args: argparse.Namespace) -> int:
+    # `secretshield rules` with no further action -> list.
+    return _cmd_rules_list(args)
+
+
+def _cmd_rule_no_subcommand(args: argparse.Namespace) -> int:
+    print("secretshield rule: missing subcommand. Try `secretshield rule create`.", file=sys.stderr)
+    return 1
+
+
+def _cmd_rule_create(args: argparse.Namespace) -> int:
+    import re as _re
+
+    from .custom_rules import append_rule, rules_file_path
+
+    try:
+        interactive = sys.stdin.isatty()
+    except Exception:
+        interactive = False
+
+    if not interactive:
+        print("secretshield rule create requires an interactive terminal.")
+        print("No rule was created.")
+        return 1
+
+    print("SecretShield \u2014 Create custom rule\n")
+
+    name = input("Rule name: ").strip()
+    if not name:
+        print("Rule name cannot be empty. No rule was created.", file=sys.stderr)
+        return 1
+
+    while True:
+        pattern = input("Pattern: ").strip()
+        if not pattern:
+            print("Pattern cannot be empty.", file=sys.stderr)
+            continue
+        try:
+            _re.compile(pattern)
+        except _re.error as exc:
+            print(f"Invalid regular expression: {exc}", file=sys.stderr)
+            print("Please try again.\n")
+            continue
+        break
+
+    path = rules_file_path(Path.cwd())
+    try:
+        append_rule(path, name, pattern)
+    except Exception as exc:
+        print(f"\u2717 Could not write {path.name}: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"{green(chr(0x2713), supports_color(sys.stdout))} Added rule to {path.name}")
+    return 0
+
+
 # --- argparse wiring -----------------------------------------------------
 
 
@@ -925,6 +1068,27 @@ def build_parser() -> argparse.ArgumentParser:
     )
     init_parser.set_defaults(func=_cmd_init)
 
+    rules_parser = subparsers.add_parser(
+        "rules",
+        help="List or validate .secretshield-rules.toml custom detection rules.",
+    )
+    rules_subparsers = rules_parser.add_subparsers(dest="rules_action")
+    rules_check_parser = rules_subparsers.add_parser(
+        "check", help="Validate .secretshield-rules.toml (TOML syntax, required fields, regex validity)."
+    )
+    rules_check_parser.set_defaults(func=_cmd_rules_check)
+    rules_parser.set_defaults(func=_cmd_rules_list)
+
+    rule_parser = subparsers.add_parser(
+        "rule", help="Create a custom detection rule."
+    )
+    rule_parser.set_defaults(func=_cmd_rule_no_subcommand)
+    rule_subparsers = rule_parser.add_subparsers(dest="rule_action")
+    rule_create_parser = rule_subparsers.add_parser(
+        "create", help="Interactively create a new rule in .secretshield-rules.toml."
+    )
+    rule_create_parser.set_defaults(func=_cmd_rule_create)
+
     return parser