pentool 1.0.0__py3-none-any.whl

pentool/api/scanner_api.py

@@ -0,0 +1,336 @@
+"""ScannerAPI — публичный интерфейс Scanner для TUI и CLI."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Callable
+
+from pentool.core.utils import run_async_sync
+
+from pentool.core.logging import get_logger
+from pentool.modules.scanner.base import BaseCheck, Finding
+from pentool.modules.scanner.checks import (
+    InfoLeakCheck,
+    LFICheck,
+    MissingSecurityHeadersCheck,
+    OpenRedirectCheck,
+    PathTraversalCheck,
+    HeaderInjectionCheck,
+    RCECheck,
+    SQLiCheck,
+    SSTICheck,
+    SSRFCheck,
+    XSSCheck,
+    XXECheck,
+    CORSCheck,
+    BrokenAuthCheck,
+    JWTNoneCheck,
+    NoSQLInjectionCheck,
+    GraphQLCheck,
+    PrototypePollutionCheck,
+    DOMXSSCheck,
+    OAuthCheck,
+    SensitiveDataCheck,
+)
+from pentool.modules.scanner.checks.header_injection import HostHeaderInjectionCheck
+from pentool.modules.scanner.checks.sqli import SQLiUnionCheck
+from pentool.modules.scanner.engine import ScanEngine
+from pentool.modules.scanner.passive import PassiveScanner
+from pentool.modules.scanner.report import (
+    generate_csv_report,
+    generate_html_report,
+    generate_json_report,
+)
+
+logger = get_logger(__name__)
+
+__all__ = ["ScannerAPI", "Finding", "BaseCheck"]
+
+
+class ScannerAPI:
+    """Фасад над ScanEngine + PassiveScanner."""
+
+    def __init__(self, db_path: str = "", http_client=None) -> None:
+        self._db_path = db_path
+        self._http_client = http_client
+        self._engine: ScanEngine | None = None
+        self._passive: PassiveScanner | None = None
+        self._active_task: asyncio.Task | None = None
+        self._scan_id: str | None = None
+
+    def _get_engine(self) -> ScanEngine:
+        if self._engine is None:
+            self._engine = ScanEngine(
+                db_path=self._db_path,
+                http_client=self._http_client,
+            )
+            self._engine.register_checks([
+                MissingSecurityHeadersCheck(),
+                InfoLeakCheck(),
+                SQLiCheck(),
+                XSSCheck(),
+                SSTICheck(),
+                LFICheck(),
+                PathTraversalCheck(),
+                HeaderInjectionCheck(),
+                HostHeaderInjectionCheck(),
+                RCECheck(),
+                OpenRedirectCheck(),
+                SSRFCheck(),
+                XXECheck(),
+                CORSCheck(),
+                BrokenAuthCheck(),
+                JWTNoneCheck(),
+                NoSQLInjectionCheck(),
+                GraphQLCheck(),
+                PrototypePollutionCheck(),
+                DOMXSSCheck(),
+                OAuthCheck(),
+                SensitiveDataCheck(),
+                SQLiUnionCheck(),
+            ])
+        return self._engine
+
+    async def start_active_scan(
+        self,
+        targets: list[str],
+        check_names: list[str] | None = None,
+        on_finding: Callable[[Finding | None, None]] = None,
+        on_progress: Callable[[int, int | None, None]] = None,
+        on_request: Callable[[str, str | None, None]] = None,
+        concurrency: int = 5,
+        request_delay: float = 0.0,
+    ) -> str:
+        """Запустить активное сканирование. Возвращает scan_id."""
+        import uuid
+        self._scan_id = str(uuid.uuid4())
+        engine = self._get_engine()
+        engine._concurrency = concurrency
+        engine._request_delay = request_delay
+
+        async def _run() -> None:
+            findings = await engine.run_active(
+                targets,
+                check_names=check_names,
+                on_finding=on_finding,
+                on_progress=on_progress,
+                on_request=on_request,
+            )
+            await engine.save_findings(findings)
+
+        self._active_task = asyncio.create_task(_run())
+        return self._scan_id
+
+    async def stop_scan(self) -> None:
+        """Остановить активное сканирование."""
+        if self._active_task and not self._active_task.done():
+            self._active_task.cancel()
+            try:
+                await self._active_task
+            except asyncio.CancelledError:
+                pass
+        self._active_task = None
+
+    def is_scanning(self) -> bool:
+        """Возвращает True если активное сканирование ещё выполняется."""
+        return bool(self._active_task and not self._active_task.done())
+
+    async def get_findings(self, limit: int = 200) -> list[Finding]:
+        """Получить список findings из БД.
+
+        Args:
+            limit: Максимальное количество возвращаемых записей.
+
+        Returns:
+            Список объектов Finding, отсортированный по времени (новые первые).
+        """
+        return await self._get_engine().get_findings(limit)
+
+    async def mark_false_positive(self, finding_id: str) -> None:
+        """Пометить finding как ложное срабатывание (false positive).
+
+        Args:
+            finding_id: UUID строка идентификатора finding.
+        """
+        await self._get_engine().mark_false_positive(finding_id)
+
+    async def attach_passive(self, proxy_api=None) -> None:
+        """Подключить пассивный сканер через EventBus (Sprint 3).
+
+        proxy_api оставлен для обратной совместимости сигнатуры,
+        но больше не используется — PassiveScanner подписывается на
+        ProxyRequestCompleted через EventBus напрямую.
+        """
+        engine = self._get_engine()
+        self._passive = PassiveScanner(engine)
+        self._passive.attach_bus()
+        logger.info("Passive scanner attached via EventBus")
+
+    async def detach_passive(self) -> None:
+        """Отключить пассивный сканер."""
+        if self._passive:
+            self._passive.detach_bus()
+        self._passive = None
+
+    def set_passive_callback(self, callback: Callable[[Finding], None]) -> None:
+        """Установить коллбэк для пассивного сканера.
+
+        Args:
+            callback: Функция вида callback(finding) — вызывается при каждом новом finding.
+        """
+        if self._passive:
+            self._passive.on_finding = callback
+
+    async def generate_report(self, path: str, fmt: str = "html") -> None:
+        """Сгенерировать отчёт. fmt: 'html' | 'json' | 'csv'."""
+        findings = await self.get_findings(limit=10000)
+        fmt = fmt.lower()
+        if fmt == "html":
+            generate_html_report(findings, path)
+        elif fmt == "json":
+            generate_json_report(findings, path)
+        elif fmt == "csv":
+            generate_csv_report(findings, path)
+        else:
+            raise ValueError(f"Unknown report format: {fmt}")
+        logger.info("Report generated: %s (%s)", path, fmt)
+
+    def register_check(self, check: BaseCheck) -> None:
+        """Зарегистрировать дополнительный check в движке сканера.
+
+        Args:
+            check: Экземпляр BaseCheck (или подкласса) для добавления.
+        """
+        self._get_engine().register_check(check)
+
+    def get_registered_checks(self) -> list[BaseCheck]:
+        """Получить список всех зарегистрированных checks.
+
+        Returns:
+            Список объектов BaseCheck в порядке регистрации.
+        """
+        return self._get_engine().get_registered_checks()
+
+    # ── Project persistence ────────────────────────────────────────────────────
+
+    def export_project_data(self) -> dict:
+        """Экспортировать findings в сериализуемый dict для сохранения проекта.
+
+        Читает findings из SQLite через синхронный вызов (блокирует ненадолго).
+        Используется из action_save_project в app.py (main thread, sync).
+        """
+        try:
+            findings = run_async_sync(self.get_findings(limit=10_000), timeout=10)
+        except Exception as exc:
+            logger.warning("export_project_data: %s", exc)
+            findings = []
+        return {"findings": [f.to_dict() for f in (findings or [])]}
+
+    def import_project_data(self, data: dict) -> int:
+        """Импортировать findings из загруженного dict проекта.
+
+        Args:
+            data: Блок "scanner" из project.json ({"findings": [...]}).
+
+        Returns:
+            Количество загруженных findings.
+        """
+        findings_data = data.get("findings", [])
+        if not findings_data:
+            return 0
+
+        findings = []
+        for fd in findings_data:
+            try:
+                findings.append(Finding.from_dict(fd))
+            except Exception as exc:
+                logger.warning("ScannerAPI.import_project_data: skip finding: %s", exc)
+
+        if not findings:
+            return 0
+
+        # Пишем в SQLite через save_findings (нужен async контекст)
+        engine = self._get_engine()
+        try:
+            run_async_sync(engine.save_findings(findings), timeout=15)
+            return len(findings)
+        except Exception as exc:
+            logger.warning("import_project_data save_findings: %s", exc)
+            return 0
+
+    async def get_stats(self) -> dict:
+        """Агрегированная статистика для Dashboard.
+
+        Returns:
+            dict с ключами:
+              findings: dict[severity → count]
+              top_finding: str — тип последнего finding или "—"
+        """
+        return await self._get_engine().get_stats()
+
+    async def get_host_count(self) -> int:
+        """Количество уникальных хостов в истории HTTP-запросов."""
+        try:
+            from pentool.storage.http_storage import HttpStorage
+            storage = HttpStorage()
+            await storage.init_db(self._db_path)
+            try:
+                return await storage.count_distinct_hosts()
+            finally:
+                await storage.close()
+        except Exception as exc:
+            logger.debug("ScannerAPI.get_host_count: %s", exc)
+            return 0
+
+    async def get_history_requests(
+        self,
+        scope_host: str = "",
+        limit: int = 500,
+    ) -> list:
+        """Загрузить ParsedRequest из истории Proxy для скана.
+
+        Args:
+            scope_host: если задан — фильтровать только по этому хосту.
+            limit: максимальное число запросов.
+
+        Returns:
+            list[ParsedRequest] — дедуплицированные по (method, path_template).
+        """
+        from pentool.storage.http_storage import HttpStorage
+        from pentool.utils.parser import ParsedRequest
+        import re as _re
+
+        storage = HttpStorage()
+        try:
+            await storage.init_db(self._db_path)
+            entries = await storage.export_all_requests(limit=limit)
+        finally:
+            await storage.close()
+
+        seen: set[str] = set()
+        result: list[ParsedRequest] = []
+
+        for entry in entries:
+            url: str = entry.get("url", "") or ""
+            method: str = (entry.get("method", "GET") or "GET").upper()
+            if not url:
+                continue
+            if scope_host and scope_host not in url:
+                continue
+            # Дедупликация по (method, path без значений параметров)
+            path_tmpl = _re.sub(r"=[^&]*", "=", url.split("?")[0])
+            dedup_key = f"{method}:{path_tmpl}"
+            if dedup_key in seen:
+                continue
+            seen.add(dedup_key)
+
+            headers: dict = entry.get("request_headers", {}) or {}
+            body: str = entry.get("request_body", "") or ""
+            result.append(ParsedRequest(
+                method=method,
+                url=url,
+                headers=headers,
+                body=body,
+            ))
+
+        return result

pentool/api/sequencer_api.py

@@ -0,0 +1,21 @@
+"""SequencerAPI — публичный интерфейс Sequencer для TUI.
+
+TUI-экраны импортируют только этот модуль,
+не modules/sequencer.py напрямую.
+"""
+
+from __future__ import annotations
+
+from pentool.modules.sequencer import (  # noqa: F401
+    Sequencer,
+    SequencerReport,
+    token_entropy,
+    charset_size,
+)
+
+__all__ = [
+    "Sequencer",
+    "SequencerReport",
+    "token_entropy",
+    "charset_size",
+]

pentool/api/spider_api.py

@@ -0,0 +1,126 @@
+"""SpiderAPI — публичный интерфейс Spider-модуля для TUI и CLI.
+
+Обёртка над AsyncSpider. TUI-экраны импортируют только этот модуль,
+не modules/spider.py напрямую.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from pentool.core.logging import get_logger
+from pentool.modules.spider import (
+    AsyncSpider,
+    SpiderEndpoint,
+    SpiderForm,
+    SpiderResult,
+    is_playwright_available,
+)
+
+logger = get_logger(__name__)
+
+# Реэкспорт типов — TUI использует их отсюда
+__all__ = [
+    "SpiderAPI", "SpiderResult", "SpiderForm", "SpiderEndpoint", "SpiderConfig",
+    "is_playwright_available",
+]
+
+
+@dataclass
+class SpiderConfig:
+    """Конфигурация краулера."""
+    max_depth: int = 3
+    max_pages: int = 100
+    concurrency: int = 5
+    timeout: float = 10.0
+    user_agent: str = "pentool/1.0"
+    respect_scope: bool = False
+    js_render: bool = False  # Playwright JS-рендеринг (если установлен)
+
+
+class SpiderAPI:
+    """Публичный интерфейс краулера.
+
+    Тонкая обёртка над AsyncSpider. Не знает о Textual.
+    Конфигурируется через SpiderConfig.
+    """
+
+    def __init__(self, config: SpiderConfig | None = None) -> None:
+        self._config = config or SpiderConfig()
+        self._spider: AsyncSpider | None = None
+        self._stop_requested = False
+
+    @classmethod
+    def from_params(
+        cls,
+        max_depth: int = 3,
+        max_pages: int = 100,
+        concurrency: int = 5,
+        timeout: float = 10.0,
+    ) -> "SpiderAPI":
+        """Удобный фабричный метод."""
+        return cls(SpiderConfig(
+            max_depth=max_depth,
+            max_pages=max_pages,
+            concurrency=concurrency,
+            timeout=timeout,
+        ))
+
+    async def crawl(
+        self,
+        url: str,
+        on_page: Callable[[str], None] | None = None,
+        on_progress: Callable[[int, int], None] | None = None,
+        extra_headers: dict | None = None,
+    ) -> SpiderResult:
+        """Запустить краулинг начиная с url.
+
+        Args:
+            url:          Стартовый URL.
+            on_page:      Коллбэк на каждую найденную страницу.
+            on_progress:  Коллбэк прогресса (done, total).
+            extra_headers: Cookie/Authorization из seed_request для auth-контекста.
+
+        Returns:
+            SpiderResult с pages, forms, endpoints, js_files, errors.
+        """
+        self._stop_requested = False
+        cfg = self._config
+        self._spider = AsyncSpider(
+            max_depth=cfg.max_depth,
+            max_pages=cfg.max_pages,
+            concurrency=cfg.concurrency,
+            respect_scope=cfg.respect_scope,
+            js_render=cfg.js_render,
+            extra_headers=extra_headers or {},
+        )
+        if on_page:
+            self._spider.on_page = on_page
+        if on_progress:
+            self._spider.on_progress = on_progress
+
+        try:
+            result = await self._spider.crawl(url)
+            logger.info(
+                "SpiderAPI.crawl: %s → %d pages, %d forms, %d endpoints",
+                url, len(result.pages), len(result.forms), len(result.endpoints),
+            )
+            return result
+        except Exception as exc:
+            logger.warning("SpiderAPI.crawl error for %s: %s", url, exc)
+            return SpiderResult(pages=[], forms=[], endpoints=[], js_files=[], errors=[str(exc)])
+
+    def stop(self) -> None:
+        """Запросить остановку краулинга."""
+        self._stop_requested = True
+        if self._spider is not None:
+            try:
+                self._spider._stop_requested = True
+            except Exception:
+                pass
+
+    @property
+    def config(self) -> SpiderConfig:
+        """Текущая конфигурация краулера (max_depth, max_pages, concurrency)."""
+        return self._config

pentool/api/target_api.py

@@ -0,0 +1,121 @@
+"""TargetAPI — публичный интерфейс Target/SiteMap для TUI и CLI."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pentool.core.logging import get_logger
+from pentool.modules.target import SiteMap, SiteNode
+
+if TYPE_CHECKING:
+    from pentool.utils.parser import ParsedRequest
+
+logger = get_logger(__name__)
+
+__all__ = ["TargetAPI", "SiteNode", "SiteMap"]
+
+
+class TargetAPI:
+    """Фасад над SiteMap."""
+
+    def __init__(self, db_path: str = "") -> None:
+        self._db_path = db_path
+        self._sitemap = SiteMap(db_path=db_path)
+
+    @property
+    def sitemap(self) -> SiteMap:
+        """Прямой доступ к объекту SiteMap."""
+        return self._sitemap
+
+    async def load(self) -> None:
+        """Загрузить карту сайта из БД."""
+        await self._sitemap.load()
+
+    async def save(self) -> None:
+        """Сохранить карту сайта в БД."""
+        await self._sitemap.save()
+
+    def add_request(self, req: "ParsedRequest") -> None:
+        """Добавить запрос в карту (вызывается из on_request_done прокси)."""
+        self._sitemap.add_request(req)
+
+    async def get_tree(self) -> dict[str, list[SiteNode]]:
+        """Получить дерево хостов → список SiteNode.
+
+        Returns:
+            Словарь {host: [SiteNode, ...]}.
+        """
+        return self._sitemap.get_tree()
+
+    def get_hosts(self) -> list[str]:
+        """Получить список всех хостов в карте сайта."""
+        return self._sitemap.get_hosts()
+
+    def get_paths(self, host: str) -> list[SiteNode]:
+        """Получить список SiteNode для указанного хоста.
+
+        Args:
+            host: Имя хоста (например, "example.com").
+
+        Returns:
+            Список SiteNode с путями, найденными для этого хоста.
+        """
+        return self._sitemap.get_paths(host)
+
+    async def set_in_scope(self, host: str, in_scope: bool) -> None:
+        """Задать scope-флаг для хоста.
+
+        Args:
+            host: Имя хоста.
+            in_scope: True — хост в scope, False — вне scope.
+        """
+        self._sitemap.set_in_scope(host, in_scope)
+
+    async def get_scope(self) -> list[str]:
+        """Получить список хостов, находящихся в scope.
+
+        Returns:
+            Список строк — имён хостов с флагом in_scope=True.
+        """
+        return self._sitemap.get_scope()
+
+    async def clear(self) -> None:
+        """Очистить всю карту сайта (все хосты и пути)."""
+        self._sitemap.clear()
+
+    async def export_json(self, path: str) -> None:
+        """Экспортировать карту в JSON-файл."""
+        data = self._sitemap.export_json()
+        Path(path).write_text(json.dumps(data, indent=2, default=str), encoding="utf-8")
+        logger.info("SiteMap exported to %s", path)
+
+    # ── Project persistence ────────────────────────────────────────────────────
+
+    def export_project_data(self) -> dict:
+        """Экспортировать SiteMap в сериализуемый dict для сохранения проекта."""
+        return {"sitemap": self._sitemap.export_json()}
+
+    def import_project_data(self, data: dict) -> int:
+        """Импортировать SiteMap из загруженного dict проекта.
+
+        Args:
+            data: Блок "target" из project.json ({"sitemap": {...}}).
+
+        Returns:
+            Количество загруженных узлов.
+        """
+        from pentool.modules.target import SiteNode
+        sitemap_data = data.get("sitemap", {})
+        self._sitemap.clear()
+        loaded = 0
+        for host, nodes in sitemap_data.items():
+            for node_dict in nodes:
+                try:
+                    node = SiteNode.from_dict(node_dict)
+                    self._sitemap._nodes.setdefault(host, {})[node.path] = node
+                    loaded += 1
+                except Exception as exc:
+                    logger.warning("TargetAPI.import_project_data: skip node: %s", exc)
+        return loaded

pentool/cli/__init__.py

@@ -0,0 +1 @@
+"""Пакет cli: команды Click."""