datacloak 0.1.0__py3-none-any.whl

datacloak/__init__.py

@@ -0,0 +1,177 @@
+"""
+DataCloak — Privacy Protection Library
+=======================================
+
+A production-ready Python library for detecting and masking Personally
+Identifiable Information (PII) in text, logs, files, and application data.
+
+Quick start::
+
+    from datacloak import mask, scan
+
+    text = \"\"\"
+    Aadhaar: 2345 6789 0123
+    PAN: ABCDE1234F
+    Email: alice@example.com
+    Phone: 9876543210
+    \"\"\"
+
+    print(mask(text))          # partial masking (default)
+    print(mask(text, mode="full"))
+    print(mask(text, mode="hash"))
+
+    findings = scan(text)
+    # {"aadhaar": ["2345 6789 0123"], "pan": ["ABCDE1234F"], ...}
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .detectors import (
+    DEFAULT_DETECTORS,
+    AadhaarDetector,
+    BaseDetector,
+    CreditCardDetector,
+    Detection,
+    EmailDetector,
+    IFSCDetector,
+    IPAddressDetector,
+    MobileDetector,
+    PANDetector,
+    UPIDetector,
+)
+from .file_scanner import FileScanResult, scan_file
+from .masker import MaskMode, mask_text
+from .reporter import Report, generate_report_from_file, generate_report_from_text
+from .scanner import ScanResult, scan_summary, scan_text
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__version__ = "0.1.0"
+__author__ = "DataCloak Contributors"
+__license__ = "MIT"
+
+# Set up a NullHandler so the library is silent unless the caller configures logging.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+# ---------------------------------------------------------------------------
+# Convenience aliases (the primary public surface)
+# ---------------------------------------------------------------------------
+
+
+def mask(
+    text: str,
+    mode: MaskMode = "partial",
+    detectors: list[BaseDetector] | None = None,
+) -> str:
+    """
+    Detect and mask all PII in *text*.
+
+    Parameters
+    ----------
+    text:
+        Input string containing potential PII.
+    mode:
+        ``"partial"`` (default) — keep trailing characters visible.
+        ``"full"`` — replace with descriptive tags like ``[EMAIL_REDACTED]``.
+        ``"hash"`` — replace with SHA-256 digest.
+    detectors:
+        Optional list of :class:`~datacloak.detectors.BaseDetector` instances.
+        Defaults to all built-in detectors.
+
+    Returns
+    -------
+    str
+        The masked string.
+
+    Example::
+
+        >>> from datacloak import mask
+        >>> mask("Call me at 9876543210")
+        'Call me at ******3210'
+    """
+    return mask_text(text, mode=mode, detectors=detectors)
+
+
+def scan(
+    text: str,
+    detectors: list[BaseDetector] | None = None,
+) -> ScanResult:
+    """
+    Scan *text* for PII without modifying it.
+
+    Parameters
+    ----------
+    text:
+        Input string to scan.
+    detectors:
+        Optional custom detectors.
+
+    Returns
+    -------
+    dict
+        Mapping of PII type name → list of detected values.
+
+    Example::
+
+        >>> from datacloak import scan
+        >>> scan("Email me at bob@example.com")
+        {'email': ['bob@example.com']}
+    """
+    return scan_text(text, detectors=detectors)
+
+
+def report(
+    text: str,
+    source_label: str = "<inline text>",
+    detectors: list[BaseDetector] | None = None,
+) -> Report:
+    """
+    Generate a structured :class:`~datacloak.reporter.Report` from *text*.
+
+    Example::
+
+        >>> from datacloak import report
+        >>> r = report("john@example.com called 9876543210")
+        >>> print(r.to_json())
+    """
+    return generate_report_from_text(text, source_label=source_label, detectors=detectors)
+
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core API
+    "mask",
+    "scan",
+    "report",
+    # File operations
+    "scan_file",
+    # Lower-level API
+    "mask_text",
+    "scan_text",
+    "scan_summary",
+    "generate_report_from_text",
+    "generate_report_from_file",
+    # Detectors
+    "BaseDetector",
+    "Detection",
+    "DEFAULT_DETECTORS",
+    "AadhaarDetector",
+    "PANDetector",
+    "MobileDetector",
+    "EmailDetector",
+    "UPIDetector",
+    "CreditCardDetector",
+    "IFSCDetector",
+    "IPAddressDetector",
+    # Types
+    "MaskMode",
+    "ScanResult",
+    "FileScanResult",
+    "Report",
+]

datacloak/cli.py

@@ -0,0 +1,222 @@
+"""
+DataCloak Command-Line Interface.
+
+Usage::
+
+    datacloak scan file.txt
+    datacloak mask file.txt
+    datacloak mask file.txt --mode full --output masked.txt
+    datacloak report file.txt
+    datacloak report file.txt --output report.json
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+import datacloak
+from datacloak.file_scanner import mask_file, scan_file
+from datacloak.masker import MaskMode
+from datacloak.reporter import generate_report_from_file
+
+
+# ---------------------------------------------------------------------------
+# CLI root
+# ---------------------------------------------------------------------------
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(datacloak.__version__, "-V", "--version")
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    default=False,
+    help="Enable verbose logging output.",
+)
+def cli(verbose: bool) -> None:
+    """
+    \b
+    DataCloak — Privacy Protection CLI
+    ===================================
+    Detect and mask PII in text files.
+    """
+    if verbose:
+        import logging
+
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(levelname)s %(name)s: %(message)s",
+        )
+
+
+# ---------------------------------------------------------------------------
+# scan command
+# ---------------------------------------------------------------------------
+
+
+@cli.command("scan")
+@click.argument("file", type=click.Path(exists=True, readable=True, path_type=Path))
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "table"], case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format.",
+)
+def scan_cmd(file: Path, output_format: str) -> None:
+    """
+    Scan FILE for PII and display findings.
+
+    \b
+    Examples:
+      datacloak scan customer_data.txt
+      datacloak scan --format json logs.txt
+    """
+    result = scan_file(file)
+
+    if result.error:
+        click.secho(f"Error: {result.error}", fg="red", err=True)
+        sys.exit(1)
+
+    if not result.findings:
+        click.secho("✓ No PII detected.", fg="green")
+        return
+
+    if output_format == "json":
+        click.echo(json.dumps(result.by_type, indent=2, ensure_ascii=False))
+        return
+
+    # Table output
+    click.secho(f"\n📄 File: {file}", bold=True)
+    click.secho(f"{'PII Type':<18} {'Value':<40} {'Line':>6}", fg="cyan")
+    click.secho("─" * 66, fg="cyan")
+    for finding in result.findings:
+        line_str = str(finding.line_number) if finding.line_number else "—"
+        click.echo(f"{finding.pii_type:<18} {finding.value:<40} {line_str:>6}")
+
+    click.secho("─" * 66, fg="cyan")
+    click.secho(f"\nSummary: {result.summary}", fg="yellow")
+    risk_colours = {"NONE": "green", "LOW": "yellow", "MEDIUM": "magenta", "HIGH": "red"}
+    from datacloak.reporter import _risk_level
+
+    risk = _risk_level(len(result.findings))
+    colour = risk_colours.get(risk, "white")
+    click.secho(f"Risk level: {risk}", fg=colour, bold=True)
+
+
+# ---------------------------------------------------------------------------
+# mask command
+# ---------------------------------------------------------------------------
+
+
+@cli.command("mask")
+@click.argument("file", type=click.Path(exists=True, readable=True, path_type=Path))
+@click.option(
+    "-m",
+    "--mode",
+    type=click.Choice(["partial", "full", "hash"], case_sensitive=False),
+    default="partial",
+    show_default=True,
+    help="Masking mode.",
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_path",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Output file path (default: <file>.masked<ext>).",
+)
+@click.option(
+    "--stdout",
+    is_flag=True,
+    default=False,
+    help="Print masked output to stdout instead of writing a file.",
+)
+def mask_cmd(file: Path, mode: str, output_path: Path | None, stdout: bool) -> None:
+    """
+    Mask PII in FILE.
+
+    \b
+    Masking modes:
+      partial  Keep last characters visible (default)
+      full     Replace with descriptive tags, e.g. [EMAIL_REDACTED]
+      hash     Replace with SHA-256 digest
+
+    \b
+    Examples:
+      datacloak mask logs.txt
+      datacloak mask logs.txt --mode full --output clean_logs.txt
+      datacloak mask logs.txt --stdout | less
+    """
+    if stdout:
+        content = file.read_text(encoding="utf-8", errors="replace")
+        from datacloak.masker import mask_text
+
+        click.echo(mask_text(content, mode=mode))  # type: ignore[arg-type]
+        return
+
+    dest = mask_file(file, output_path=output_path, mode=mode)  # type: ignore[arg-type]
+    click.secho(f"✓ Masked file written to: {dest}", fg="green")
+
+
+# ---------------------------------------------------------------------------
+# report command
+# ---------------------------------------------------------------------------
+
+
+@cli.command("report")
+@click.argument("file", type=click.Path(exists=True, readable=True, path_type=Path))
+@click.option(
+    "-o",
+    "--output",
+    "output_path",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Save report as JSON to this path.",
+)
+@click.option(
+    "--pretty",
+    is_flag=True,
+    default=True,
+    help="Pretty-print JSON output (default: True).",
+)
+def report_cmd(file: Path, output_path: Path | None, pretty: bool) -> None:
+    """
+    Generate a PII scan report for FILE.
+
+    \b
+    Examples:
+      datacloak report data.txt
+      datacloak report data.csv --output report.json
+    """
+    rep = generate_report_from_file(file)
+
+    json_str = rep.to_json(indent=2 if pretty else None)
+
+    if output_path:
+        rep.save(output_path)
+        click.secho(f"✓ Report saved to: {output_path}", fg="green")
+    else:
+        click.echo(json_str)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

datacloak/detectors/__init__.py

@@ -0,0 +1,40 @@
+"""
+DataCloak detector modules.
+
+All built-in detectors are exported from this package.
+"""
+
+from .aadhaar import AadhaarDetector
+from .base import BaseDetector, Detection
+from .credit_card import CreditCardDetector
+from .email import EmailDetector
+from .ifsc import IFSCDetector
+from .ip_address import IPAddressDetector
+from .mobile import MobileDetector
+from .pan import PANDetector
+from .upi import UPIDetector
+
+__all__ = [
+    "BaseDetector",
+    "Detection",
+    "AadhaarDetector",
+    "PANDetector",
+    "MobileDetector",
+    "EmailDetector",
+    "UPIDetector",
+    "CreditCardDetector",
+    "IFSCDetector",
+    "IPAddressDetector",
+]
+
+#: Registry of all built-in detectors (ordered by detection priority)
+DEFAULT_DETECTORS: list[BaseDetector] = [
+    AadhaarDetector(),
+    PANDetector(),
+    MobileDetector(),
+    EmailDetector(),
+    UPIDetector(),
+    CreditCardDetector(),
+    IFSCDetector(),
+    IPAddressDetector(),
+]

datacloak/detectors/aadhaar.py

@@ -0,0 +1,53 @@
+"""Detector for Indian Aadhaar numbers (12-digit UIDs)."""
+
+from __future__ import annotations
+
+import re
+
+from .base import BaseDetector, Detection
+
+
+class AadhaarDetector(BaseDetector):
+    """
+    Detects Indian Aadhaar numbers.
+
+    Supports formats:
+        - ``1234 5678 9012``   (space-separated groups of 4)
+        - ``1234-5678-9012``   (hyphen-separated)
+        - ``123456789012``     (no separator)
+
+    Validates that the number does not start with 0 or 1 (invalid Aadhaar prefix).
+    """
+
+    name = "aadhaar"
+    description = "Indian Aadhaar UID (12-digit unique identifier)"
+
+    # Matches 12-digit numbers in groups of 4, with optional space/hyphen separators.
+    _pattern: re.Pattern = re.compile(
+        r"\b([2-9]\d{3}[\s\-]?\d{4}[\s\-]?\d{4})\b"
+    )
+
+    def _validate(self, value: str) -> bool:
+        digits = re.sub(r"[\s\-]", "", value)
+        if len(digits) != 12:
+            return False
+        # Aadhaar numbers cannot start with 0 or 1
+        if digits[0] in ("0", "1"):
+            return False
+        return True
+
+    def detect(self, text: str) -> list[Detection]:
+        results: list[Detection] = []
+        for match in self._pattern.finditer(text):
+            raw = match.group()
+            if self._validate(raw):
+                results.append(
+                    Detection(
+                        detector_name=self.name,
+                        value=raw,
+                        start=match.start(),
+                        end=match.end(),
+                        confidence=self._confidence(raw),
+                    )
+                )
+        return results

datacloak/detectors/base.py

@@ -0,0 +1,97 @@
+"""
+Base detector interface for DataCloak PII detection framework.
+All custom detectors must subclass BaseDetector.
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Iterator
+
+
+@dataclass(frozen=True)
+class Detection:
+    """Represents a single PII detection result."""
+
+    detector_name: str
+    value: str
+    start: int
+    end: int
+    confidence: float = 1.0
+    metadata: dict = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        return (
+            f"Detection(type={self.detector_name!r}, value={self.value!r}, "
+            f"span=({self.start}, {self.end}), confidence={self.confidence:.2f})"
+        )
+
+
+class BaseDetector(ABC):
+    """
+    Abstract base class for all PII detectors.
+
+    Subclass this and implement :meth:`detect` to create a pluggable detector.
+
+    Attributes:
+        name: Unique identifier for this detector (e.g. ``"email"``).
+        description: Human-readable description of what this detector finds.
+    """
+
+    name: str = ""
+    description: str = ""
+
+    # Optional compiled regex — subclasses may set this to get detect() for free.
+    _pattern: re.Pattern | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def detect(self, text: str) -> list[Detection]:
+        """
+        Detect all PII occurrences in *text*.
+
+        Returns a list of :class:`Detection` instances sorted by position.
+        The default implementation uses :attr:`_pattern` if set.
+        Subclasses may override for more complex logic.
+        """
+        if self._pattern is None:
+            raise NotImplementedError(
+                f"{self.__class__.__name__} must implement detect() "
+                "or set _pattern."
+            )
+        results: list[Detection] = []
+        for match in self._pattern.finditer(text):
+            if self._validate(match.group()):
+                results.append(
+                    Detection(
+                        detector_name=self.name,
+                        value=match.group(),
+                        start=match.start(),
+                        end=match.end(),
+                        confidence=self._confidence(match.group()),
+                    )
+                )
+        return results
+
+    def detect_iter(self, text: str) -> Iterator[Detection]:
+        """Lazy iterator variant of :meth:`detect`."""
+        yield from self.detect(text)
+
+    # ------------------------------------------------------------------
+    # Optional hooks
+    # ------------------------------------------------------------------
+
+    def _validate(self, value: str) -> bool:  # noqa: ARG002
+        """Secondary validation hook.  Return ``False`` to reject a regex match."""
+        return True
+
+    def _confidence(self, value: str) -> float:  # noqa: ARG002
+        """Return a confidence score in [0, 1] for the detected value."""
+        return 1.0
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} name={self.name!r}>"

datacloak/detectors/credit_card.py

@@ -0,0 +1,60 @@
+"""Detector for credit/debit card numbers with Luhn algorithm validation."""
+
+from __future__ import annotations
+
+import re
+
+from .base import BaseDetector, Detection
+
+
+def _luhn_check(number: str) -> bool:
+    """Return True if *number* (digits only) passes the Luhn algorithm."""
+    digits = [int(d) for d in reversed(number)]
+    total = 0
+    for i, digit in enumerate(digits):
+        if i % 2 == 1:
+            digit *= 2
+            if digit > 9:
+                digit -= 9
+        total += digit
+    return total % 10 == 0
+
+
+class CreditCardDetector(BaseDetector):
+    """
+    Detects credit and debit card numbers (13–19 digits).
+
+    Validates using the Luhn algorithm to eliminate false positives.
+
+    Supports formats:
+        - ``4111111111111111``           (no separator)
+        - ``4111 1111 1111 1111``        (space-separated)
+        - ``4111-1111-1111-1111``        (hyphen-separated)
+
+    Covers: Visa, Mastercard, Amex, RuPay, Discover, JCB, etc.
+    """
+
+    name = "credit_card"
+    description = "Credit/debit card number"
+
+    _pattern: re.Pattern = re.compile(
+        r"\b"
+        r"(\d{4}[\s\-]?\d{4}[\s\-]?\d{4}[\s\-]?\d{1,4}"  # 13-16 digit
+        r"(?:[\s\-]?\d{1,3})?)"                             # up to 19 digits
+        r"\b"
+    )
+
+    def _validate(self, value: str) -> bool:
+        digits = re.sub(r"[\s\-]", "", value)
+        if not (13 <= len(digits) <= 19):
+            return False
+        if not digits.isdigit():
+            return False
+        return _luhn_check(digits)
+
+    def _confidence(self, value: str) -> float:
+        # Luhn-validated numbers get high confidence
+        digits = re.sub(r"[\s\-]", "", value)
+        if _luhn_check(digits):
+            return 0.95
+        return 0.5

datacloak/detectors/email.py

@@ -0,0 +1,50 @@
+"""Detector for email addresses."""
+
+from __future__ import annotations
+
+import re
+
+from .base import BaseDetector, Detection
+
+# Common disposable/invalid TLDs to optionally flag (not filtered by default)
+_MIN_TLD_LENGTH = 2
+
+
+class EmailDetector(BaseDetector):
+    """
+    Detects RFC-5321-compatible email addresses.
+
+    Examples:
+        - ``john.doe@example.com``
+        - ``user+tag@sub.domain.org``
+        - ``first.last@company.co.in``
+    """
+
+    name = "email"
+    description = "Email address"
+
+    # Permissive but practical email regex
+    _pattern: re.Pattern = re.compile(
+        r"\b"
+        r"([a-zA-Z0-9]"                         # local: must start with alnum
+        r"(?:[a-zA-Z0-9._%+\-]{0,62})"          # local: body
+        r"[a-zA-Z0-9])"                          # local: must end with alnum (or be 1 char)
+        r"@"
+        r"([a-zA-Z0-9]"                          # domain
+        r"(?:[a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?"  # domain labels
+        r"(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?)*"
+        r"\.[a-zA-Z]{2,})"                       # TLD
+        r"\b",
+        re.ASCII,
+    )
+
+    def _validate(self, value: str) -> bool:
+        if "@" not in value:
+            return False
+        local, _, domain = value.rpartition("@")
+        if not local or not domain:
+            return False
+        if ".." in local or ".." in domain:
+            return False
+        tld = domain.rsplit(".", 1)[-1]
+        return len(tld) >= _MIN_TLD_LENGTH