secretshield 0.3.2__tar.gz → 0.4.1__tar.gz

{secretshield-0.3.2 → secretshield-0.4.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Sam3360
+Copyright (c) 2026 Samarth Chugh (Sam3360)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

secretshield-0.4.1/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: secretshield
+Version: 0.4.1
+Summary: Detect, redact, and prevent secret exposure in Python apps, source code, and Git commits — runtime protection, multi-language scanning, auto-fix, and CI integration in one tool.
+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.**
+**SecretShield makes sure they don't — automatically.**
+
+[![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](#installation) · [Demo](#demo) · [Quick start](#quick-start) · [Features](#what-secretshield-does) · [Docs below](#cli-reference)
+
+</div>
+
+---
+
+## The problem
+
+You've done this. Everyone has.
+
+```python
+print("API key:", api_key)          # ...now it's in your terminal history
+logger.info("Token: %s", token)     # ...now it's in your log files
+API_KEY = "sk-live-abc123..."       # ...now it's about to get committed
+```
+
+One `print()` left in from debugging. One log line that dumps a config
+dict. One hardcoded key that slips past code review. That's usually all
+it takes.
+
+## The fix
+
+```bash
+pip install secretshield
+```
+
+```python
+import secretshield
+
+api_key = "sk-example1234567890abcdefFAKEKEY"
+print("API key:", api_key)
+```
+
+```text
+API key: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+**No configuration. No code changes. Just `pip install` and `import`.**
+The moment you import it, your terminal output, your logs — protected.
+
+## Demo
+
+See SecretShield in action:
+
+[![SecretShield Demo](https://img.youtube.com/vi/g95lNIhWsXM/maxresdefault.jpg)](https://youtu.be/g95lNIhWsXM)
+
+**[▶ Watch the full demo on YouTube](https://youtu.be/g95lNIhWsXM)**
+
+## Quick start
+
+```bash
+pip install secretshield
+```
+
+Protect a running script:
+```python
+import secretshield   # that's it — stdout, stderr, and logging are now protected
+```
+
+Scan an entire project for hardcoded secrets:
+```bash
+secretshield scan .
+```
+
+Set a whole project up in one step (config file + Git hook + CI):
+```bash
+secretshield init
+```
+
+## What SecretShield does
+
+SecretShield isn't just one trick — it's five layers that cover the
+whole path a secret takes from your keyboard to a place you can't take
+it back from:
+
+| | |
+|---|---|
+| 🖥️ **Runtime protection** | Automatically redacts secrets from `stdout`, `stderr`, and `logging` the instant you `import secretshield` |
+| 🔍 **Static scanning** | `secretshield scan .` finds hardcoded secrets across Python, JS/TS, HTML, YAML, `.env`, and more |
+| 🔧 **Auto-Fix** | `scan . --fix` interactively moves a hardcoded secret into `.env` and rewrites your code to use it — safely, and only when it's unambiguous |
+| 🪝 **Git pre-commit hook** | `install-hook` blocks a commit before a secret ever reaches your repo's history |
+| ⚙️ **GitHub Actions** | `github-action` generates a workflow that scans every push and PR automatically |
+
+All of it: **zero required dependencies, no telemetry, no network calls, nothing sent anywhere.** Everything happens locally, in your own process.
+
+## Why star this repo
+
+If SecretShield has ever caught something before it hit your terminal
+or your Git history — that's the whole point of the project working.
+Starring it costs nothing and helps the next developer who's about to
+`print()` an API key by accident actually find this before it's too
+late.
+
+---
+
+## Installation
+
+```bash
+pip install secretshield
+```
+
+Requires Python 3.10+. No required third-party runtime dependencies
+(a tiny `tomli` backport is pulled in automatically, but only on Python 3.10).
+
+## Basic usage
+
+```python
+import secretshield
+
+password = "hunter2-example-not-real"
+print("Using password:", password)
+```
+
+```text
+Using password: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+Toggle protection manually if you need to:
+
+```python
+import secretshield
+
+secretshield.disable()
+secretshield.enable()      # idempotent, safe to call repeatedly
+secretshield.is_enabled()
+```
+
+Or use detection/redaction directly, without touching stdout at all:
+
+```python
+from secretshield import detect, redact
+
+detect("aws_key=AKIAABCDEFGHIJKLMNOP")
+# [Match(start=8, end=28, value='AKIA...', kind='aws_access_key_id')]
+
+redact("aws_key=AKIAABCDEFGHIJKLMNOP")
+# ("aws_key=********", True)
+```
+
+## CLI reference
+
+### `secretshield init` — set a project up in one step
+
+```bash
+secretshield init
+```
+
+Detects your project, then interactively offers to create a config
+file, install the Git hook, and generate the GitHub Actions workflow —
+all in one pass instead of discovering each command separately.
+
+### `secretshield scan` — find hardcoded secrets
+
+```bash
+secretshield scan .                       # scan a directory
+secretshield scan app.py                  # scan a single file
+secretshield scan . --json                # machine-readable, CI-safe
+secretshield scan . --fix                 # interactively move secrets to .env
+secretshield scan --staged                # would this commit introduce a secret?
+secretshield scan --diff HEAD~1           # did my changes introduce a secret?
+secretshield scan . --baseline            # adopt SecretShield without fixing everything today
+```
+
+Scans Python, JavaScript/TypeScript, HTML, CSS, Vue, Svelte, JSON,
+YAML, TOML/INI, `.env` files, shell scripts, and more — treating each
+as text and running the same detection engine regardless of language.
+Automatically skips `.git/`, `node_modules/`, `.venv/`, binary files,
+and obvious documentation placeholders like `your_api_key_here`.
+
+```text
+SecretShield scan
+
+✗ src/app.js:82
+  Potential secret: Bearer token
+  Type: token
+
+✓ 143 files scanned
+✗ 1 potential secret(s) found
+
+Exit code: 1
+```
+
+### `secretshield run` — protect a script without editing it
+
+```bash
+secretshield run app.py
+```
+
+### `secretshield install-hook` / `uninstall-hook` — stop secrets before they're committed
+
+```bash
+secretshield install-hook
+```
+
+Scans **staged content** (not your whole working tree) before every
+commit and blocks it if something looks like a secret. Never destroys
+an existing pre-commit hook — backs it up and wraps it instead.
+
+### `secretshield github-action` — catch what slips past locally
+
+```bash
+secretshield github-action
+```
+
+Generates `.github/workflows/secretshield.yml`, scanning every push and
+pull request automatically.
+
+## Configuration file
+
+Project-wide scan settings live in `secretshield.toml` (generate one
+with `secretshield init`):
+
+```toml
+[scan]
+entropy_threshold = 4.2
+
+[scan.ignore]
+paths = ["tests/fixtures/", "docs/examples/"]
+
+[scan.include]
+patterns = ["*.py", "*.js"]
+
+[output]
+format = "text"
+```
+
+CLI flags always override the file.
+
+## Runtime 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
+)
+```
+
+## Detection methods
+
+SecretShield combines two strategies:
+
+1. **Known-format pattern matching** — AWS keys, GitHub tokens,
+   OpenAI-style keys, Slack tokens, Stripe keys, Google API keys, JWTs,
+   bearer tokens, PEM private-key blocks, and labeled generic secrets
+   (`password =`, `api_key:`, etc.)
+2. **High-entropy detection** — catches random-looking secrets that
+   don't match a known format, used as a conservative supplement (not
+   the primary mechanism) to keep false positives low.
+
+## Architecture
+
+```text
+secretshield/
+├── patterns.py, detector.py, redactor.py   # detection & redaction engine
+├── guardian.py                              # stdout/stderr + logging protection
+├── config.py, notifications.py               # runtime settings & safe warnings
+├── project_config.py, baseline.py              # secretshield.toml, --baseline
+├── cli.py                                        # command-line interface
+├── autofix/                                        # interactive scan --fix
+├── git/                                              # pre-commit hook
+└── github/                                             # Actions workflow generation
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+176+ tests covering detection, redaction, runtime protection, static
+scanning across languages, Auto-Fix, Git hooks, and CI integration. All
+secrets used in tests and examples are fake.
+
+## Limitations
+
+Be honest about what this is and isn't:
+
+- Runtime protection covers **this Python process's** `stdout`,
+  `stderr`, and `logging` — not screenshots, clipboard, arbitrary file
+  writes, other applications, or network traffic.
+- **Auto-Fix (`--fix`)** only rewrites Python, and only unambiguous
+  simple assignments (checked via Python's own `ast` module, not a
+  regex). Anything less certain is reported but left untouched.
+- The pre-commit hook needs `secretshield` resolvable on `PATH` at
+  commit time — keep your virtual environment active.
+
+Treat SecretShield as a strong defense-in-depth safety net, not a
+replacement for proper secret management (vaults, least-privilege
+credentials, secret scanning in CI, etc.).
+
+## Security considerations
+
+No network calls. No telemetry. Nothing sent anywhere — detection and
+redaction happen entirely locally, in-process.
+
+## Contributing
+
+Issues and PRs welcome. Please 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.4.1/README.md

@@ -0,0 +1,327 @@
+<div align="center">
+
+# 🛡️ SecretShield
+
+**Your secrets shouldn't end up in your terminal, your logs, or your commit history.**
+**SecretShield makes sure they don't — automatically.**
+
+[![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](#installation) · [Demo](#demo) · [Quick start](#quick-start) · [Features](#what-secretshield-does) · [Docs below](#cli-reference)
+
+</div>
+
+---
+
+## The problem
+
+You've done this. Everyone has.
+
+```python
+print("API key:", api_key)          # ...now it's in your terminal history
+logger.info("Token: %s", token)     # ...now it's in your log files
+API_KEY = "sk-live-abc123..."       # ...now it's about to get committed
+```
+
+One `print()` left in from debugging. One log line that dumps a config
+dict. One hardcoded key that slips past code review. That's usually all
+it takes.
+
+## The fix
+
+```bash
+pip install secretshield
+```
+
+```python
+import secretshield
+
+api_key = "sk-example1234567890abcdefFAKEKEY"
+print("API key:", api_key)
+```
+
+```text
+API key: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+**No configuration. No code changes. Just `pip install` and `import`.**
+The moment you import it, your terminal output, your logs — protected.
+
+## Demo
+
+See SecretShield in action:
+
+[![SecretShield Demo](https://img.youtube.com/vi/g95lNIhWsXM/maxresdefault.jpg)](https://youtu.be/g95lNIhWsXM)
+
+**[▶ Watch the full demo on YouTube](https://youtu.be/g95lNIhWsXM)**
+
+## Quick start
+
+```bash
+pip install secretshield
+```
+
+Protect a running script:
+```python
+import secretshield   # that's it — stdout, stderr, and logging are now protected
+```
+
+Scan an entire project for hardcoded secrets:
+```bash
+secretshield scan .
+```
+
+Set a whole project up in one step (config file + Git hook + CI):
+```bash
+secretshield init
+```
+
+## What SecretShield does
+
+SecretShield isn't just one trick — it's five layers that cover the
+whole path a secret takes from your keyboard to a place you can't take
+it back from:
+
+| | |
+|---|---|
+| 🖥️ **Runtime protection** | Automatically redacts secrets from `stdout`, `stderr`, and `logging` the instant you `import secretshield` |
+| 🔍 **Static scanning** | `secretshield scan .` finds hardcoded secrets across Python, JS/TS, HTML, YAML, `.env`, and more |
+| 🔧 **Auto-Fix** | `scan . --fix` interactively moves a hardcoded secret into `.env` and rewrites your code to use it — safely, and only when it's unambiguous |
+| 🪝 **Git pre-commit hook** | `install-hook` blocks a commit before a secret ever reaches your repo's history |
+| ⚙️ **GitHub Actions** | `github-action` generates a workflow that scans every push and PR automatically |
+
+All of it: **zero required dependencies, no telemetry, no network calls, nothing sent anywhere.** Everything happens locally, in your own process.
+
+## Why star this repo
+
+If SecretShield has ever caught something before it hit your terminal
+or your Git history — that's the whole point of the project working.
+Starring it costs nothing and helps the next developer who's about to
+`print()` an API key by accident actually find this before it's too
+late.
+
+---
+
+## Installation
+
+```bash
+pip install secretshield
+```
+
+Requires Python 3.10+. No required third-party runtime dependencies
+(a tiny `tomli` backport is pulled in automatically, but only on Python 3.10).
+
+## Basic usage
+
+```python
+import secretshield
+
+password = "hunter2-example-not-real"
+print("Using password:", password)
+```
+
+```text
+Using password: ********
+⚠ secretshield: Potential secret detected and redacted.
+```
+
+Toggle protection manually if you need to:
+
+```python
+import secretshield
+
+secretshield.disable()
+secretshield.enable()      # idempotent, safe to call repeatedly
+secretshield.is_enabled()
+```
+
+Or use detection/redaction directly, without touching stdout at all:
+
+```python
+from secretshield import detect, redact
+
+detect("aws_key=AKIAABCDEFGHIJKLMNOP")
+# [Match(start=8, end=28, value='AKIA...', kind='aws_access_key_id')]
+
+redact("aws_key=AKIAABCDEFGHIJKLMNOP")
+# ("aws_key=********", True)
+```
+
+## CLI reference
+
+### `secretshield init` — set a project up in one step
+
+```bash
+secretshield init
+```
+
+Detects your project, then interactively offers to create a config
+file, install the Git hook, and generate the GitHub Actions workflow —
+all in one pass instead of discovering each command separately.
+
+### `secretshield scan` — find hardcoded secrets
+
+```bash
+secretshield scan .                       # scan a directory
+secretshield scan app.py                  # scan a single file
+secretshield scan . --json                # machine-readable, CI-safe
+secretshield scan . --fix                 # interactively move secrets to .env
+secretshield scan --staged                # would this commit introduce a secret?
+secretshield scan --diff HEAD~1           # did my changes introduce a secret?
+secretshield scan . --baseline            # adopt SecretShield without fixing everything today
+```
+
+Scans Python, JavaScript/TypeScript, HTML, CSS, Vue, Svelte, JSON,
+YAML, TOML/INI, `.env` files, shell scripts, and more — treating each
+as text and running the same detection engine regardless of language.
+Automatically skips `.git/`, `node_modules/`, `.venv/`, binary files,
+and obvious documentation placeholders like `your_api_key_here`.
+
+```text
+SecretShield scan
+
+✗ src/app.js:82
+  Potential secret: Bearer token
+  Type: token
+
+✓ 143 files scanned
+✗ 1 potential secret(s) found
+
+Exit code: 1
+```
+
+### `secretshield run` — protect a script without editing it
+
+```bash
+secretshield run app.py
+```
+
+### `secretshield install-hook` / `uninstall-hook` — stop secrets before they're committed
+
+```bash
+secretshield install-hook
+```
+
+Scans **staged content** (not your whole working tree) before every
+commit and blocks it if something looks like a secret. Never destroys
+an existing pre-commit hook — backs it up and wraps it instead.
+
+### `secretshield github-action` — catch what slips past locally
+
+```bash
+secretshield github-action
+```
+
+Generates `.github/workflows/secretshield.yml`, scanning every push and
+pull request automatically.
+
+## Configuration file
+
+Project-wide scan settings live in `secretshield.toml` (generate one
+with `secretshield init`):
+
+```toml
+[scan]
+entropy_threshold = 4.2
+
+[scan.ignore]
+paths = ["tests/fixtures/", "docs/examples/"]
+
+[scan.include]
+patterns = ["*.py", "*.js"]
+
+[output]
+format = "text"
+```
+
+CLI flags always override the file.
+
+## Runtime 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
+)
+```
+
+## Detection methods
+
+SecretShield combines two strategies:
+
+1. **Known-format pattern matching** — AWS keys, GitHub tokens,
+   OpenAI-style keys, Slack tokens, Stripe keys, Google API keys, JWTs,
+   bearer tokens, PEM private-key blocks, and labeled generic secrets
+   (`password =`, `api_key:`, etc.)
+2. **High-entropy detection** — catches random-looking secrets that
+   don't match a known format, used as a conservative supplement (not
+   the primary mechanism) to keep false positives low.
+
+## Architecture
+
+```text
+secretshield/
+├── patterns.py, detector.py, redactor.py   # detection & redaction engine
+├── guardian.py                              # stdout/stderr + logging protection
+├── config.py, notifications.py               # runtime settings & safe warnings
+├── project_config.py, baseline.py              # secretshield.toml, --baseline
+├── cli.py                                        # command-line interface
+├── autofix/                                        # interactive scan --fix
+├── git/                                              # pre-commit hook
+└── github/                                             # Actions workflow generation
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+176+ tests covering detection, redaction, runtime protection, static
+scanning across languages, Auto-Fix, Git hooks, and CI integration. All
+secrets used in tests and examples are fake.
+
+## Limitations
+
+Be honest about what this is and isn't:
+
+- Runtime protection covers **this Python process's** `stdout`,
+  `stderr`, and `logging` — not screenshots, clipboard, arbitrary file
+  writes, other applications, or network traffic.
+- **Auto-Fix (`--fix`)** only rewrites Python, and only unambiguous
+  simple assignments (checked via Python's own `ast` module, not a
+  regex). Anything less certain is reported but left untouched.
+- The pre-commit hook needs `secretshield` resolvable on `PATH` at
+  commit time — keep your virtual environment active.
+
+Treat SecretShield as a strong defense-in-depth safety net, not a
+replacement for proper secret management (vaults, least-privilege
+credentials, secret scanning in CI, etc.).
+
+## Security considerations
+
+No network calls. No telemetry. Nothing sent anywhere — detection and
+redaction happen entirely locally, in-process.
+
+## Contributing
+
+Issues and PRs welcome. Please 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.3.2 → secretshield-0.4.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "secretshield"
-version = "0.3.2"
-description = "Detect and redact likely secrets before they reach Python's terminal output or logging system."
+version = "0.4.1"
+description = "Detect, redact, and prevent secret exposure in Python apps, source code, and Git commits — runtime protection, multi-language scanning, auto-fix, and CI integration in one tool."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -23,7 +23,9 @@ classifiers = [
     "Topic :: Security",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-dependencies = []
+dependencies = [
+    "tomli>=2.0; python_version < \"3.11\"",
+]
 
 [project.optional-dependencies]
 dev = [