secretshield 0.2.0__tar.gz → 0.3.0__tar.gz

{secretshield-0.2.0 → secretshield-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Sam3360
+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

{secretshield-0.2.0 → secretshield-0.3.0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: secretshield
-Version: 0.2.0
+Version: 0.3.0
 Summary: Detect and redact likely secrets before they reach Python's terminal output or logging system.
-Author: Samarth Chugh (Sam3360)
-License: MIT
+Author: secretshield contributors
+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: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -266,6 +265,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:
@@ -292,7 +395,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:
@@ -353,6 +465,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