tabayyan 0.5.1__py3-none-any.whl

tabayyan/__init__.py

@@ -0,0 +1,46 @@
+"""Tabayyan (تبيّن) — Saudi-aware PII detection & redaction for LLM pipelines.
+
+Local-first. Zero telemetry. No network calls in the detection core.
+"""
+from __future__ import annotations
+
+from .engine import DetectionEngine
+from .entities import Category, Confidence, EntityType, Match
+from .middleware import AuditLog, AuditRecord, Guard, ProtectResult, is_in_kingdom
+from .redaction import RedactionItem, RedactionMode, RedactionResult, redact, restore
+
+__version__ = "0.5.1"
+__all__ = [
+    "DetectionEngine",
+    "Match",
+    "EntityType",
+    "Category",
+    "Confidence",
+    "RedactionMode",
+    "RedactionResult",
+    "RedactionItem",
+    "redact",
+    "restore",
+    "Guard",
+    "AuditLog",
+    "AuditRecord",
+    "ProtectResult",
+    "is_in_kingdom",
+    "scan",
+    "scan_and_redact",
+    "__version__",
+]
+
+
+def scan(text: str) -> list[Match]:
+    """Convenience one-shot detection using the default detector set."""
+    return DetectionEngine().scan(text)
+
+
+def scan_and_redact(
+    text: str,
+    mode: "RedactionMode | str" = RedactionMode.MASK,
+    **kwargs,
+) -> RedactionResult:
+    """Detect then redact in one call. kwargs pass through to redact()."""
+    return redact(text, DetectionEngine().scan(text), mode, **kwargs)

tabayyan/checksums.py

@@ -0,0 +1,82 @@
+"""Deterministic, offline checksum primitives.
+
+Pure functions only. Passing a checksum confirms a value is *structurally
+valid*, NOT that it was ever issued.
+"""
+from __future__ import annotations
+
+
+def luhn_is_valid(number: str) -> bool:
+    if not number.isdigit():
+        return False
+    total = 0
+    parity = len(number) % 2
+    for i, ch in enumerate(number):
+        d = int(ch)
+        if i % 2 == parity:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return total % 10 == 0
+
+
+def luhn_check_digit(number_without_check: str) -> int:
+    total = 0
+    parity = (len(number_without_check) + 1) % 2
+    for i, ch in enumerate(number_without_check):
+        d = int(ch)
+        if i % 2 == parity:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return (10 - (total % 10)) % 10
+
+
+def saudi_id_is_valid(value: str) -> bool:
+    if len(value) != 10 or not value.isdigit() or value[0] not in ("1", "2"):
+        return False
+    total = 0
+    for i in range(10):
+        d = int(value[i])
+        if i % 2 == 0:
+            d *= 2
+            total += d // 10 + d % 10
+        else:
+            total += d
+    return total % 10 == 0
+
+
+def saudi_id_check_digit(first_nine: str) -> int:
+    if len(first_nine) != 9 or not first_nine.isdigit():
+        raise ValueError("first_nine must be exactly 9 digits")
+    partial = 0
+    for i in range(9):
+        d = int(first_nine[i])
+        if i % 2 == 0:
+            d *= 2
+            partial += d // 10 + d % 10
+        else:
+            partial += d
+    return (10 - (partial % 10)) % 10
+
+
+def _iban_to_numeric(iban: str) -> str:
+    rearranged = iban[4:] + iban[:4]
+    out = []
+    for ch in rearranged:
+        out.append(ch if ch.isdigit() else str(ord(ch.upper()) - 55))
+    return "".join(out)
+
+
+def iban_mod97_is_valid(iban: str) -> bool:
+    iban = iban.replace(" ", "").upper()
+    if len(iban) < 5 or not iban[:2].isalpha() or not iban[2:4].isdigit():
+        return False
+    return int(_iban_to_numeric(iban)) % 97 == 1
+
+
+def iban_check_digits(country: str, bban: str) -> str:
+    trial = country.upper() + "00" + bban.upper()
+    return f"{98 - (int(_iban_to_numeric(trial)) % 97):02d}"

tabayyan/cli.py

@@ -0,0 +1,220 @@
+"""Command-line interface for Tabayyan. Stdlib only.
+
+Commands:
+  tabayyan scan    [paths...]  detect entities, print findings
+  tabayyan redact  [paths...]  detect + redact, print sanitised text
+
+Reads stdin when no path is given or path is '-'. Supports batch over
+files and directories. Exit code is non-zero when entities are found,
+so it slots into CI / pre-commit gates.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Iterable
+
+from . import __version__
+from .config import Config
+from .engine import DetectionEngine
+from .streaming import scan_file
+from .entities import Confidence, Match
+from .homoglyph import scan_text as _scan_domains
+from .redaction import RedactionMode, redact
+
+_CONFIDENCE_ORDER = {Confidence.LOW: 0, Confidence.MEDIUM: 1, Confidence.HIGH: 2}
+_TEXT_SUFFIXES = {".txt", ".md", ".log", ".json", ".csv", ".eml", ".text"}
+
+
+def _iter_inputs(paths: list[str]) -> Iterable[tuple[str, str]]:
+    """Yield (source_name, text). '-' or empty -> stdin."""
+    if not paths or paths == ["-"]:
+        yield ("<stdin>", sys.stdin.read())
+        return
+    for raw in paths:
+        if raw == "-":
+            yield ("<stdin>", sys.stdin.read())
+            continue
+        p = Path(raw)
+        if p.is_dir():
+            for child in sorted(p.rglob("*")):
+                if child.is_file() and child.suffix.lower() in _TEXT_SUFFIXES:
+                    yield (str(child), child.read_text(encoding="utf-8", errors="replace"))
+        elif p.is_file():
+            yield (str(p), p.read_text(encoding="utf-8", errors="replace"))
+        else:
+            print(f"tabayyan: cannot read '{raw}'", file=sys.stderr)
+
+
+def _engine_from_args(args) -> DetectionEngine:
+    cfg = getattr(args, "config", None)
+    return Config.from_file(cfg).build_engine() if cfg else DetectionEngine()
+
+
+def _filter_matches(matches: list[Match], args) -> list[Match]:
+    out = matches
+    if args.min_confidence:
+        floor = _CONFIDENCE_ORDER[Confidence(args.min_confidence)]
+        out = [m for m in out if _CONFIDENCE_ORDER[m.confidence] >= floor]
+    if args.only:
+        only = set(args.only)
+        out = [m for m in out if m.entity_type.value in only]
+    if args.exclude:
+        excl = set(args.exclude)
+        out = [m for m in out if m.entity_type.value not in excl]
+    return out
+
+
+def _cmd_scan(args) -> int:
+    engine = _engine_from_args(args)
+    found_any = False
+    report = []
+    if args.stream:
+        for raw in args.paths:
+            if raw in ("", "-"):
+                print("tabayyan: --stream requires file paths, not stdin", file=sys.stderr)
+                continue
+            matches = _filter_matches(list(scan_file(raw, engine)), args)
+            if matches:
+                found_any = True
+            if args.json:
+                report.append({"source": raw, "matches": [m.to_dict() for m in matches]})
+            else:
+                for m in matches:
+                    val = "" if args.no_values else f"  {m.value!r}"
+                    print(f"{raw}:{m.start}-{m.end}\t{m.entity_type.value}\t"
+                          f"{m.confidence.value}\t{m.category.value}{val}")
+        if args.json:
+            json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+            sys.stdout.write("\n")
+        return (1 if found_any else 0) if args.fail_on_find else 0
+    for name, text in _iter_inputs(args.paths):
+        matches = _filter_matches(engine.scan(text), args)
+        if matches:
+            found_any = True
+        if args.json:
+            report.append({"source": name, "matches": [m.to_dict() for m in matches]})
+        else:
+            for m in matches:
+                val = "" if args.no_values else f"  {m.value!r}"
+                print(f"{name}:{m.start}-{m.end}\t{m.entity_type.value}\t"
+                      f"{m.confidence.value}\t{m.category.value}{val}")
+    if args.json:
+        json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    return (1 if found_any else 0) if args.fail_on_find else 0
+
+
+def _cmd_redact(args) -> int:
+    engine = _engine_from_args(args)
+    mode = RedactionMode(args.mode)
+    found_any = False
+    inputs = list(_iter_inputs(args.paths))
+    multi = len(inputs) > 1
+    for name, text in inputs:
+        matches = _filter_matches(engine.scan(text), args)
+        if matches:
+            found_any = True
+        result = redact(
+            text, matches, mode,
+            salt=args.salt, hash_length=args.hash_length,
+            partial_keep_last=args.keep_last,
+        )
+        if args.json:
+            payload = result.to_dict()
+            payload["source"] = name
+            json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+            sys.stdout.write("\n")
+        else:
+            if multi:
+                print(f"===== {name} =====")
+            sys.stdout.write(result.text)
+            if not result.text.endswith("\n"):
+                sys.stdout.write("\n")
+            if result.vault:
+                print(f"# vault ({len(result.vault)} tokens) — store securely; "
+                      f"use --json to capture", file=sys.stderr)
+    return (1 if found_any else 0) if args.fail_on_find else 0
+
+
+def _load_watchlist(path: str | None) -> list[str]:
+    if not path:
+        return []
+    return [ln.strip() for ln in Path(path).read_text(encoding="utf-8").splitlines()
+            if ln.strip() and not ln.startswith("#")]
+
+
+def _cmd_domains(args) -> int:
+    watchlist = _load_watchlist(args.watchlist)
+    found_any = False
+    report = []
+    for name, text in _iter_inputs(args.paths):
+        findings = _scan_domains(text, watchlist,
+                                 typosquat_max_distance=args.max_distance)
+        if findings:
+            found_any = True
+        if args.json:
+            report.append({"source": name, "findings": [vars(f) for f in findings]})
+        else:
+            for f in findings:
+                tgt = f" -> {f.target}" if f.target else ""
+                print(f"{name}:{f.start}-{f.end}\t{f.domain}\t{f.reason}\t"
+                      f"{f.confidence}{tgt}\t{f.detail}")
+    if args.json:
+        json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    return (1 if found_any else 0) if args.fail_on_find else 0
+
+
+def _add_common_filters(p: argparse.ArgumentParser) -> None:
+    p.add_argument("paths", nargs="*", help="files/dirs, or '-' for stdin")
+    p.add_argument("--min-confidence", choices=["low", "medium", "high"],
+                   help="drop matches below this confidence")
+    p.add_argument("--only", nargs="+", metavar="TYPE", help="keep only these entity types")
+    p.add_argument("--exclude", nargs="+", metavar="TYPE", help="drop these entity types")
+    p.add_argument("--json", action="store_true", help="emit JSON")
+    p.add_argument("--fail-on-find", action="store_true",
+                   help="exit 1 if any entity is found (for CI / pre-commit)")
+    p.add_argument("--config", help="JSON config: disable/add detectors, thresholds")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tabayyan", description=__doc__.splitlines()[0])
+    parser.add_argument("--version", action="version", version=f"tabayyan {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    ps = sub.add_parser("scan", help="detect entities")
+    _add_common_filters(ps)
+    ps.add_argument("--no-values", action="store_true", help="hide raw values in output")
+    ps.add_argument("--stream", action="store_true",
+                    help="scan large files incrementally (file paths only)")
+    ps.set_defaults(func=_cmd_scan)
+
+    pr = sub.add_parser("redact", help="detect and redact")
+    _add_common_filters(pr)
+    pr.add_argument("--mode", choices=[m.value for m in RedactionMode], default="mask")
+    pr.add_argument("--salt", default="", help="salt for hash mode")
+    pr.add_argument("--hash-length", type=int, default=12, help="hash token length")
+    pr.add_argument("--keep-last", type=int, default=4, help="kept chars in partial mode")
+    pr.set_defaults(func=_cmd_redact)
+    pd = sub.add_parser("domains", help="detect lookalike / homoglyph domains")
+    pd.add_argument("paths", nargs="*", help="files/dirs, or '-' for stdin")
+    pd.add_argument("--watchlist", help="file of legitimate domains, one per line")
+    pd.add_argument("--max-distance", type=int, default=1,
+                    help="max edit distance for typosquat flag")
+    pd.add_argument("--json", action="store_true", help="emit JSON")
+    pd.add_argument("--fail-on-find", action="store_true",
+                    help="exit 1 if any suspicious domain is found")
+    pd.set_defaults(func=_cmd_domains)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tabayyan/config.py

@@ -0,0 +1,92 @@
+"""Configuration: customise detection without editing code.
+
+Load a JSON config to enable/disable detectors, add custom regex
+detectors, extend the confusable map, and tune thresholds. JSON is used
+(not TOML) to keep zero runtime dependencies on Python 3.9.
+
+Schema (all keys optional):
+{
+  "disable": ["saudi_cr", "arabic_name"],
+  "typosquat_max_distance": 2,
+  "confusables": {"ⅴ": "v"},
+  "custom_detectors": [
+    {"label": "employee_id", "pattern": "EMP-\\\\d{6}",
+     "category": "organisation", "confidence": "medium"}
+  ]
+}
+
+Custom-detector matches use entity_type CUSTOM; their configured label is
+preserved in the `detector` and `notes` fields and in the mask placeholder.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from .confusables import register_confusables
+from .detectors import DEFAULT_DETECTORS, Detector
+from .engine import DetectionEngine
+from .entities import Category, Confidence, EntityType, Match
+
+_CONF = {c.value: c for c in Confidence}
+_CAT = {c.value: c for c in Category}
+
+
+class CustomRegexDetector(Detector):
+    """A user-defined regex detector loaded from config."""
+
+    def __init__(self, label: str, pattern: str, category: Category,
+                 confidence: Confidence) -> None:
+        self.name = f"custom:{label}"
+        self.label = label
+        self._rx = re.compile(pattern)
+        self._category = category
+        self._confidence = confidence
+
+    def detect(self, text: str) -> Iterable[Match]:
+        for m in self._rx.finditer(text):
+            yield Match(
+                entity_type=EntityType.CUSTOM, category=self._category,
+                confidence=self._confidence, start=m.start(), end=m.end(),
+                value=m.group(0), detector=self.name, label=self.label,
+                notes=f"custom detector '{self.label}'",
+            )
+
+    def mask_label(self) -> str:
+        return f"[{self.label.upper()}]"
+
+
+@dataclass
+class Config:
+    disable: set[str] = field(default_factory=set)
+    typosquat_max_distance: int = 1
+    custom_detectors: list[CustomRegexDetector] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Config":
+        for ch, sk in (data.get("confusables") or {}).items():
+            register_confusables({ch: sk})
+        customs = []
+        for spec in data.get("custom_detectors", []):
+            customs.append(CustomRegexDetector(
+                label=spec["label"], pattern=spec["pattern"],
+                category=_CAT[spec.get("category", "organisation")],
+                confidence=_CONF[spec.get("confidence", "medium")],
+            ))
+        return cls(
+            disable=set(data.get("disable", [])),
+            typosquat_max_distance=int(data.get("typosquat_max_distance", 1)),
+            custom_detectors=customs,
+        )
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "Config":
+        return cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))
+
+    def build_engine(self) -> DetectionEngine:
+        detectors = [d for d in DEFAULT_DETECTORS if d.name not in self.disable]
+        detectors.extend(self.custom_detectors)
+        return DetectionEngine(detectors)

tabayyan/confusables.py

@@ -0,0 +1,99 @@
+"""Script classification and confusable-skeleton folding.
+
+Used by the homoglyph subsystem to catch domains that impersonate a
+target using visually-confusable characters (IDN homograph attacks) or
+mix scripts. The confusables map is a curated, practical subset of the
+Unicode confusables data — extensible, not exhaustive. See
+homoglyph.py for the detection logic that consumes these primitives.
+"""
+from __future__ import annotations
+
+# Curated confusable -> ASCII/canonical skeleton map.
+# Focus: characters realistically used to spoof Latin domains
+# (Cyrillic, Greek, fullwidth, digit/letter swaps) plus Arabic-Indic
+# digits which appear in mixed Arabic/Latin spoofs.
+_CONFUSABLES: dict[str, str] = {
+    # Cyrillic -> Latin
+    "а": "a", "е": "e", "о": "o", "р": "p", "с": "c", "х": "x",
+    "у": "y", "к": "k", "м": "m", "н": "h", "т": "t", "в": "b",
+    "і": "i", "ј": "j", "ѕ": "s", "ԁ": "d", "ɡ": "g",
+    "ӏ": "l", "Ӏ": "l", "ⅼ": "l", "ｊ": "j",
+    # Greek -> Latin
+    "α": "a", "ο": "o", "ν": "v", "ρ": "p", "τ": "t", "υ": "u",
+    "ι": "i", "κ": "k", "χ": "x", "ε": "e",
+    # Fullwidth Latin -> ASCII
+    "ａ": "a", "ｂ": "b", "ｃ": "c", "ｄ": "d", "ｅ": "e", "ｏ": "o",
+    "ｐ": "p", "ｓ": "s", "ｘ": "x", "ｉ": "i", "ｌ": "l", "ｍ": "m",
+    "ｎ": "n", "ｇ": "g", "ｔ": "t", "ｒ": "r", "ｕ": "u",
+    # Digit/letter confusions folded to a single skeleton
+    "0": "o", "1": "l", "5": "s", "8": "b",
+    "l": "l", "I": "l", "|": "l",
+    # Arabic-Indic and Eastern-Arabic digits -> ASCII digits then folded
+    "٠": "o", "١": "l", "٢": "2", "٣": "3", "٤": "4", "٥": "s",
+    "٦": "6", "٧": "7", "٨": "b", "٩": "9",
+    "۰": "o", "۱": "l", "۲": "2", "۳": "3", "۴": "4", "۵": "s",
+    "۶": "6", "۷": "7", "۸": "b", "۹": "9",
+}
+
+
+def register_confusables(extra: dict[str, str]) -> None:
+    """Merge user-supplied confusable mappings into the global map."""
+    _CONFUSABLES.update(extra)
+
+
+def skeleton(label: str) -> str:
+    """Fold a string to its confusable skeleton (lowercased).
+
+    Two strings with the same skeleton look alike. This is the core
+    primitive for homograph-impersonation detection.
+    """
+    out = []
+    for ch in label.lower():
+        out.append(_CONFUSABLES.get(ch, ch))
+    return "".join(out)
+
+
+# Script ranges (start, end, name). Order matters only for first-match.
+_SCRIPT_RANGES = [
+    (0x0041, 0x005A, "Latin"), (0x0061, 0x007A, "Latin"),
+    (0x00C0, 0x024F, "Latin"),
+    (0x0370, 0x03FF, "Greek"), (0x1F00, 0x1FFF, "Greek"),
+    (0x0400, 0x04FF, "Cyrillic"), (0x0500, 0x052F, "Cyrillic"),
+    (0x0600, 0x06FF, "Arabic"), (0x0750, 0x077F, "Arabic"),
+    (0x08A0, 0x08FF, "Arabic"), (0xFB50, 0xFDFF, "Arabic"),
+    (0xFE70, 0xFEFF, "Arabic"),
+    (0x0590, 0x05FF, "Hebrew"),
+    (0x4E00, 0x9FFF, "Han"),
+    (0x3040, 0x30FF, "Kana"),
+]
+
+
+def script_of(ch: str) -> str:
+    """Return a coarse script name for a single character.
+
+    Digits and ASCII punctuation are 'Common' (script-neutral) so they
+    don't trigger false mixed-script alarms on their own.
+    """
+    cp = ord(ch)
+    if ch.isdigit() and cp < 0x0660:
+        return "Common"
+    if ch in "-._/:":
+        return "Common"
+    for start, end, name in _SCRIPT_RANGES:
+        if start <= cp <= end:
+            return name
+    return "Common"
+
+
+def scripts_in(label: str) -> set[str]:
+    """Return the set of non-Common scripts present in a label."""
+    return {s for s in (script_of(c) for c in label) if s != "Common"}
+
+
+def is_mixed_script(label: str) -> bool:
+    """True if a single label mixes two or more distinct scripts.
+
+    Mixing scripts inside one domain label is a strong spoofing signal:
+    legitimate labels almost never combine, e.g., Latin and Cyrillic.
+    """
+    return len(scripts_in(label)) >= 2

tabayyan/detectors/__init__.py

@@ -0,0 +1,12 @@
+"""Detector registry."""
+from __future__ import annotations
+
+from .base import Detector
+from .generic import GENERIC_DETECTORS
+from .names import ArabicNameDetector
+from .saudi import SAUDI_DETECTORS
+
+DEFAULT_DETECTORS = [*SAUDI_DETECTORS, *GENERIC_DETECTORS, ArabicNameDetector()]
+
+__all__ = ["Detector", "DEFAULT_DETECTORS", "SAUDI_DETECTORS", "GENERIC_DETECTORS",
+           "ArabicNameDetector"]

tabayyan/detectors/base.py

@@ -0,0 +1,15 @@
+"""Detector base class. Detectors are pure: text in, matches out."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Iterable
+
+from ..entities import Match
+
+
+class Detector(ABC):
+    name: str = "detector"
+
+    @abstractmethod
+    def detect(self, text: str) -> Iterable[Match]:
+        raise NotImplementedError

tabayyan/detectors/domains.py

@@ -0,0 +1,37 @@
+"""Opt-in lookalike/homoglyph domain detector.
+
+Not part of DEFAULT_DETECTORS: it needs a watchlist to be most useful and
+it emits THREAT findings, not PII. Construct it explicitly (optionally
+with a watchlist) and pass it to DetectionEngine, or use the `domains`
+CLI command.
+"""
+from __future__ import annotations
+
+from typing import Iterable, Sequence
+
+from ..entities import Category, Confidence, EntityType, Match
+from ..homoglyph import scan_text
+from .base import Detector
+
+_CONF = {"high": Confidence.HIGH, "medium": Confidence.MEDIUM, "low": Confidence.LOW}
+
+
+class LookalikeDomainDetector(Detector):
+    name = "lookalike_domain"
+
+    def __init__(self, watchlist: Sequence[str] | None = None,
+                 typosquat_max_distance: int = 1) -> None:
+        self.watchlist = list(watchlist or [])
+        self.typosquat_max_distance = typosquat_max_distance
+
+    def detect(self, text: str) -> Iterable[Match]:
+        for f in scan_text(text, self.watchlist,
+                           typosquat_max_distance=self.typosquat_max_distance):
+            note = f.detail if f.target is None else f"{f.reason}: {f.detail}"
+            yield Match(
+                entity_type=EntityType.SUSPICIOUS_DOMAIN,
+                category=Category.THREAT,
+                confidence=_CONF[f.confidence],
+                start=f.start, end=f.end, value=f.domain,
+                detector=self.name, notes=note,
+            )

tabayyan/detectors/generic.py

@@ -0,0 +1,50 @@
+"""Generic, locale-independent detectors: email, credit card, IP."""
+from __future__ import annotations
+
+import ipaddress
+import re
+from typing import Iterable
+
+from ..checksums import luhn_is_valid
+from ..entities import Category, Confidence, EntityType, Match
+from .base import Detector
+
+
+class EmailDetector(Detector):
+    name = "email"
+    _pattern = re.compile(r"(?<![A-Za-z0-9._%+\-])[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}")
+
+    def detect(self, text: str) -> Iterable[Match]:
+        for m in self._pattern.finditer(text):
+            yield Match(EntityType.EMAIL, Category.CONTACT, Confidence.MEDIUM,
+                        m.start(), m.end(), m.group(0), self.name)
+
+
+class CreditCardDetector(Detector):
+    name = "credit_card"
+    _pattern = re.compile(r"(?<!\d)(?:\d[ \-]?){12,18}\d(?!\d)")
+
+    def detect(self, text: str) -> Iterable[Match]:
+        for m in self._pattern.finditer(text):
+            digits = re.sub(r"[ \-]", "", m.group(0))
+            if not (13 <= len(digits) <= 19) or not luhn_is_valid(digits):
+                continue
+            yield Match(EntityType.CREDIT_CARD, Category.FINANCIAL, Confidence.HIGH,
+                        m.start(), m.end(), digits, self.name, "Luhn-valid")
+
+
+class IpAddressDetector(Detector):
+    name = "ip_address"
+    _candidate = re.compile(r"(?<![\w.])(?:\d{1,3}(?:\.\d{1,3}){3}|[0-9A-Fa-f:]{2,}:[0-9A-Fa-f:]*)(?![\w.])")
+
+    def detect(self, text: str) -> Iterable[Match]:
+        for m in self._candidate.finditer(text):
+            try:
+                ipaddress.ip_address(m.group(0))
+            except ValueError:
+                continue
+            yield Match(EntityType.IP_ADDRESS, Category.NETWORK, Confidence.MEDIUM,
+                        m.start(), m.end(), m.group(0), self.name)
+
+
+GENERIC_DETECTORS = [EmailDetector(), CreditCardDetector(), IpAddressDetector()]