secretshield 0.2.1__tar.gz → 0.3.1__tar.gz

{secretshield-0.2.1 → secretshield-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secretshield
-Version: 0.2.1
+Version: 0.3.1
 Summary: Detect and redact likely secrets before they reach Python's terminal output or logging system.
 Author: Samarth Chugh (Sam3360)
 License-Expression: MIT
@@ -57,6 +57,15 @@ 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.
 
+## 🎥 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)**
+
+
 ## Installation
 
 ```bash
@@ -265,6 +274,110 @@ secretshield.configure(
 
 Sensible defaults mean most projects need zero configuration.
 
+## Auto-Fix -- moving secrets into `.env`
+
+```bash
+secretshield scan . --fix
+```
+
+`--fix` adds an *interactive* repair step on top of the normal scan.
+For each detected secret, SecretShield asks whether to move it into a
+local `.env` file:
+
+```text
+Secret 1/1 detected
+File: app.py
+Line: 5
+Detected value: ********
+
+Would you like me to move this secret to a local .env file automatically? [y/N]
+```
+
+If you confirm, this:
+
+```python
+API_KEY = "actual-secret-value"
+```
+
+becomes:
+
+```python
+import os
+
+API_KEY = os.getenv("API_KEY")
+```
+
+with the real value moved into `.env` (created if missing, and never
+overwritten -- new variables are only ever appended), `.gitignore`
+updated to exclude `.env` if it isn't already, and `.env.example`
+updated with a blank placeholder (`API_KEY=`, never the real value) so
+you can safely commit the example file.
+
+**Auto-Fix is conservative by design.** It only rewrites Python, and
+only lines that are unambiguously a simple assignment --
+`API_KEY = "..."`. Anything less certain -- a value inside a dict, an
+f-string, a function call argument, a non-Python file -- is reported
+but left untouched:
+
+```text
+Secret detected, but SecretShield could not safely determine how to
+replace it automatically.
+
+No changes were made.
+```
+
+Every fix is validated after being written (confirming the secret is
+gone from the source and present in `.env`); if anything about a fix
+fails, that file is rolled back to its original content rather than
+left half-modified. `--fix` only prompts in a real interactive
+terminal -- in CI or any non-interactive environment, it makes no
+changes and does not hang waiting for input.
+
+## Git pre-commit hook
+
+```bash
+secretshield install-hook
+```
+
+Installs a hook that scans **staged file contents** (not the whole
+working tree, and not what's merely on disk if you've only partially
+staged a file) before every commit, blocking it if a likely secret is
+found:
+
+```text
+SecretShield: scanning staged files...
+
+✗ Potential secret detected
+
+File: config.py
+Line: 14
+Type: API token
+
+Commit blocked.
+
+Remove the secret from the staged changes and try again.
+```
+
+If a `pre-commit` hook already exists, SecretShield never overwrites
+it: the original is backed up to `pre-commit.secretshield-backup` and
+wrapped so both run on every commit. Remove SecretShield's hook (and
+automatically restore any hook it wrapped) with:
+
+```bash
+secretshield uninstall-hook
+```
+
+## GitHub Actions
+
+```bash
+secretshield github-action
+```
+
+Generates `.github/workflows/secretshield.yml`, a workflow that installs
+SecretShield and runs `secretshield scan .` on every push and pull
+request, failing the check if a potential secret is found. Won't
+overwrite an existing workflow file unless you pass `--force`.
+
 ## Detection methods
 
 `secretshield` combines two strategies:
@@ -291,7 +404,16 @@ secretshield/
 ├── 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
+├── cli.py                    # `secretshield` command-line entry point
+├── autofix/                    # interactive scan --fix
+│   ├── fixer.py                  # orchestration, atomic writes, rollback
+│   ├── python.py                  # ast-based safe-assignment detection
+│   ├── env.py                      # safe .env / .env.example handling
+│   └── gitignore.py                 # ensures .env stays out of Git
+├── git/                                # pre-commit hook install/uninstall
+│   └── hooks.py
+└── github/                               # GitHub Actions workflow generation
+    └── actions.py
 ```
 
 Key design points:
@@ -352,6 +474,19 @@ 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.).
 
+**Auto-Fix (`--fix`)** only rewrites Python, and only when a line is
+unambiguously a simple `NAME = "value"` assignment (checked via Python's
+own `ast` module, not a regex). Secrets inside dicts, f-strings,
+function-call arguments, or any other language are reported but never
+automatically rewritten — you'll need to fix those by hand.
+
+**The pre-commit hook** invokes the `secretshield` command by name, so
+it needs to be resolvable on `PATH` at commit time. If you installed
+SecretShield inside a virtual environment, make sure that environment
+is active (or `secretshield` is otherwise on `PATH`) whenever you run
+`git commit` — otherwise the hook itself will fail to run rather than
+silently skip the scan.
+
 ## Security considerations
 
 * secretshield performs **no network calls** and collects **no