secretshield 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secretshield
-Version: 0.1.2
+Version: 0.2.0
 Summary: Detect and redact likely secrets before they reach Python's terminal output or logging system.
 Author: Samarth Chugh (Sam3360)
 License: MIT
@@ -152,20 +152,104 @@ useful for wrapping an existing script without editing its source.
 ```bash
 secretshield scan .
 secretshield scan path/to/file.py
+secretshield scan src/ --json
 ```
 
-Scans a file, or recursively scans a directory of text-like files
-(`.py`, `.txt`, `.md`, `.env`, `.yml`, `.json`, `.ini`, `.toml`, `.sh`,
-`.js`, `.ts`, etc.), reporting the *kind* and *location* of any likely
-secrets found. `scan` does **not** execute any code and does **not**
-print the secret values themselves — only where they were found. It
-exits with status `1` if anything was found, `0` otherwise, so it can be
-used as a pre-commit or CI check.
+`scan` recursively scans a directory (or a single file) of text-based
+project files, reporting the *kind* and *location* of any likely secrets
+found. It does **not** execute or import anything it scans, and it never
+prints the secret values themselves — only which file, which line, and
+what kind of credential it looks like.
+
+**Supported file types** include Python, JavaScript/JSX, TypeScript/TSX,
+HTML, CSS/SCSS, Vue, Svelte, JSON/JSONC, YAML, TOML/INI/CFG/CONF, `.env`
+and `.env.*` variants, shell scripts (`.sh`/`.bash`/`.zsh`), Windows
+scripts (`.ps1`/`.bat`/`.cmd`), XML, Markdown/plain text, SQL, and
+GraphQL. Extensionless files (`Dockerfile`, `Makefile`, etc.) are also
+scanned as long as they're actually text, not binary. Files are treated
+purely as text — the same `detect()` engine used for runtime protection
+does the work, regardless of which language the file is written in.
+
+By default, `scan` skips common non-source directories: `.git/`,
+`node_modules/`, `__pycache__/`, `.venv/`/`venv/`, `dist/`, `build/`,
+`coverage/`, and a few similar cache directories. It also skips binary
+files automatically (detected by sniffing for null bytes / invalid
+UTF-8), so pointing it at a directory containing images, compiled
+artifacts, etc. is safe.
+
+**Example output:**
+
+```text
+SecretShield scan
+
+✗ src/app.js:82
+  Potential secret: Bearer token
+  Type: token
+
+✓ 143 files scanned
+✗ 1 potential secret(s) found
+
+Exit code: 1
+```
+
+If nothing is found:
+
+```text
+SecretShield scan
+
+✓ 143 files scanned
+✓ No potential secrets found
+
+Exit code: 0
+```
+
+**Options:**
+
+| Flag | Purpose |
+|---|---|
+| `--json` | Machine-readable JSON output instead of the text report (see below). Safe to pipe into CI — never contains secret values, matched text, or surrounding lines. |
+| `--include PATTERN` | Only scan files matching a glob pattern (filename or relative path). Repeatable. |
+| `--exclude PATTERN` | Skip files matching a glob pattern. Repeatable. Always wins over `--include` and the defaults. |
+| `--no-ignore` | Don't skip the default-ignored directories (`.git`, `node_modules`, etc.). |
+| `--entropy-threshold FLOAT` | Shannon entropy threshold for generic high-entropy detection (default `4.2`). |
+
+**`--json` output shape:**
+
+```json
+{
+  "files_scanned": 143,
+  "matches": [
+    {"file": "src/app.js", "line": 82, "kind": "bearer_token"}
+  ],
+  "secrets_found": 1
+}
+```
+
+Exit code is `1` if `secrets_found > 0`, `0` otherwise — identical logic
+to the text output, so `scan` works the same way as a CI gate either way.
+
+Obvious documentation placeholders (`your_api_key_here`, `changeme`,
+`xxxxxxxx`, and similar) are filtered out of scan results so they don't
+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.
+
+---
 
 **`scan` is static analysis; `run` (and the automatic protection on
-import) is runtime redaction.** They are separate features: `scan`
-looks at file contents on disk, `run`/import-time protection looks at
-what a running program actually writes out.
+import) is runtime redaction.** They are separate, complementary
+features:
+
+```text
+Runtime protection:
+Protects what a running Python application writes to stdout,
+stderr, and logging, live, as it happens.
+
+Static scanning:
+Searches source/configuration files on disk -- in any of the
+supported languages -- for likely exposed secrets without
+executing or importing them.
+```
 
 ## Configuration