shieldenv 1.0.0__tar.gz

shieldenv-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShieldRunner 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
+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.

shieldenv-1.0.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: shieldenv
+Version: 1.0.0
+Summary: Local-first secret and AI API key leak prevention CLI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Dynamic: license-file
+
+# ShieldEnv 🛡️
+Local-First Secret Scanning & Pre-Commit Guardraill
+
+ShieldEnv is an open-source security engine designed to eliminate accidental credential leaks, API key exposures, and compliance violations before code ever hits version control.
+
+### Why Local-First?
+Unlike cloud-based PR scanners that analyze your code after it leaves your machine, ShieldEnv runs entirely local-first. Zero code, environment variables, or tokens ever leave your local environment.
+
+## Features
+
+- Regex detection for OpenAI, Anthropic, Google, AWS, GitHub, Slack, database URLs, private keys, and generic secret assignments.
+- Provider rules include confidence levels (`high` or `medium`).
+- Entropy-based detection for literal custom tokens.
+- Built-in filtering for placeholders, environment substitutions, templates, and common generated/UI syntax.
+- Project and user-level `.shieldignore` support.
+- Text, JSON, and SARIF output for local and CI use.
+- Optional Git pre-commit hook installation.
+- Redacted findings that never print complete secret values.
+
+## Installation
+
+Create an environment and install ShieldEnv:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+On Windows PowerShell, activate with:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+shieldenv scan
+```
+
+Scan another path or emit machine-readable JSON:
+
+```bash
+shieldenv scan --path ./src --format json
+```
+
+Generate GitHub Code Scanning-compatible SARIF:
+
+```bash
+shieldenv scan --path . --format sarif > shieldenv.sarif
+```
+
+Use verbose mode to inspect scan coverage and ignored paths:
+
+```bash
+shieldenv scan --verbose
+shieldenv scan --audit --format json
+```
+
+Exit codes:
+
+- `0`: no findings and no scan errors.
+- `1`: one or more potential secrets were found.
+- `2`: one or more files could not be read.
+
+Install a Git pre-commit hook from the repository root:
+
+```bash
+shieldenv install
+```
+
+ShieldEnv will not overwrite an existing hook unless explicitly requested:
+
+```bash
+shieldenv install --force
+```
+
+With `--force`, an existing hook is saved as `.git/hooks/pre-commit.shieldenv-backup`.
+
+## Ignore rules
+
+ShieldEnv skips common dependency, build, cache, and lock-file paths by default. Add a project-level `.shieldignore` at the root being scanned, or a global `~/.shieldignore`, with one rule per line:
+
+```text
+# Exact directory name anywhere in the tree
+generated
+
+# Relative path or glob
+backend/app/api/
+frontend/generated/**
+```
+
+Blank lines and lines beginning with `#` are ignored. Use ignore rules carefully: excluded files are not scanned. `--verbose` lists ignored paths so exclusions can be reviewed.
+
+To suppress a deliberate test value on one line, use the explicit marker:
+
+```python
+TEST_TOKEN = "not-a-credential"  # shieldenv: ignore
+```
+
+Suppressions are recorded in audit JSON output. Keep suppressions rare and review them during code review.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+```
+
+ShieldEnv is heuristic-based and should complement, not replace, secret rotation and incident-response procedures. Review findings and maintain project-specific ignore rules for generated code.
+
+ShieldEnv cannot guarantee detection of every secret format. It combines provider signatures, structured assignment patterns, and entropy heuristics, so unusual encodings may be missed and generated or identifier-like values may still require review. The scanner intentionally reports findings without exposing full values. Run it in CI on Linux, Windows, and macOS; the included workflow tests Python 3.9 through 3.13.
+
+Provider signatures are high-confidence indicators; generic assignments and entropy findings are medium-confidence heuristics. A clean scan means no supported rule matched, not that the repository is guaranteed secret-free. Rotate any credential that may have been exposed, and use code review and repository access controls alongside ShieldEnv.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

shieldenv-1.0.0/README.md

@@ -0,0 +1,121 @@
+# ShieldEnv 🛡️
+Local-First Secret Scanning & Pre-Commit Guardraill
+
+ShieldEnv is an open-source security engine designed to eliminate accidental credential leaks, API key exposures, and compliance violations before code ever hits version control.
+
+### Why Local-First?
+Unlike cloud-based PR scanners that analyze your code after it leaves your machine, ShieldEnv runs entirely local-first. Zero code, environment variables, or tokens ever leave your local environment.
+
+## Features
+
+- Regex detection for OpenAI, Anthropic, Google, AWS, GitHub, Slack, database URLs, private keys, and generic secret assignments.
+- Provider rules include confidence levels (`high` or `medium`).
+- Entropy-based detection for literal custom tokens.
+- Built-in filtering for placeholders, environment substitutions, templates, and common generated/UI syntax.
+- Project and user-level `.shieldignore` support.
+- Text, JSON, and SARIF output for local and CI use.
+- Optional Git pre-commit hook installation.
+- Redacted findings that never print complete secret values.
+
+## Installation
+
+Create an environment and install ShieldEnv:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+On Windows PowerShell, activate with:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+shieldenv scan
+```
+
+Scan another path or emit machine-readable JSON:
+
+```bash
+shieldenv scan --path ./src --format json
+```
+
+Generate GitHub Code Scanning-compatible SARIF:
+
+```bash
+shieldenv scan --path . --format sarif > shieldenv.sarif
+```
+
+Use verbose mode to inspect scan coverage and ignored paths:
+
+```bash
+shieldenv scan --verbose
+shieldenv scan --audit --format json
+```
+
+Exit codes:
+
+- `0`: no findings and no scan errors.
+- `1`: one or more potential secrets were found.
+- `2`: one or more files could not be read.
+
+Install a Git pre-commit hook from the repository root:
+
+```bash
+shieldenv install
+```
+
+ShieldEnv will not overwrite an existing hook unless explicitly requested:
+
+```bash
+shieldenv install --force
+```
+
+With `--force`, an existing hook is saved as `.git/hooks/pre-commit.shieldenv-backup`.
+
+## Ignore rules
+
+ShieldEnv skips common dependency, build, cache, and lock-file paths by default. Add a project-level `.shieldignore` at the root being scanned, or a global `~/.shieldignore`, with one rule per line:
+
+```text
+# Exact directory name anywhere in the tree
+generated
+
+# Relative path or glob
+backend/app/api/
+frontend/generated/**
+```
+
+Blank lines and lines beginning with `#` are ignored. Use ignore rules carefully: excluded files are not scanned. `--verbose` lists ignored paths so exclusions can be reviewed.
+
+To suppress a deliberate test value on one line, use the explicit marker:
+
+```python
+TEST_TOKEN = "not-a-credential"  # shieldenv: ignore
+```
+
+Suppressions are recorded in audit JSON output. Keep suppressions rare and review them during code review.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+```
+
+ShieldEnv is heuristic-based and should complement, not replace, secret rotation and incident-response procedures. Review findings and maintain project-specific ignore rules for generated code.
+
+ShieldEnv cannot guarantee detection of every secret format. It combines provider signatures, structured assignment patterns, and entropy heuristics, so unusual encodings may be missed and generated or identifier-like values may still require review. The scanner intentionally reports findings without exposing full values. Run it in CI on Linux, Windows, and macOS; the included workflow tests Python 3.9 through 3.13.
+
+Provider signatures are high-confidence indicators; generic assignments and entropy findings are medium-confidence heuristics. A clean scan means no supported rule matched, not that the repository is guaranteed secret-free. Rotate any credential that may have been exposed, and use code review and repository access controls alongside ShieldEnv.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

shieldenv-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shieldenv"
+version = "1.0.0"
+description = "Local-first secret and AI API key leak prevention CLI"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "click>=8.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.6.0",
+]
+
+[project.scripts]
+shieldenv = "shieldenv.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+exclude = [
+    "build",
+    "full-stack-fastapi-template",
+    "juice-shop",
+    "venv",
+    ".venv",
+]

shieldenv-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shieldenv-1.0.0/shieldenv/__init__.py

@@ -0,0 +1,6 @@
+"""ShieldEnv: fast secret scanning for repositories and CI pipelines."""
+
+from .scanner import Finding, ScanResult, scan_path
+
+__all__ = ["Finding", "ScanResult", "scan_path"]
+__version__ = "1.0.0"

shieldenv-1.0.0/shieldenv/cli.py

@@ -0,0 +1,204 @@
+import codecs
+import json
+import os
+import shlex
+import sys
+from pathlib import Path
+
+import click
+
+from .scanner import scan_path
+
+
+def _configure_utf8_stream(stream):
+    """Use UTF-8 for real Windows streams without disrupting Click capture."""
+    if sys.platform != "win32":
+        return stream
+
+    reconfigure = getattr(stream, "reconfigure", None)
+    if reconfigure is not None:
+        try:
+            reconfigure(encoding="utf-8", errors="strict")
+            return stream
+        except (AttributeError, OSError, ValueError):
+            pass
+
+    buffer = getattr(stream, "buffer", None)
+    if buffer is not None:
+        return codecs.getwriter("utf-8")(buffer, "strict")
+    return stream
+
+
+def _configure_utf8_streams():
+    sys.stdout = _configure_utf8_stream(sys.stdout)
+    sys.stderr = _configure_utf8_stream(sys.stderr)
+
+
+def safe_echo(message="", **kwargs):
+    try:
+        click.echo(message, **kwargs)
+    except UnicodeEncodeError:
+        fallback = str(message).encode("ascii", "replace").decode("ascii")
+        click.echo(fallback, **kwargs)
+
+
+@click.group()
+def main():
+    """ShieldEnv: A local-first security scanner for hardcoded secrets and API keys."""
+    _configure_utf8_streams()
+
+@main.command()
+@click.option("--path", default=".", help="Root directory to scan for secrets.")
+@click.option("--format", type=click.Choice(["text", "json", "sarif"]), default="text", help="Output format for scan results.")
+@click.option("--verbose", is_flag=True, help="Show ignored paths and scan summary.")
+@click.option("--audit", is_flag=True, help="Include suppression and ignore audit data.")
+def scan(path, format, verbose, audit):
+    """Scan codebases, configuration files, and environment files for exposed secrets."""
+    if format == "text":
+        safe_echo("🛡️ ShieldEnv: Scanning repository files...")
+    
+    try:
+        result = scan_path(path, verbose=verbose or audit)
+    except (RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    violations = [finding.__dict__ for finding in result.violations]
+
+    if result.errors:
+        for error in result.errors:
+            safe_echo(f"❌ {error}", err=True)
+        raise click.exceptions.Exit(2)
+    
+    if format == "sarif":
+        safe_echo(json.dumps(_to_sarif(result), indent=2))
+        if violations or result.errors:
+            raise click.exceptions.Exit(1 if violations else 2)
+        return
+
+    if format == "json":
+        payload = violations
+        if audit or verbose:
+            payload = {
+                "findings": violations,
+                "suppressed": result.suppressed,
+                "ignored": result.ignored,
+                "files_scanned": result.files_scanned,
+            }
+        safe_echo(json.dumps(payload, indent=2))
+        if violations:
+            raise click.exceptions.Exit(1)
+        return
+
+    if not violations:
+        safe_echo("✅ All clear! No leaked secrets or API keys found.")
+        if audit or verbose:
+            safe_echo(f"Scanned {result.files_scanned} files.")
+            safe_echo(f"Suppressed findings: {len(result.suppressed)}")
+            safe_echo(f"Ignored paths: {len(result.ignored)}")
+        return
+
+    safe_echo(f"\n❌ SECURITY ALERT: Found {len(violations)} potential secret leaks!\n")
+    
+    for v in violations:
+        safe_echo(f"  • Type: {v['type']}")
+        safe_echo(f"    File: {v['file']} (Line {v['line']})")
+        safe_echo(f"    Confidence: {v['confidence']}")
+        safe_echo(f"    Data: {v['snippet']}")
+        safe_echo("-" * 50)
+
+    if audit or verbose:
+        safe_echo(f"\nSuppressed findings: {len(result.suppressed)}")
+        safe_echo(f"Ignored paths: {len(result.ignored)}")
+        safe_echo(f"Files scanned: {result.files_scanned}")
+        
+    safe_echo("\n🚫 Commit/Build BLOCKED. Remove secrets, use environment variables, or update .shieldignore.")
+    raise click.exceptions.Exit(1)
+
+
+def _to_sarif(result):
+    return {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "ShieldEnv",
+                    "informationUri": "https://github.com/ShieldHQ/shieldenv",
+                    "rules": [
+                        {"id": finding.type, "name": finding.type}
+                        for finding in result.violations
+                    ],
+                }
+            },
+            "results": [
+                {
+                    "ruleId": finding.type,
+                    "level": "error" if finding.confidence == "high" else "warning",
+                    "message": {"text": f"Potential secret detected ({finding.confidence} confidence)."},
+                    "locations": [
+                        {
+                            "physicalLocation": {
+                                "artifactLocation": {
+                                    "uri": _sarif_uri(finding.file)
+                                },
+                                "region": {"startLine": finding.line}
+                            }
+                        }
+                    ]
+                }
+                for finding in result.violations
+            ]
+        }]
+    }
+
+
+def _sarif_uri(file_path: str) -> str:
+    try:
+        normalized = os.path.relpath(file_path)
+    except ValueError:
+        normalized = file_path
+    return Path(normalized).as_posix()
+
+
+@main.command()
+@click.option("--force", is_flag=True, help="Back up and replace an existing pre-commit hook.")
+def install(force):
+    """Automatically install ShieldEnv as a local Git pre-commit hook."""
+    git_dir = Path(".git")
+    if not git_dir.exists():
+        safe_echo("❌ Error: Not a git repository. Run 'git init' first.")
+        raise click.exceptions.Exit(1)
+
+    hook_path = git_dir / "hooks" / "pre-commit"
+    if hook_path.exists() and not force:
+        raise click.ClickException(
+            f"{hook_path} already exists; use --force to replace it with a backup."
+        )
+
+    if hook_path.exists():
+        backup_path = hook_path.with_name("pre-commit.shieldenv-backup")
+        hook_path.replace(backup_path)
+
+    if getattr(sys, "frozen", False):
+        command = shlex.quote(sys.executable)
+    else:
+        command = f"{shlex.quote(sys.executable)} -m shieldenv.cli"
+    hook_script = f"""#!/bin/sh
+# ShieldEnv automated pre-commit security hook
+exec {command} scan
+"""
+    try:
+        hook_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(hook_path, "w", encoding="utf-8") as f:
+            f.write(hook_script)
+        
+        # Make executable on Unix/Mac
+        if os.name != 'nt':
+            hook_path.chmod(0o755)
+            
+        safe_echo("✅ Successfully installed ShieldEnv git pre-commit hook!")
+    except OSError as e:
+        safe_echo(f"❌ Failed to install hook: {e}")
+        raise click.exceptions.Exit(1)
+
+if __name__ == "__main__":
+    main()

shieldenv-1.0.0/shieldenv/config.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+BUILTIN_IGNORES = {
+    "node_modules", "venv", ".venv", "dist", "build", ".next", 
+    "__pycache__", ".pytest_cache", ".ruff_cache", ".git", 
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml"
+}
+
+def load_shieldignore(root_dir: Path = Path(".")) -> set[str]:
+    ignore_set = set(BUILTIN_IGNORES)
+
+    def add_entries(ignore_file: Path) -> None:
+        if not ignore_file.exists():
+            return
+        try:
+            lines = ignore_file.read_text(encoding="utf-8").splitlines()
+        except OSError as exc:
+            raise RuntimeError(f"Unable to read ignore file: {ignore_file}") from exc
+        for line in lines:
+            cleaned = line.strip()
+            if cleaned and not cleaned.startswith("#"):
+                ignore_set.add(cleaned.strip("/"))
+
+    # 1. Check local project .shieldignore
+    add_entries(root_dir / ".shieldignore")
+
+    # 2. Check global user-level ignore (~/.shieldignore)
+    add_entries(Path.home() / ".shieldignore")
+
+    return ignore_set

shieldenv-1.0.0/shieldenv/patterns.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PatternRule:
+    name: str
+    pattern: re.Pattern[str]
+    confidence: str
+
+
+PATTERN_RULES = (
+    PatternRule("OpenAI API Key", re.compile(r"sk-[a-zA-Z0-9]{32,}", re.IGNORECASE), "high"),
+    PatternRule("Anthropic API Key", re.compile(r"sk-ant-[a-zA-Z0-9\-_]{20,}", re.IGNORECASE), "high"),
+    PatternRule("Google Gemini / AIza Key", re.compile(r"AIza[0-9A-Za-z\-_]{35}", re.IGNORECASE), "high"),
+    PatternRule("GitHub Personal Access Token", re.compile(r"gh[pousr]_[a-zA-Z0-9_]{20,}", re.IGNORECASE), "high"),
+    PatternRule("AWS access key", re.compile(r"AKIA[0-9A-Z]{16}"), "high"),
+    PatternRule("Azure Storage Key", re.compile(r"DefaultEndpointsProtocol=https?;AccountName=[^;]+;AccountKey=[^;]+", re.IGNORECASE), "high"),
+    PatternRule("Stripe Secret Key", re.compile(r"sk_(?:live|test)_[0-9a-zA-Z]{20,}", re.IGNORECASE), "high"),
+    PatternRule("Slack Webhook / Token", re.compile(r"xox[baprs]-[0-9a-zA-Z]{10,48}"), "high"),
+    PatternRule("Database Connection URL", re.compile(r"(postgres|mysql|mongodb(\+srv)?):\//[^\s]+:[^\s]+@[^\s]+", re.IGNORECASE), "high"),
+    PatternRule("JWT", re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b"), "medium"),
+    PatternRule("Generic Private Key", re.compile(r"-----BEGIN (RSA|EC|PRIVATE|OPENSSH) KEY-----"), "high"),
+    PatternRule("Generic Secret Assignment", re.compile(
+        r"""(?:"?(api_key|secret_key|password|passwd|auth_token|bearer)"?\s*(?:=|:)\s*['"][^'"]{8,200}['"])""",
+        re.IGNORECASE,
+    ), "medium"),
+)
+
+SECRET_PATTERNS = {rule.name: rule.pattern for rule in PATTERN_RULES}

shieldenv-1.0.0/shieldenv/scanner.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+from pathlib import Path
+
+from .config import load_shieldignore
+from .patterns import PATTERN_RULES
+
+SECRET_ASSIGNMENT = re.compile(
+    r"^\s*(?:(?:export\s+)?(?:const|let|var)\s+)?"
+    r"(?P<name>[A-Za-z_][\w.]*)"
+    r"(?:\s*:\s*[^=]+)?\s*=\s*(?P<value>.+)$"
+)
+
+@dataclass
+class Finding:
+    file: str
+    line: int
+    type: str
+    snippet: str
+    confidence: str = "medium"
+
+    @property
+    def rule(self) -> str:
+        return self.type
+
+@dataclass
+class ScanResult:
+    violations: list[Finding] = field(default_factory=list)
+    files_scanned: int = 0
+    errors: list[str] = field(default_factory=list)
+    suppressed: list[dict[str, str | int]] = field(default_factory=list)
+    ignored: list[str] = field(default_factory=list)
+
+    @property
+    def findings(self) -> list[Finding]:
+        return self.violations
+
+    @property
+    def has_secrets(self) -> bool:
+        return len(self.violations) > 0
+
+EXCLUDE_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".ico", ".pdf", ".lock", ".zip", ".tar", ".gz", 
+    ".pyc", ".woff", ".woff2", ".bin", ".md", ".markdown", ".txt"
+}
+
+def calculate_entropy(data: str) -> float:
+    """Calculates Shannon entropy to detect randomized strings/secrets."""
+    if not data:
+        return 0.0
+    counts = Counter(data)
+    return -sum((count / len(data)) * math.log2(count / len(data)) for count in counts.values())
+
+def redact(text: str, match: re.Match[str] | None = None) -> str:
+    return "[REDACTED]"
+
+
+def scan_file_details(file_path: Path) -> tuple[list[Finding], list[dict[str, str | int]]]:
+    violations = []
+    suppressed = []
+    file_str = str(file_path).lower()
+    
+    if ".test." in file_str or ".spec." in file_str or "tests" in file_path.parts:
+        return violations, suppressed
+
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+            for line_no, line in enumerate(f, 1):
+                stripped = line.strip()
+                lower_line = stripped.lower()
+                suppressed_line = "shieldenv: ignore" in lower_line
+
+                if stripped.startswith(("#", "//")) or len(stripped) < 8:
+                    continue
+                
+                if any(term in lower_line for term in ["example", "placeholder", "dummy", "changeme", "your_", "secret123"]):
+                    continue
+
+                if "{{" in stripped or "}}" in stripped or "{%" in stripped or "%}" in stripped:
+                    continue
+
+                if "${" in stripped or "$(" in stripped:
+                    continue
+
+                if (
+                    any(safe_call in lower_line for safe_call in ["os.getenv", "settings.", "process.env", "config."])
+                    and "=" in stripped
+                    and not any(quote in stripped for quote in ["'", '"', "`"])
+                ):
+                    continue
+
+                if file_path.suffix in {".tsx", ".jsx", ".html", ".vue"}:
+                    if any(tag in lower_line for tag in ["<h1", "<h3", "<span", "<div", "routerlink", "tabindex", "datakey"]):
+                        continue
+                    if "password" in lower_line and not "=" in stripped:
+                        continue
+
+                if len(stripped) > 300:
+                    continue
+
+                matched = False
+                for rule in PATTERN_RULES:
+                    match = rule.pattern.search(line)
+                    if match:
+                        finding = Finding(
+                            file=str(file_path),
+                            line=line_no,
+                            type=rule.name,
+                            snippet=redact(stripped, match),
+                            confidence=rule.confidence,
+                        )
+                        if suppressed_line:
+                            suppressed.append({"file": str(file_path), "line": line_no, "reason": "inline suppression"})
+                        else:
+                            violations.append(finding)
+                        matched = True
+                        break
+                
+                if matched:
+                    continue
+
+                assignment = SECRET_ASSIGNMENT.match(stripped)
+                if assignment and any(
+                    word in assignment.group("name").lower()
+                    for word in ["token", "secret", "password", "api_key", "secret_key"]
+                ):
+                    value = assignment.group("value").strip()
+                    literal = re.fullmatch(r"""(['"])(.*?)\1""", value)
+                    if literal:
+                        val = literal.group(2)
+                        if len(val) > 20 and calculate_entropy(val) > 4.5:
+                            finding = Finding(
+                                file=str(file_path),
+                                line=line_no,
+                                type="High-Entropy Secret / Custom Token",
+                                snippet=redact(stripped),
+                                confidence="medium",
+                            )
+                            if suppressed_line:
+                                suppressed.append({"file": str(file_path), "line": line_no, "reason": "inline suppression"})
+                            else:
+                                violations.append(finding)
+    except (OSError, UnicodeError) as exc:
+        raise RuntimeError(f"Unable to scan file: {file_path}") from exc
+    return violations, suppressed
+
+
+def scan_file(file_path: Path) -> list[Finding]:
+    return scan_file_details(file_path)[0]
+
+def scan_path(root_dir=".", verbose=False):
+    root_path = Path(root_dir).resolve()
+    if not root_path.exists():
+        raise ValueError(f"Scan path does not exist: {root_path}")
+    if not root_path.is_dir():
+        raise ValueError(f"Scan path is not a directory: {root_path}")
+
+    ignore_list = load_shieldignore(root_path)
+    all_violations = []
+    errors = []
+    suppressed = []
+    ignored = []
+    files_count = 0
+
+    for path in root_path.rglob("*"):
+        rel_path = path.relative_to(root_path)
+        rel_str = rel_path.as_posix()
+        if any(_matches_ignore(rel_str, path.is_dir(), ignore) for ignore in ignore_list):
+            if verbose:
+                ignored.append(rel_str)
+            continue
+
+        if path.is_dir():
+            continue
+        if path.suffix.lower() in EXCLUDE_EXTENSIONS:
+            continue
+            
+        files_count += 1
+        try:
+            findings, audits = scan_file_details(path)
+            all_violations.extend(findings)
+            suppressed.extend(audits)
+        except RuntimeError as exc:
+            errors.append(str(exc))
+
+    return ScanResult(
+        violations=all_violations,
+        files_scanned=files_count,
+        errors=errors,
+        suppressed=suppressed,
+        ignored=ignored,
+    )
+
+
+def _matches_ignore(relative_path: str, is_directory: bool, pattern: str) -> bool:
+    normalized = pattern.strip().strip("/")
+    if not normalized:
+        return False
+    if "/" not in normalized and "\\" not in normalized:
+        return normalized in Path(relative_path).parts
+    if fnmatch(relative_path, normalized) or fnmatch(relative_path, f"{normalized}/**"):
+        return True
+    return is_directory and relative_path == normalized
+
+def scan_directory(root_dir="."):
+    return [v.__dict__ for v in scan_path(root_dir).violations]

shieldenv-1.0.0/shieldenv.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: shieldenv
+Version: 1.0.0
+Summary: Local-first secret and AI API key leak prevention CLI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Dynamic: license-file
+
+# ShieldEnv 🛡️
+Local-First Secret Scanning & Pre-Commit Guardraill
+
+ShieldEnv is an open-source security engine designed to eliminate accidental credential leaks, API key exposures, and compliance violations before code ever hits version control.
+
+### Why Local-First?
+Unlike cloud-based PR scanners that analyze your code after it leaves your machine, ShieldEnv runs entirely local-first. Zero code, environment variables, or tokens ever leave your local environment.
+
+## Features
+
+- Regex detection for OpenAI, Anthropic, Google, AWS, GitHub, Slack, database URLs, private keys, and generic secret assignments.
+- Provider rules include confidence levels (`high` or `medium`).
+- Entropy-based detection for literal custom tokens.
+- Built-in filtering for placeholders, environment substitutions, templates, and common generated/UI syntax.
+- Project and user-level `.shieldignore` support.
+- Text, JSON, and SARIF output for local and CI use.
+- Optional Git pre-commit hook installation.
+- Redacted findings that never print complete secret values.
+
+## Installation
+
+Create an environment and install ShieldEnv:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+On Windows PowerShell, activate with:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+shieldenv scan
+```
+
+Scan another path or emit machine-readable JSON:
+
+```bash
+shieldenv scan --path ./src --format json
+```
+
+Generate GitHub Code Scanning-compatible SARIF:
+
+```bash
+shieldenv scan --path . --format sarif > shieldenv.sarif
+```
+
+Use verbose mode to inspect scan coverage and ignored paths:
+
+```bash
+shieldenv scan --verbose
+shieldenv scan --audit --format json
+```
+
+Exit codes:
+
+- `0`: no findings and no scan errors.
+- `1`: one or more potential secrets were found.
+- `2`: one or more files could not be read.
+
+Install a Git pre-commit hook from the repository root:
+
+```bash
+shieldenv install
+```
+
+ShieldEnv will not overwrite an existing hook unless explicitly requested:
+
+```bash
+shieldenv install --force
+```
+
+With `--force`, an existing hook is saved as `.git/hooks/pre-commit.shieldenv-backup`.
+
+## Ignore rules
+
+ShieldEnv skips common dependency, build, cache, and lock-file paths by default. Add a project-level `.shieldignore` at the root being scanned, or a global `~/.shieldignore`, with one rule per line:
+
+```text
+# Exact directory name anywhere in the tree
+generated
+
+# Relative path or glob
+backend/app/api/
+frontend/generated/**
+```
+
+Blank lines and lines beginning with `#` are ignored. Use ignore rules carefully: excluded files are not scanned. `--verbose` lists ignored paths so exclusions can be reviewed.
+
+To suppress a deliberate test value on one line, use the explicit marker:
+
+```python
+TEST_TOKEN = "not-a-credential"  # shieldenv: ignore
+```
+
+Suppressions are recorded in audit JSON output. Keep suppressions rare and review them during code review.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+```
+
+ShieldEnv is heuristic-based and should complement, not replace, secret rotation and incident-response procedures. Review findings and maintain project-specific ignore rules for generated code.
+
+ShieldEnv cannot guarantee detection of every secret format. It combines provider signatures, structured assignment patterns, and entropy heuristics, so unusual encodings may be missed and generated or identifier-like values may still require review. The scanner intentionally reports findings without exposing full values. Run it in CI on Linux, Windows, and macOS; the included workflow tests Python 3.9 through 3.13.
+
+Provider signatures are high-confidence indicators; generic assignments and entropy findings are medium-confidence heuristics. A clean scan means no supported rule matched, not that the repository is guaranteed secret-free. Rotate any credential that may have been exposed, and use code review and repository access controls alongside ShieldEnv.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

shieldenv-1.0.0/shieldenv.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+shieldenv/__init__.py
+shieldenv/cli.py
+shieldenv/config.py
+shieldenv/patterns.py
+shieldenv/scanner.py
+shieldenv.egg-info/PKG-INFO
+shieldenv.egg-info/SOURCES.txt
+shieldenv.egg-info/dependency_links.txt
+shieldenv.egg-info/entry_points.txt
+shieldenv.egg-info/requires.txt
+shieldenv.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_scanner.py

shieldenv-1.0.0/shieldenv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shieldenv-1.0.0/shieldenv.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shieldenv = shieldenv.cli:main

shieldenv-1.0.0/shieldenv.egg-info/requires.txt

@@ -0,0 +1,5 @@
+click>=8.0.0
+
+[dev]
+pytest>=8.0.0
+ruff>=0.6.0

shieldenv-1.0.0/shieldenv.egg-info/top_level.txt

@@ -0,0 +1 @@
+shieldenv

shieldenv-1.0.0/tests/test_cli.py

@@ -0,0 +1,59 @@
+import json
+
+from click.testing import CliRunner
+
+from shieldenv.cli import main
+
+
+def test_sarif_output_has_standard_shape(tmp_path) -> None:
+    (tmp_path / "config.env").write_text(
+        "AWS_KEY=AKIA" + "1234567890ABCDEF\n",
+        encoding="utf-8",
+    )
+
+    result = CliRunner().invoke(main, ["scan", "--path", str(tmp_path), "--format", "sarif"])
+
+    assert result.exit_code == 1
+    output = result.stdout
+    payload = json.loads(output)
+    assert payload["version"] == "2.1.0"
+    assert payload["runs"][0]["results"][0]["ruleId"] == "AWS access key"
+    assert "AKIA" not in output
+
+
+def test_audit_json_reports_suppression_without_secret(tmp_path) -> None:
+    fake_secret = "ghp_" + "abcdefghijklmnopqrstuvwxyz123456"
+    (tmp_path / "config.py").write_text(
+        f'TOKEN = "{fake_secret}"  # shieldenv: ignore\n',
+        encoding="utf-8",
+    )
+
+    result = CliRunner().invoke(
+        main,
+        ["scan", "--path", str(tmp_path), "--format", "json", "--audit"],
+    )
+
+    assert result.exit_code == 0
+    output = result.stdout
+    payload = json.loads(output)
+    assert payload["findings"] == []
+    assert len(payload["suppressed"]) == 1
+    assert fake_secret not in output
+
+
+def test_sarif_output_falls_back_when_relpath_fails(tmp_path, monkeypatch) -> None:
+    (tmp_path / "config.env").write_text(
+        "AWS_KEY=AKIA" + "1234567890ABCDEF\n",
+        encoding="utf-8",
+    )
+
+    def _raise_value_error(*_args, **_kwargs):
+        raise ValueError("path is on mount 'C:', start on mount 'D:'")
+
+    monkeypatch.setattr("shieldenv.cli.os.path.relpath", _raise_value_error)
+    result = CliRunner().invoke(main, ["scan", "--path", str(tmp_path), "--format", "sarif"])
+
+    assert result.exit_code == 1
+    payload = json.loads(result.stdout)
+    uri = payload["runs"][0]["results"][0]["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
+    assert uri.endswith("/config.env")

shieldenv-1.0.0/tests/test_scanner.py

@@ -0,0 +1,186 @@
+import time
+from pathlib import Path
+
+from shieldenv.scanner import scan_path
+
+
+def fake_token(prefix: str, suffix: str) -> str:
+    return prefix + suffix
+
+
+def test_detects_aws_key(tmp_path: Path) -> None:
+    target = tmp_path / "settings.py"
+    target.write_text(
+        f'AWS_KEY = "{fake_token("AKIA", "1234567890ABCDEF")}"\n',
+        encoding="utf-8",
+    )
+
+    result = scan_path(tmp_path)
+
+    assert result.has_secrets
+    assert result.findings[0].rule == "AWS access key"
+
+
+def test_respects_shieldignore(tmp_path: Path) -> None:
+    ignored = tmp_path / "secrets.env"
+    ignored.write_text(
+        f'TOKEN="{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz")}"\n',
+        encoding="utf-8",
+    )
+    (tmp_path / ".shieldignore").write_text("secrets.env\n", encoding="utf-8")
+
+    result = scan_path(tmp_path)
+
+    assert not result.has_secrets
+
+
+def test_scans_only_text_files(tmp_path: Path) -> None:
+    (tmp_path / "image.bin").write_bytes(b"\xff\xfe\x00")
+
+    result = scan_path(tmp_path)
+
+    assert result.files_scanned == 0
+
+
+def test_entropy_detection_requires_secret_named_literal_assignment(tmp_path: Path) -> None:
+    target = tmp_path / "source.ts"
+    target.write_text(
+        'const token = "x9Z!mQ8#vL2$pK5_wR7%tY4&hN1-jB3*fC6"\n'
+        'const loginPassword = getPassword(token)\n'
+        'const value = `reset-password?token=${token}`\n'
+        'const passwordInput = React.forwardRef<HTMLInputElement, Props>(fn)\n',
+        encoding="utf-8",
+    )
+
+    result = scan_path(tmp_path)
+
+    assert len(result.findings) == 1
+    assert result.findings[0].line == 1
+
+
+def test_shieldignore_is_loaded_from_scan_root(tmp_path: Path) -> None:
+    ignored_dir = tmp_path / "backend" / "app" / "api"
+    ignored_dir.mkdir(parents=True)
+    (ignored_dir / "secrets.py").write_text(
+        f'TOKEN = "{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}"\n',
+        encoding="utf-8",
+    )
+    (tmp_path / ".shieldignore").write_text("backend/app/api/\n", encoding="utf-8")
+
+    result = scan_path(tmp_path)
+
+    assert not result.has_secrets
+
+
+def test_scans_json_and_typed_assignments(tmp_path: Path) -> None:
+    (tmp_path / "config.json").write_text(
+        f'{{"password": "{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}"}}\n',
+        encoding="utf-8",
+    )
+    (tmp_path / "config.py").write_text(
+        f'password: str = "{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}"\n',
+        encoding="utf-8",
+    )
+
+    result = scan_path(tmp_path)
+
+    assert len(result.findings) == 2
+
+
+def test_ignore_names_match_path_segments_not_substrings(tmp_path: Path) -> None:
+    (tmp_path / "apiary.py").write_text(
+        f'TOKEN = "{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}"\n',
+        encoding="utf-8",
+    )
+    (tmp_path / "api").mkdir()
+    (tmp_path / "api" / "safe.py").write_text("print('safe')\n", encoding="utf-8")
+    (tmp_path / ".shieldignore").write_text("api\n", encoding="utf-8")
+
+    result = scan_path(tmp_path)
+
+    assert len(result.findings) == 1
+    assert result.findings[0].file.endswith("apiary.py")
+
+
+def test_provider_findings_are_redacted_and_have_confidence(tmp_path: Path) -> None:
+    (tmp_path / "providers.env").write_text(
+        f'OPENAI_KEY={fake_token("sk-", "abcdefghijklmnopqrstuvwxyz1234567890")}\n'
+        f'AWS_KEY={fake_token("AKIA", "1234567890ABCDEF")}\n'
+        f'STRIPE_KEY={fake_token("sk_live_", "12345678901234567890")}\n',
+        encoding="utf-8",
+    )
+
+    result = scan_path(tmp_path)
+
+    assert len(result.findings) == 3
+    assert all(finding.snippet == "[REDACTED]" for finding in result.findings)
+    assert all(finding.confidence == "high" for finding in result.findings)
+
+
+def test_inline_suppression_is_recorded(tmp_path: Path) -> None:
+    (tmp_path / "source.py").write_text(
+        f'TOKEN = "{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}"  # shieldenv: ignore\n',
+        encoding="utf-8",
+    )
+
+    result = scan_path(tmp_path)
+
+    assert not result.findings
+    assert result.suppressed[0]["line"] == 1
+
+
+def test_structured_config_extensions_are_scanned(tmp_path: Path) -> None:
+    (tmp_path / "config.yaml").write_text(
+        f'password: {fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}\n',
+        encoding="utf-8",
+    )
+    (tmp_path / "config.toml").write_text(
+        f'token = "{fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}"\n',
+        encoding="utf-8",
+    )
+
+    result = scan_path(tmp_path)
+
+    assert len(result.findings) == 2
+
+
+def test_large_repository_scan_completes(tmp_path: Path) -> None:
+    for index in range(250):
+        (tmp_path / f"module_{index}.py").write_text(
+            "def health_check():\n    return True\n",
+            encoding="utf-8",
+        )
+
+    started = time.perf_counter()
+    result = scan_path(tmp_path)
+    elapsed = time.perf_counter() - started
+
+    assert result.files_scanned == 250
+    assert not result.findings
+    assert elapsed < 2.0
+
+
+def test_provider_fixture_detects_and_redacts_all_supported_rules(tmp_path: Path) -> None:
+    target = tmp_path / "providers.env"
+    target.write_text(
+        f'OPENAI={fake_token("sk-", "abcdefghijklmnopqrstuvwxyz1234567890")}\n'
+        f'ANTHROPIC={fake_token("sk-ant-", "abcdefghijklmnopqrstuvwxyz")}\n'
+        f'GOOGLE={fake_token("AIza", "12345678901234567890123456789012345")}\n'
+        f'AWS={fake_token("AKIA", "1234567890ABCDEF")}\n'
+        f'GITHUB={fake_token("ghp_", "abcdefghijklmnopqrstuvwxyz123456")}\n'
+        f'SLACK={fake_token("xoxb-", "1234567890-abcdefghijklmnop")}\n'
+        f'STRIPE={fake_token("sk_live_", "12345678901234567890")}\n',
+        encoding="utf-8",
+    )
+    findings = scan_file_for_fixture(target)
+
+    assert len(findings) == 7
+    assert {finding.confidence for finding in findings} == {"high"}
+    assert all(finding.snippet == "[REDACTED]" for finding in findings)
+
+
+def scan_file_for_fixture(path: Path):
+    from shieldenv.scanner import scan_file_details
+
+    findings, _ = scan_file_details(path)
+    return findings