secretshield 0.3.2__tar.gz → 0.4.0__tar.gz

{secretshield-0.3.2 → secretshield-0.4.0}/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.3.2 → secretshield-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secretshield
-Version: 0.3.2
+Version: 0.4.0
 Summary: Detect and redact likely secrets before they reach Python's terminal output or logging system.
 Author: Samarth Chugh (Sam3360)
 License-Expression: MIT
@@ -19,6 +19,7 @@ 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
@@ -242,6 +243,62 @@ create noise — this filtering is narrow and only applies to `scan`
 output, not to runtime redaction, so it never risks hiding a real secret
 just because it resembles a placeholder pattern.
 
+While a scan runs, a live `Scanning... N files scanned` indicator is
+shown on stderr (only in an interactive terminal — never in CI logs or
+`--json` output, and it never touches the actual result output).
+
+### Scanning a subset of files: `--staged` and `--diff`
+
+```bash
+secretshield scan --staged
+secretshield scan --diff HEAD~1
+secretshield scan --diff origin/main...HEAD
+```
+
+`--staged` scans exactly what's staged for the next commit — the real
+Git *index* content, correct even if a file is only partially staged
+(so it can't be fooled by working-tree edits made after `git add`).
+Answers: *"would this commit introduce a secret?"*
+
+`--diff REF` scans the current on-disk content of files that differ
+from `REF` (any Git revision or range Git itself understands). Answers:
+*"did my changes introduce a secret?"*
+
+Both require running inside a Git repository and support all the usual
+flags (`--json`, `--include`, `--exclude`, `--entropy-threshold`).
+
+### Adopting SecretShield in an existing repo: `--baseline`
+
+A repo with a backlog of existing findings shouldn't have to fix all of
+them just to turn SecretShield on:
+
+```bash
+secretshield scan . --baseline
+```
+
+writes `.secretshield-baseline.json`, capturing every current finding
+as a hash of `(file, kind, value)` — never the plaintext secret itself,
+so the baseline file is safe to commit. From then on, ordinary scans
+automatically ignore anything already in the baseline and only fail on
+genuinely new findings:
+
+```text
+SecretShield scan
+
+✗ src/config.py:82
+  Potential secret: API token
+  Type: token
+
+✓ 412 existing finding(s) ignored by baseline
+✓ 413 files scanned
+✗ 1 potential secret(s) found
+
+Exit code: 1
+```
+
+Re-run `scan . --baseline` any time to refresh it after intentionally
+fixing or accepting findings.
+
 ---
 
 **`scan` is static analysis; `run` (and the automatic protection on
@@ -259,6 +316,74 @@ supported languages -- for likely exposed secrets without
 executing or importing them.
 ```
 
+## Project setup: `secretshield init`
+
+```bash
+secretshield init
+```
+
+An interactive wizard for setting a project up in one step instead of
+discovering `install-hook`, `github-action`, and configuration
+separately:
+
+```text
+SecretShield project setup
+
+✓ Detected Python project
+✓ Detected Git repository
+
+Create a secretshield.toml configuration file? [Y/n]:
+Install Git pre-commit hook? [Y/n]:
+Generate GitHub Actions workflow? [Y/n]:
+
+Apply this setup? [Y/n]:
+
+✓ Created secretshield.toml
+✓ SecretShield pre-commit hook installed.
+✓ Created .github/workflows/secretshield.yml
+
+SecretShield is ready.
+```
+
+Requires a real interactive terminal — like `--fix`, it refuses to run
+(and makes no changes) in CI or any non-interactive environment.
+
+## Configuration file
+
+Project-wide `scan` settings can live in `secretshield.toml` at the
+project root, so `--entropy-threshold`, `--include`, and `--exclude`
+don't need to be retyped on every invocation (`secretshield init` can
+generate a starting file for you):
+
+```toml
+[scan]
+entropy_threshold = 4.2
+
+[scan.ignore]
+paths = [
+    "tests/fixtures/",
+    "docs/examples/",
+]
+
+[scan.include]
+patterns = [
+    "*.py",
+    "*.js",
+]
+
+[output]
+format = "text"
+```
+
+`secretshield scan .` reads this file automatically if it's present.
+**Explicit CLI flags always override it** — e.g. `--json` wins over
+`format = "text"` in the file, and `--entropy-threshold 3.0` wins over
+whatever the file says. Paths under `[scan.ignore]` ending in `/` are
+treated as "this directory and everything under it," same as the
+`--exclude` flag. On Python 3.10 this needs the small `tomli` package
+(installed automatically as a conditional dependency); 3.11+ uses the
+standard library's `tomllib` with no extra dependency at all.
+
 ## Configuration
 
 ```python
@@ -405,6 +530,8 @@ secretshield/
 ├── notifications.py      # safe, secret-free console/desktop warnings
 ├── guardian.py             # stdout/stderr wrapping + logging record-factory hook
 ├── cli.py                    # `secretshield` command-line entry point
+├── project_config.py           # secretshield.toml loading
+├── baseline.py                   # --baseline: hashed findings, no plaintext
 ├── autofix/                    # interactive scan --fix
 │   ├── fixer.py                  # orchestration, atomic writes, rollback
 │   ├── python.py                  # ast-based safe-assignment detection