evadex 0.1.0__py3-none-any.whl

evadex/__init__.py

@@ -0,0 +1,5 @@
+from importlib.metadata import version, PackageNotFoundError
+try:
+    __version__ = version("evadex")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

evadex/__main__.py

@@ -0,0 +1,3 @@
+from evadex.cli.app import main
+if __name__ == "__main__":
+    main()

evadex/adapters/base.py

@@ -0,0 +1,49 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional
+from evadex.core.result import Payload, Variant, ScanResult
+
+
+class AdapterError(Exception):
+    pass
+
+
+@dataclass
+class AdapterConfig:
+    base_url: str = "http://localhost:8080"
+    api_key: Optional[str] = None
+    timeout: float = 30.0
+    extra: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AdapterConfig":
+        extra = {k: v for k, v in d.items() if k not in ("base_url", "api_key", "timeout")}
+        return cls(
+            base_url=d.get("base_url", "http://localhost:8080"),
+            api_key=d.get("api_key"),
+            timeout=float(d.get("timeout", 30.0)),
+            extra=extra,
+        )
+
+
+class BaseAdapter(ABC):
+    name: str = "base"
+
+    def __init__(self, config: "dict | AdapterConfig"):
+        if isinstance(config, dict):
+            self.config = AdapterConfig.from_dict(config)
+        else:
+            self.config = config
+
+    @abstractmethod
+    async def submit(self, payload: Payload, variant: Variant) -> ScanResult:
+        pass
+
+    async def setup(self):
+        pass
+
+    async def teardown(self):
+        pass
+
+    async def health_check(self) -> bool:
+        return True

evadex/adapters/dlpscan/adapter.py

@@ -0,0 +1,69 @@
+from evadex.adapters.base import BaseAdapter, AdapterConfig
+from evadex.adapters.dlpscan.client import DlpscanClient
+from evadex.adapters.dlpscan.file_builder import FileBuilder
+from evadex.core.registry import register_adapter
+from evadex.core.result import Payload, Variant, ScanResult
+
+
+@register_adapter("dlpscan")
+class DlpscanAdapter(BaseAdapter):
+    name = "dlpscan"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self._client = DlpscanClient(
+            base_url=self.config.base_url,
+            api_key=self.config.api_key,
+            timeout=self.config.timeout,
+        )
+        # Key in response JSON that indicates detection. Configurable via adapter extra config.
+        self._detected_key = self.config.extra.get("response_detected_key", "detected")
+
+    async def setup(self):
+        pass
+
+    async def teardown(self):
+        await self._client.close()
+
+    async def health_check(self) -> bool:
+        try:
+            await self._client.get_health()
+            return True
+        except Exception:
+            return False
+
+    async def submit(self, payload: Payload, variant: Variant) -> ScanResult:
+        strategy = variant.strategy
+        if strategy == "text":
+            raw = await self._client.post_text(variant.value)
+        else:
+            data, mime = FileBuilder.build(variant.value, strategy)
+            filename = f"evadex_test.{strategy}"
+            raw = await self._client.upload_file(data, filename, mime)
+
+        detected = self._parse_response(raw)
+        return ScanResult(payload=payload, variant=variant, detected=detected, raw_response=raw)
+
+    def _parse_response(self, raw: dict) -> bool:
+        # Try configured key first
+        if self._detected_key in raw:
+            val = raw[self._detected_key]
+            if isinstance(val, bool):
+                return val
+            if isinstance(val, (int, float)):
+                return bool(val)
+            if isinstance(val, str):
+                return val.lower() in ('true', '1', 'yes', 'detected')
+
+        # Try common response shapes
+        for key in ("detected", "found", "matches", "findings", "alert", "flagged"):
+            if key in raw:
+                val = raw[key]
+                if isinstance(val, bool):
+                    return val
+                if isinstance(val, list):
+                    return len(val) > 0
+                if isinstance(val, (int, float)):
+                    return bool(val)
+
+        return False

evadex/adapters/dlpscan/client.py

@@ -0,0 +1,74 @@
+import httpx
+from typing import Optional
+from evadex.adapters.base import AdapterError
+
+
+class DlpscanClient:
+    def __init__(self, base_url: str, api_key: Optional[str] = None, timeout: float = 30.0):
+        self.base_url = base_url.rstrip('/')
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._headers = headers
+        self._timeout = timeout
+        self._client: Optional[httpx.AsyncClient] = None
+
+    async def __aenter__(self):
+        self._client = httpx.AsyncClient(headers=self._headers, timeout=self._timeout)
+        return self
+
+    async def __aexit__(self, *args):
+        if self._client:
+            await self._client.aclose()
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self._timeout)
+        return self._client
+
+    async def post_text(self, text: str) -> dict:
+        client = await self._get_client()
+        # Exclude Content-Type so httpx sets it correctly for JSON
+        headers = {k: v for k, v in self._headers.items() if k != "Content-Type"}
+        try:
+            resp = await client.post(
+                f"{self.base_url}/scan",
+                json={"content": text},
+                headers=headers,
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            raise AdapterError(f"HTTP {e.response.status_code}: {e.response.text}") from e
+        except httpx.RequestError as e:
+            raise AdapterError(f"Request failed: {e}") from e
+
+    async def upload_file(self, data: bytes, filename: str, mime_type: str) -> dict:
+        client = await self._get_client()
+        headers = {k: v for k, v in self._headers.items() if k != "Content-Type"}
+        try:
+            resp = await client.post(
+                f"{self.base_url}/scan/file",
+                files={"file": (filename, data, mime_type)},
+                headers=headers,
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            raise AdapterError(f"HTTP {e.response.status_code}: {e.response.text}") from e
+        except httpx.RequestError as e:
+            raise AdapterError(f"Request failed: {e}") from e
+
+    async def get_health(self) -> dict:
+        client = await self._get_client()
+        try:
+            resp = await client.get(f"{self.base_url}/health")
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as e:
+            raise AdapterError(f"Health check failed: {e}") from e
+
+    async def close(self):
+        if self._client:
+            await self._client.aclose()
+            self._client = None

evadex/adapters/dlpscan/file_builder.py

@@ -0,0 +1,112 @@
+import io
+from typing import Literal
+
+try:
+    from docx import Document
+    HAS_DOCX = True
+except ImportError:
+    HAS_DOCX = False
+
+try:
+    from fpdf import FPDF
+    HAS_FPDF = True
+except ImportError:
+    HAS_FPDF = False
+
+try:
+    import openpyxl
+    HAS_OPENPYXL = True
+except ImportError:
+    HAS_OPENPYXL = False
+
+
+DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+PDF_MIME  = "application/pdf"
+XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+
+NOISE_SENTENCES = [
+    "This document contains confidential business information.",
+    "Please handle with care and do not distribute.",
+    "For internal use only.",
+    "Authorized personnel only.",
+]
+
+
+class FileBuilder:
+    @staticmethod
+    def build(text: str, fmt: Literal["docx", "pdf", "xlsx"]) -> tuple[bytes, str]:
+        """Build an in-memory document containing text. Returns (bytes, mime_type).
+        Never writes to disk — uses io.BytesIO only.
+        """
+        if fmt == "docx":
+            return FileBuilder._build_docx(text), DOCX_MIME
+        elif fmt == "pdf":
+            return FileBuilder._build_pdf(text), PDF_MIME
+        elif fmt == "xlsx":
+            return FileBuilder._build_xlsx(text), XLSX_MIME
+        else:
+            raise ValueError(f"Unknown format: {fmt!r}")
+
+    @staticmethod
+    def _build_docx(text: str) -> bytes:
+        if not HAS_DOCX:
+            raise RuntimeError("python-docx is required for DOCX generation")
+        doc = Document()
+        doc.add_paragraph(NOISE_SENTENCES[0])
+        doc.add_paragraph(NOISE_SENTENCES[1])
+        doc.add_paragraph(text)
+        doc.add_paragraph(NOISE_SENTENCES[2])
+        buf = io.BytesIO()
+        doc.save(buf)
+        return buf.getvalue()
+
+    @staticmethod
+    def _build_pdf(text: str) -> bytes:
+        if not HAS_FPDF:
+            raise RuntimeError("fpdf2 is required for PDF generation")
+        pdf = FPDF()
+        pdf.add_page()
+        # Try DejaVu (bundled with fpdf2 >= 2.7.6) for full Unicode support.
+        # Fall back to Helvetica for ASCII-only content if DejaVu is unavailable.
+        try:
+            pdf.set_font("DejaVu", size=12)
+        except Exception:
+            # DejaVu not available — encode text to latin-1 safe subset
+            pdf.set_font("Helvetica", size=12)
+            text = text.encode("latin-1", errors="replace").decode("latin-1")
+
+        for sentence in NOISE_SENTENCES[:2]:
+            try:
+                pdf.cell(0, 10, sentence, new_x="LMARGIN", new_y="NEXT")
+            except Exception:
+                safe = sentence.encode("latin-1", errors="replace").decode("latin-1")
+                pdf.cell(0, 10, safe, new_x="LMARGIN", new_y="NEXT")
+
+        try:
+            pdf.cell(0, 10, text, new_x="LMARGIN", new_y="NEXT")
+        except Exception:
+            safe = text.encode("latin-1", errors="replace").decode("latin-1")
+            pdf.cell(0, 10, safe, new_x="LMARGIN", new_y="NEXT")
+
+        pdf.cell(0, 10, NOISE_SENTENCES[2], new_x="LMARGIN", new_y="NEXT")
+
+        buf = io.BytesIO()
+        pdf.output(buf)
+        return buf.getvalue()
+
+    @staticmethod
+    def _build_xlsx(text: str) -> bytes:
+        if not HAS_OPENPYXL:
+            raise RuntimeError("openpyxl is required for XLSX generation")
+        wb = openpyxl.Workbook()
+        ws = wb.active
+        ws['A1'] = NOISE_SENTENCES[0]
+        ws['A2'] = text
+        ws['A3'] = NOISE_SENTENCES[1]
+        ws['B1'] = "Document ID"
+        ws['B2'] = "12345"
+        ws['C1'] = "Classification"
+        ws['C2'] = "Confidential"
+        buf = io.BytesIO()
+        wb.save(buf)
+        return buf.getvalue()

evadex/adapters/dlpscan_cli/adapter.py

@@ -0,0 +1,56 @@
+import asyncio
+import json
+import tempfile
+import os
+from evadex.adapters.base import BaseAdapter
+from evadex.adapters.dlpscan.file_builder import FileBuilder
+from evadex.core.registry import register_adapter
+from evadex.core.result import Payload, Variant, ScanResult
+
+
+@register_adapter("dlpscan-cli")
+class DlpscanCliAdapter(BaseAdapter):
+    name = "dlpscan-cli"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self._exe = self.config.extra.get("executable", "dlpscan")
+
+    async def submit(self, payload: Payload, variant: Variant) -> ScanResult:
+        strategy = variant.strategy
+        loop = asyncio.get_event_loop()
+
+        if strategy == "text":
+            raw = await loop.run_in_executor(None, self._scan_text, variant.value)
+        else:
+            data, _ = FileBuilder.build(variant.value, strategy)
+            raw = await loop.run_in_executor(None, self._scan_bytes, data, strategy)
+
+        detected = len(raw) > 0
+        return ScanResult(payload=payload, variant=variant, detected=detected, raw_response={"matches": raw})
+
+    def _scan_text(self, text: str) -> list:
+        suffix = ".txt"
+        return self._run_on_tempfile(text.encode("utf-8"), suffix)
+
+    def _scan_bytes(self, data: bytes, fmt: str) -> list:
+        suffix = f".{fmt}"
+        return self._run_on_tempfile(data, suffix)
+
+    def _run_on_tempfile(self, data: bytes, suffix: str) -> list:
+        with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as f:
+            f.write(data)
+            path = f.name
+        try:
+            import subprocess
+            result = subprocess.run(
+                [self._exe, "-f", "json", path],
+                capture_output=True,
+                text=True,
+                timeout=self.config.timeout,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(f"dlpscan exited {result.returncode}: {result.stderr.strip()}")
+            return json.loads(result.stdout or "[]")
+        finally:
+            os.unlink(path)

evadex/cli/app.py

@@ -0,0 +1,15 @@
+import click
+from rich.console import Console
+from evadex.cli.commands.scan import scan
+
+console = Console()
+
+
+@click.group()
+@click.version_option(package_name="evadex")
+def main():
+    """evadex — DLP evasion test suite."""
+    pass
+
+
+main.add_command(scan)

evadex/cli/commands/scan.py

@@ -0,0 +1,114 @@
+import sys
+import click
+from rich.console import Console
+from evadex.core.registry import load_builtins, get_adapter, all_generators, get_generator
+from evadex.core.engine import Engine
+from evadex.core.result import Payload, PayloadCategory
+from evadex.payloads.builtins import get_payloads, detect_category
+from evadex.reporters.json_reporter import JsonReporter
+from evadex.reporters.html_reporter import HtmlReporter
+
+err_console = Console(stderr=True)
+
+STRATEGY_CHOICES = click.Choice(["text", "docx", "pdf", "xlsx"])
+CATEGORY_CHOICES = click.Choice([c.value for c in PayloadCategory])
+
+
+@click.command()
+@click.option("--tool", "-t", default="dlpscan", show_default=True, help="DLP adapter to use")
+@click.option("--input", "-i", "input_value", default=None,
+              help="Single value to test (if omitted, runs all built-ins)")
+@click.option("--format", "-f", "fmt", type=click.Choice(["json", "html"]),
+              default="json", show_default=True)
+@click.option("--output", "-o", default=None, help="Output file path (default: stdout)")
+@click.option("--url", default="http://localhost:8080", show_default=True,
+              help="Adapter base URL")
+@click.option("--api-key", default=None, envvar="EVADEX_API_KEY",
+              help="API key for adapter")
+@click.option("--timeout", default=30.0, show_default=True, type=float,
+              help="Request timeout in seconds")
+@click.option("--strategy", "strategies", multiple=True, type=STRATEGY_CHOICES,
+              help="Submission strategies to use (default: all). Repeat for multiple.")
+@click.option("--concurrency", default=5, show_default=True, type=int,
+              help="Max concurrent requests")
+@click.option("--category", "categories", multiple=True, type=CATEGORY_CHOICES,
+              help="Filter built-in payloads by category. Repeat for multiple.")
+@click.option("--variant-group", "variant_groups", multiple=True,
+              help="Limit to specific generator names. Repeat for multiple.")
+def scan(
+    tool, input_value, fmt, output, url, api_key, timeout,
+    strategies, concurrency, categories, variant_groups,
+):
+    """Run DLP evasion tests."""
+    load_builtins()
+
+    # Resolve strategies
+    active_strategies = list(strategies) if strategies else ["text", "docx", "pdf", "xlsx"]
+
+    # Resolve payloads
+    if input_value:
+        category = detect_category(input_value)
+        payloads = [Payload(
+            value=input_value,
+            category=category,
+            label=f"Custom ({category.value})",
+        )]
+    else:
+        filter_cats = {PayloadCategory(c) for c in categories} if categories else None
+        payloads = get_payloads(filter_cats)
+
+    if not payloads:
+        err_console.print("[red]No payloads to test.[/red]")
+        sys.exit(1)
+
+    # Resolve adapter
+    config = {"base_url": url, "api_key": api_key, "timeout": timeout}
+    try:
+        adapter = get_adapter(tool, config)
+    except KeyError as e:
+        err_console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    # Resolve generators
+    if variant_groups:
+        try:
+            generators = [get_generator(name) for name in variant_groups]
+        except KeyError as e:
+            err_console.print(f"[red]{e}[/red]")
+            sys.exit(1)
+    else:
+        generators = None  # use all registered
+
+    # Run engine
+    err_console.print(
+        f"[dim]Running evadex scan against [bold]{tool}[/bold] at {url}...[/dim]"
+    )
+    engine = Engine(
+        adapter=adapter,
+        generators=generators,
+        concurrency=concurrency,
+        strategies=active_strategies,
+    )
+    results = engine.run(payloads)
+
+    # Summary
+    total  = len(results)
+    passes = sum(1 for r in results if r.detected)
+    fails  = total - passes
+    err_console.print(
+        f"[green]Done.[/green] {total} tests \u2014 "
+        f"[green]{passes} detected[/green], [red]{fails} evaded[/red]"
+    )
+
+    # Report
+    reporter = HtmlReporter() if fmt == "html" else JsonReporter()
+    rendered = reporter.render(results)
+
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(rendered)
+        err_console.print(f"[dim]Report written to {output}[/dim]")
+    else:
+        sys.stdout.buffer.write(rendered.encode("utf-8"))
+        sys.stdout.buffer.write(b"\n")
+        sys.stdout.buffer.flush()

evadex/core/engine.py

@@ -0,0 +1,81 @@
+import asyncio
+import time
+from typing import AsyncIterator
+from evadex.core.result import Payload, ScanResult
+from evadex.adapters.base import BaseAdapter
+from evadex.variants.base import BaseVariantGenerator
+from evadex.core.registry import all_generators
+
+
+class Engine:
+    def __init__(
+        self,
+        adapter: BaseAdapter,
+        generators: list[BaseVariantGenerator] | None = None,
+        concurrency: int = 5,
+        strategies: list[str] | None = None,
+    ):
+        self.adapter = adapter
+        self.generators = generators  # None = use all registered
+        self.concurrency = concurrency
+        self.strategies = strategies or ["text", "docx", "pdf", "xlsx"]
+
+    def run(self, payloads: list[Payload]) -> list[ScanResult]:
+        return asyncio.run(self._run_async_collect(payloads))
+
+    async def _run_async_collect(self, payloads: list[Payload]) -> list[ScanResult]:
+        results = []
+        async for r in self.run_async(payloads):
+            results.append(r)
+        return results
+
+    async def run_async(self, payloads: list[Payload]) -> AsyncIterator[ScanResult]:
+        generators = self.generators if self.generators is not None else all_generators()
+        sem = asyncio.Semaphore(self.concurrency)
+        tasks = []
+
+        for payload in payloads:
+            for gen in generators:
+                # Check applicable_categories
+                if hasattr(gen, 'applicable_categories') and gen.applicable_categories is not None:
+                    if payload.category not in gen.applicable_categories:
+                        continue
+                for variant in gen.generate(payload.value):
+                    for strategy in self.strategies:
+                        tasks.append(self._run_one(sem, payload, variant, strategy))
+
+        await self.adapter.setup()
+        try:
+            for coro in asyncio.as_completed(tasks):
+                result = await coro
+                yield result
+        finally:
+            await self.adapter.teardown()
+
+    async def _run_one(
+        self, sem: asyncio.Semaphore, payload: Payload, variant, strategy: str
+    ) -> ScanResult:
+        from evadex.core.result import Variant, ScanResult
+
+        # Clone variant with strategy
+        v = Variant(
+            value=variant.value,
+            generator=variant.generator,
+            technique=variant.technique,
+            transform_name=variant.transform_name,
+            strategy=strategy,
+        )
+        async with sem:
+            start = time.perf_counter()
+            try:
+                result = await self.adapter.submit(payload, v)
+                result.duration_ms = (time.perf_counter() - start) * 1000
+                return result
+            except Exception as e:
+                return ScanResult(
+                    payload=payload,
+                    variant=v,
+                    detected=False,
+                    error=str(e),
+                    duration_ms=(time.perf_counter() - start) * 1000,
+                )

evadex/core/registry.py

@@ -0,0 +1,46 @@
+_GENERATORS: dict = {}
+_ADAPTERS: dict = {}
+
+
+def register_generator(name: str):
+    def decorator(cls):
+        _GENERATORS[name] = cls
+        return cls
+    return decorator
+
+
+def register_adapter(name: str):
+    def decorator(cls):
+        _ADAPTERS[name] = cls
+        return cls
+    return decorator
+
+
+def get_generator(name: str):
+    if name not in _GENERATORS:
+        raise KeyError(f"No generator registered: {name!r}")
+    return _GENERATORS[name]()
+
+
+def get_adapter(name: str, config=None):
+    if name not in _ADAPTERS:
+        raise KeyError(f"No adapter registered: {name!r}. Available: {list(_ADAPTERS)}")
+    return _ADAPTERS[name](config or {})
+
+
+def all_generators():
+    return [cls() for cls in _GENERATORS.values()]
+
+
+def load_builtins():
+    # Import all variant modules so their @register_generator decorators fire
+    import evadex.variants.unicode_encoding
+    import evadex.variants.delimiter
+    import evadex.variants.splitting
+    import evadex.variants.leetspeak
+    import evadex.variants.regional_digits
+    import evadex.variants.structural
+    import evadex.variants.encoding
+    # Import adapters
+    import evadex.adapters.dlpscan.adapter
+    import evadex.adapters.dlpscan_cli.adapter