secretscreen 0.1.0__tar.gz

secretscreen-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/secretscreen/
+
+      - name: Test
+        run: pytest --tb=short -q

secretscreen-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

secretscreen-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.swp
+*.swo
+.env
+.venv/

secretscreen-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Cron <cron@featurecreep.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package vendors pattern data from the gitleaks project
+(https://github.com/gitleaks/gitleaks), which is also MIT-licensed.

secretscreen-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: secretscreen
+Version: 0.1.0
+Summary: Detect and redact secrets in key-value pairs, dicts, and environment variables.
+Project-URL: Homepage, https://github.com/featurecreep-cron/secretscreen
+Project-URL: Issues, https://github.com/featurecreep-cron/secretscreen/issues
+Author-email: Cron <cron@featurecreep.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docker,environment,redaction,secrets,security
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# secretscreen
+
+[![CI](https://github.com/featurecreep-cron/secretscreen/actions/workflows/ci.yml/badge.svg)](https://github.com/featurecreep-cron/secretscreen/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Ffeaturecreep-cron%2Fsecretscreen%2Fmain%2Fpyproject.toml)](https://pypi.org/project/secretscreen/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Detect and redact secrets in key-value pairs, dicts, and environment variables.
+
+Best-effort defense-in-depth. Not a security boundary.
+
+## Install
+
+```
+pip install secretscreen
+```
+
+## Quick start
+
+```python
+from secretscreen import redact_pair, redact_dict, audit_dict, Mode
+
+# Single pair
+redact_pair("DB_PASSWORD", "hunter2")        # → "[REDACTED]"
+redact_pair("APP_NAME", "myapp")             # → "myapp"
+
+# Dict with recursion
+redact_dict({"db": {"password": "x", "host": "localhost"}})
+# → {"db": {"password": "[REDACTED]", "host": "localhost"}}
+
+# Aggressive mode (adds entropy detection)
+redact_dict(env, mode=Mode.AGGRESSIVE)
+
+# Audit mode (structured findings, no mutation)
+findings = audit_dict(env)
+# → [Finding(key="DB_PASSWORD", reason="key_pattern:password", ...)]
+
+# Custom safe suffixes (keys ending with these are never redacted)
+redact_dict(env, safe_suffixes=("_config", "_enabled"))
+```
+
+## Detection layers
+
+1. **Key-name denylist** — substring match against ~30 known secret key patterns
+2. **Structured value parsing** — JSON, Python literals, DSN, INI, URL query params
+3. **Value-format detection** — 222 known formats via vendored [gitleaks](https://github.com/gitleaks/gitleaks) patterns (MIT)
+4. **URL credential detection** — partial redaction of `user:pass@host` URLs
+5. **Entropy detection** — Shannon entropy for machine-generated strings (aggressive mode only)
+
+## License
+
+MIT. Gitleaks patterns are also MIT-licensed.

secretscreen-0.1.0/README.md

@@ -0,0 +1,51 @@
+# secretscreen
+
+[![CI](https://github.com/featurecreep-cron/secretscreen/actions/workflows/ci.yml/badge.svg)](https://github.com/featurecreep-cron/secretscreen/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Ffeaturecreep-cron%2Fsecretscreen%2Fmain%2Fpyproject.toml)](https://pypi.org/project/secretscreen/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Detect and redact secrets in key-value pairs, dicts, and environment variables.
+
+Best-effort defense-in-depth. Not a security boundary.
+
+## Install
+
+```
+pip install secretscreen
+```
+
+## Quick start
+
+```python
+from secretscreen import redact_pair, redact_dict, audit_dict, Mode
+
+# Single pair
+redact_pair("DB_PASSWORD", "hunter2")        # → "[REDACTED]"
+redact_pair("APP_NAME", "myapp")             # → "myapp"
+
+# Dict with recursion
+redact_dict({"db": {"password": "x", "host": "localhost"}})
+# → {"db": {"password": "[REDACTED]", "host": "localhost"}}
+
+# Aggressive mode (adds entropy detection)
+redact_dict(env, mode=Mode.AGGRESSIVE)
+
+# Audit mode (structured findings, no mutation)
+findings = audit_dict(env)
+# → [Finding(key="DB_PASSWORD", reason="key_pattern:password", ...)]
+
+# Custom safe suffixes (keys ending with these are never redacted)
+redact_dict(env, safe_suffixes=("_config", "_enabled"))
+```
+
+## Detection layers
+
+1. **Key-name denylist** — substring match against ~30 known secret key patterns
+2. **Structured value parsing** — JSON, Python literals, DSN, INI, URL query params
+3. **Value-format detection** — 222 known formats via vendored [gitleaks](https://github.com/gitleaks/gitleaks) patterns (MIT)
+4. **URL credential detection** — partial redaction of `user:pass@host` URLs
+5. **Entropy detection** — Shannon entropy for machine-generated strings (aggressive mode only)
+
+## License
+
+MIT. Gitleaks patterns are also MIT-licensed.

secretscreen-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "secretscreen"
+version = "0.1.0"
+description = "Detect and redact secrets in key-value pairs, dicts, and environment variables."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Cron", email = "cron@featurecreep.dev" }]
+keywords = ["secrets", "redaction", "security", "environment", "docker"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "ruff>=0.4", "mypy>=1.10"]
+
+[project.urls]
+Homepage = "https://github.com/featurecreep-cron/secretscreen"
+Issues = "https://github.com/featurecreep-cron/secretscreen/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/secretscreen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
+ignore = ["SIM102", "SIM108"]

secretscreen-0.1.0/src/secretscreen/__init__.py

@@ -0,0 +1,37 @@
+"""Detect and redact secrets in key-value pairs, dicts, and environment variables.
+
+Best-effort defense-in-depth. Not a security boundary.
+
+Five detection layers:
+1. Key-name denylist — substring match against known secret key patterns.
+2. Structured value parsing — JSON, Python literals, INI, DSN, URL query params.
+3. Value-format detection — 222 known secret formats via vendored gitleaks patterns.
+4. URL credential detection — partial redaction of embedded passwords.
+5. Entropy detection — Shannon entropy for machine-generated strings (aggressive mode).
+
+Two modes:
+- NORMAL: layers 1-4, zero false positives target.
+- AGGRESSIVE: layers 1-5, adds entropy detection.
+
+audit_pair() and audit_dict() return structured findings without mutating values.
+"""
+
+from secretscreen._core import (
+    Finding,
+    Mode,
+    audit_dict,
+    audit_pair,
+    redact_dict,
+    redact_pair,
+)
+
+__all__ = [
+    "Finding",
+    "Mode",
+    "audit_dict",
+    "audit_pair",
+    "redact_dict",
+    "redact_pair",
+]
+
+__version__ = "0.1.0"

secretscreen-0.1.0/src/secretscreen/_core.py

@@ -0,0 +1,339 @@
+"""Core orchestration — ties all detection layers together.
+
+Public API: redact_pair, redact_dict, audit_pair, audit_dict.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+from secretscreen._entropy import looks_like_secret
+from secretscreen._formats import matches_known_format
+from secretscreen._keys import (
+    DEFAULT_KEY_PATTERNS,
+    DEFAULT_SAFE_SUFFIXES,
+    matches_key_pattern,
+)
+from secretscreen._parsers import extract_pairs
+from secretscreen._urls import has_url_credentials, redact_url_password
+
+REDACTED = "[REDACTED]"
+
+
+class Mode(enum.Enum):
+    """Detection mode controlling which layers are active."""
+
+    NORMAL = "normal"
+    """Layers 1-4: key patterns, structured parsing, format detection, URL credentials."""
+
+    AGGRESSIVE = "aggressive"
+    """Layers 1-5: adds Shannon entropy detection for machine-generated strings."""
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """A detected secret with metadata about how it was found."""
+
+    key: str
+    reason: str
+    layer: str
+    detail: str = ""
+
+
+@dataclass
+class ScreenConfig:
+    """Configuration for secret screening."""
+
+    mode: Mode = Mode.NORMAL
+    replacement: str = REDACTED
+    extra_keys: tuple[str, ...] = ()
+    safe_suffixes: tuple[str, ...] = DEFAULT_SAFE_SUFFIXES
+    entropy_threshold: float = 4.5
+
+    def __post_init__(self) -> None:
+        """Pre-compute merged patterns to avoid recomputation per key."""
+        if not self.extra_keys:
+            self._patterns = DEFAULT_KEY_PATTERNS
+        else:
+            seen = {p.lower() for p in DEFAULT_KEY_PATTERNS}
+            extra = tuple(p for p in self.extra_keys if p.lower() not in seen)
+            self._patterns = DEFAULT_KEY_PATTERNS + extra
+
+    @property
+    def patterns(self) -> tuple[str, ...]:
+        """Merged key patterns (defaults + extras)."""
+        return self._patterns
+
+
+def redact_pair(
+    key: str,
+    value: str,
+    *,
+    mode: Mode = Mode.NORMAL,
+    replacement: str = REDACTED,
+    extra_keys: tuple[str, ...] = (),
+    safe_suffixes: tuple[str, ...] = DEFAULT_SAFE_SUFFIXES,
+    entropy_threshold: float = 4.5,
+) -> str:
+    """Redact a single key-value pair if the value is detected as a secret.
+
+    Returns the replacement string if secret, or the original value.
+    """
+    if not isinstance(value, str) or not value:
+        return value
+
+    config = ScreenConfig(
+        mode=mode,
+        replacement=replacement,
+        extra_keys=extra_keys,
+        safe_suffixes=safe_suffixes,
+        entropy_threshold=entropy_threshold,
+    )
+
+    finding = _detect(key, value, config)
+    if finding is None:
+        return value
+
+    return _apply_redaction(finding, key, value, config)
+
+
+def redact_dict(
+    data: dict[str, object] | list[object] | object,
+    *,
+    mode: Mode = Mode.NORMAL,
+    replacement: str = REDACTED,
+    extra_keys: tuple[str, ...] = (),
+    safe_suffixes: tuple[str, ...] = DEFAULT_SAFE_SUFFIXES,
+    entropy_threshold: float = 4.5,
+) -> object:
+    """Recursively redact secrets in a dict, list, or nested structure.
+
+    Returns a new structure with secrets replaced. Does not mutate the input.
+    """
+    config = ScreenConfig(
+        mode=mode,
+        replacement=replacement,
+        extra_keys=extra_keys,
+        safe_suffixes=safe_suffixes,
+        entropy_threshold=entropy_threshold,
+    )
+    return _redact_recursive(data, config)
+
+
+def audit_pair(
+    key: str,
+    value: str,
+    *,
+    mode: Mode = Mode.NORMAL,
+    extra_keys: tuple[str, ...] = (),
+    safe_suffixes: tuple[str, ...] = DEFAULT_SAFE_SUFFIXES,
+    entropy_threshold: float = 4.5,
+) -> Finding | None:
+    """Check a single key-value pair for secrets without redacting.
+
+    Returns a Finding if detected, or None.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+
+    config = ScreenConfig(
+        mode=mode,
+        extra_keys=extra_keys,
+        safe_suffixes=safe_suffixes,
+        entropy_threshold=entropy_threshold,
+    )
+    return _detect(key, value, config)
+
+
+def audit_dict(
+    data: dict[str, object] | list[object] | object,
+    *,
+    mode: Mode = Mode.NORMAL,
+    extra_keys: tuple[str, ...] = (),
+    safe_suffixes: tuple[str, ...] = DEFAULT_SAFE_SUFFIXES,
+    entropy_threshold: float = 4.5,
+) -> list[Finding]:
+    """Recursively audit a dict/list for secrets without redacting.
+
+    Returns a list of all findings.
+    """
+    config = ScreenConfig(
+        mode=mode,
+        extra_keys=extra_keys,
+        safe_suffixes=safe_suffixes,
+        entropy_threshold=entropy_threshold,
+    )
+    findings: list[Finding] = []
+    _audit_recursive(data, config, findings)
+    return findings
+
+
+
+# Maximum recursion depth for structured parsing detection.
+# Prevents stack overflow from crafted nested JSON/Python literals.
+_MAX_DETECT_DEPTH = 3
+
+
+def _detect(
+    key: str, value: str, config: ScreenConfig, _depth: int = 0
+) -> Finding | None:
+    """Run all detection layers on a single key-value pair."""
+
+    # Layer 1: Key-name pattern match
+    matched_pattern = matches_key_pattern(key, config.patterns, config.safe_suffixes)
+    if matched_pattern is not None:
+        # URL keys get partial redaction, not full
+        if key.lower().endswith("_url") and has_url_credentials(value):
+            return Finding(
+                key=key,
+                reason=f"key_pattern:{matched_pattern}",
+                layer="url_credentials",
+                detail="URL with embedded credentials",
+            )
+        return Finding(
+            key=key,
+            reason=f"key_pattern:{matched_pattern}",
+            layer="key_pattern",
+        )
+
+    # Layer 4: URL credential detection (even without key pattern match)
+    if has_url_credentials(value):
+        return Finding(
+            key=key,
+            reason="url_credentials",
+            layer="url_credentials",
+            detail="URL with embedded credentials",
+        )
+
+    # Layer 2: Structured value parsing (depth-limited to prevent recursion bombs)
+    if _depth < _MAX_DETECT_DEPTH:
+        pairs = extract_pairs(value)
+    else:
+        pairs = []
+    if pairs:
+        for sub_key, sub_value in pairs:
+            sub_finding = _detect(sub_key, sub_value, config, _depth + 1)
+            if sub_finding is not None:
+                return Finding(
+                    key=key,
+                    reason=f"structured:{sub_key}={sub_finding.reason}",
+                    layer="structured_parsing",
+                    detail=f"Found secret in parsed structure: {sub_key}",
+                )
+
+    # Layer 3: Value-format detection (gitleaks patterns)
+    format_match = matches_known_format(value)
+    if format_match is not None:
+        return Finding(
+            key=key,
+            reason=f"format:{format_match.id}",
+            layer="format_detection",
+            detail=format_match.description,
+        )
+
+    # Layer 5: Entropy detection (aggressive mode only)
+    if config.mode == Mode.AGGRESSIVE:
+        entropy = looks_like_secret(value, config.entropy_threshold)
+        if entropy is not None:
+            return Finding(
+                key=key,
+                reason=f"entropy:{entropy:.2f}",
+                layer="entropy",
+                detail=f"Shannon entropy {entropy:.2f} bits/char exceeds threshold",
+            )
+
+    return None
+
+
+def _apply_redaction(
+    finding: Finding, key: str, value: str, config: ScreenConfig
+) -> str:
+    """Apply the appropriate redaction strategy based on finding layer.
+
+    Single source of truth for layer-specific redaction behavior.
+    Used by both redact_pair and _redact_recursive.
+    """
+    if finding.layer == "url_credentials":
+        return redact_url_password(value, config.replacement)
+
+    if finding.layer == "structured_parsing":
+        return _redact_structured(value, config)
+
+    return config.replacement
+
+
+def _redact_structured(value: str, config: ScreenConfig) -> str:
+    """Redact secret portions within a structured value string.
+
+    Re-parses the value and replaces only exact secret values, tracking
+    which values have been replaced to avoid collateral damage when a
+    secret string appears as a substring of a non-secret value.
+    """
+    pairs = extract_pairs(value)
+    # Collect secret values and their replacements
+    secrets_to_redact: dict[str, str] = {}
+    for sub_key, sub_value in pairs:
+        if not sub_value:
+            continue
+        sub_finding = _detect(sub_key, sub_value, config)
+        if sub_finding is not None:
+            secrets_to_redact[sub_value] = config.replacement
+
+    if not secrets_to_redact:
+        return value
+
+    # Replace longest secrets first to avoid partial matches
+    # when one secret is a substring of another
+    redacted = value
+    for secret in sorted(secrets_to_redact, key=len, reverse=True):
+        redacted = redacted.replace(secret, secrets_to_redact[secret])
+    return redacted
+
+
+def _redact_recursive(
+    data: object,
+    config: ScreenConfig,
+) -> object:
+    """Recursively walk and redact a nested structure."""
+    if isinstance(data, dict):
+        out: dict[object, object] = {}
+        for k, v in data.items():
+            key_str = str(k)
+            if isinstance(v, str):
+                finding = _detect(key_str, v, config)
+                if finding is not None:
+                    out[k] = _apply_redaction(finding, key_str, v, config)
+                else:
+                    out[k] = v
+            elif isinstance(v, (dict, list)):
+                out[k] = _redact_recursive(v, config)
+            else:
+                out[k] = v
+        return out
+
+    if isinstance(data, list):
+        return [_redact_recursive(item, config) for item in data]
+
+    return data
+
+
+def _audit_recursive(
+    data: object,
+    config: ScreenConfig,
+    findings: list[Finding],
+) -> None:
+    """Recursively walk and audit a nested structure."""
+    if isinstance(data, dict):
+        for k, v in data.items():
+            key_str = str(k)
+            if isinstance(v, str):
+                finding = _detect(key_str, v, config)
+                if finding is not None:
+                    findings.append(finding)
+            elif isinstance(v, (dict, list)):
+                _audit_recursive(v, config, findings)
+
+    elif isinstance(data, list):
+        for item in data:
+            _audit_recursive(item, config, findings)