shadowcat 2.0.0__py3-none-any.whl

backend/tools/dirbrute_tool.py

@@ -0,0 +1,304 @@
+"""Directory / file brute-force tool — discovers unlisted paths.
+
+Tries a built-in wordlist of ~180 high-value paths (admin panels, API docs,
+config files, backup files, framework debug endpoints) and reports any that
+return HTTP 200, 301, 302, 401, or 403.  Skips everything else.
+
+Registered in GeneralDastMode so the agent can call it by name.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+_WORDLIST: list[str] = [
+    # Admin panels
+    "admin",
+    "administrator",
+    "admin/login",
+    "admin/dashboard",
+    "manage",
+    "management",
+    "backend",
+    "backoffice",
+    "cp",
+    "cpanel",
+    "dashboard",
+    "panel",
+    # API
+    "api",
+    "api/v1",
+    "api/v2",
+    "api/v3",
+    "api/v4",
+    "rest",
+    "graphql",
+    "gql",
+    "rpc",
+    "swagger",
+    "swagger-ui",
+    "swagger.json",
+    "openapi.json",
+    "api-docs",
+    "api/swagger",
+    "api/docs",
+    # Debug / dev
+    "debug",
+    "console",
+    "shell",
+    "test",
+    "dev",
+    "phpinfo.php",
+    "info.php",
+    # Secrets / config
+    ".env",
+    ".env.local",
+    ".env.production",
+    "config.php",
+    "config.json",
+    "config.yml",
+    "config.yaml",
+    ".git/config",
+    ".git/HEAD",
+    ".htaccess",
+    ".htpasswd",
+    "web.config",
+    "package.json",
+    # Auth
+    "login",
+    "signin",
+    "auth",
+    "authentication",
+    "logout",
+    "register",
+    "signup",
+    "forgot-password",
+    "reset-password",
+    "oauth",
+    "oauth2",
+    "sso",
+    # Users / profile
+    "user",
+    "users",
+    "profile",
+    "account",
+    "accounts",
+    "me",
+    # Files
+    "upload",
+    "uploads",
+    "files",
+    "media",
+    "download",
+    "downloads",
+    "static",
+    "assets",
+    "public",
+    # Health / metrics (cloud-native)
+    "health",
+    "healthz",
+    "health-check",
+    "ping",
+    "status",
+    "actuator",
+    "actuator/health",
+    "actuator/info",
+    "actuator/metrics",
+    "actuator/env",
+    "metrics",
+    "prometheus",
+    # Database admin
+    "phpMyAdmin",
+    "phpmyadmin",
+    "pma",
+    "adminer",
+    "adminer.php",
+    "server-status",
+    "server-info",
+    # WordPress
+    "wp-admin",
+    "wp-login.php",
+    "wp-json",
+    "xmlrpc.php",
+    "wp-content/uploads",
+    "wp-json/wp/v2/users",
+    # Framework-specific
+    "telescope",
+    "horizon",  # Laravel
+    "_debug",
+    "_debug/toolbar",  # Django debug toolbar
+    "rails/info",
+    "rails/info/routes",  # Rails
+    # Backups
+    "backup",
+    "backup.sql",
+    "database.sql",
+    "dump.sql",
+    "backup.zip",
+    "backup.tar.gz",
+    "old",
+    "archive",
+    # SEO / well-known
+    "robots.txt",
+    "sitemap.xml",
+    "sitemap_index.xml",
+    "security.txt",
+    ".well-known/security.txt",
+    "humans.txt",
+    # Docs
+    "docs",
+    "documentation",
+    "changelog",
+    "version",
+    "version.txt",
+    # Install / setup
+    "setup",
+    "setup.php",
+    "install",
+    "install.php",
+    "update.php",
+    "cgi-bin",
+    # Logs / temp
+    "logs",
+    "log",
+    "tmp",
+    "temp",
+    "cache",
+    # Common REST resources
+    "posts",
+    "articles",
+    "products",
+    "items",
+    "orders",
+    "payments",
+    "billing",
+    "notifications",
+    "messages",
+    "comments",
+    # Java Spring Boot
+    "actuator/beans",
+    "actuator/mappings",
+    "actuator/configprops",
+    # Misc
+    "private",
+    "secret",
+    "secrets",
+    "credentials",
+    "info",
+    "about",
+]
+
+_INTERESTING_STATUSES = frozenset({200, 301, 302, 401, 403})
+
+
+class DirBruteTool:
+    """Async directory brute-force over a built-in wordlist.
+
+    Uses N concurrent workers (default 20) that each probe one path at a time.
+    The wordlist is partitioned statically across workers to avoid queue
+    complexity since paths are never added dynamically.
+    """
+
+    name = "dir_bruteforce"
+
+    def __init__(
+        self,
+        *,
+        workers: int = 20,
+        timeout: float = 10.0,
+        rate_limit_ms: int = 0,
+    ) -> None:
+        self._workers = workers
+        self._timeout = timeout
+        self._rate_limit_ms = rate_limit_ms
+
+    def schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Brute-force ~180 common directory and file paths on the target to "
+                    "discover hidden attack surface: admin panels, API docs, config files, "
+                    "backup files, and framework debug endpoints. "
+                    "Reports paths that return HTTP 200 (accessible), 401/403 (exists but "
+                    "protected), or 301/302 (redirect). Use this at the start of an assessment "
+                    "before probing individual endpoints."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "rationale": {
+                            "type": "string",
+                            "description": "Why you are running this brute-force scan now.",
+                        },
+                        "base_url": {
+                            "type": "string",
+                            "description": "Base URL to probe (e.g. 'https://target.com'). "
+                            "Paths are appended: base_url/admin, base_url/.env, etc.",
+                        },
+                    },
+                    "required": ["rationale", "base_url"],
+                },
+            },
+        }
+
+    async def run(self, **kwargs: Any) -> dict[str, Any]:
+        base_url = (kwargs.get("base_url") or "").rstrip("/")
+        if not base_url:
+            return {"error": "missing_parameter", "detail": "base_url is required"}
+
+        found: list[dict[str, Any]] = []
+        result_lock = asyncio.Lock()
+
+        # Partition wordlist across workers.
+        chunk_size = max(1, (len(_WORDLIST) + self._workers - 1) // self._workers)
+        chunks = [_WORDLIST[i : i + chunk_size] for i in range(0, len(_WORDLIST), chunk_size)]
+
+        async def _probe_batch(client: httpx.AsyncClient, paths: list[str]) -> None:
+            for path in paths:
+                if self._rate_limit_ms > 0:
+                    await asyncio.sleep(self._rate_limit_ms / 1000)
+                url = f"{base_url}/{path}"
+                try:
+                    resp = await client.get(url, follow_redirects=False, timeout=self._timeout)
+                    if resp.status_code in _INTERESTING_STATUSES:
+                        ct = resp.headers.get("content-type", "")
+                        preview = resp.text[:300] if resp.text else ""
+                        async with result_lock:
+                            found.append(
+                                {
+                                    "path": path,
+                                    "url": url,
+                                    "status": resp.status_code,
+                                    "content_type": ct,
+                                    "body_preview": preview,
+                                }
+                            )
+                        log.info("DirBrute: %s → %d", url, resp.status_code)
+                except Exception as exc:
+                    log.debug("DirBrute error %s: %s", url, exc)
+
+        async with httpx.AsyncClient(
+            verify=False,
+            follow_redirects=False,
+            headers={
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+                "Accept": "text/html,application/xhtml+xml,*/*;q=0.8",
+            },
+        ) as client:
+            await asyncio.gather(*[_probe_batch(client, chunk) for chunk in chunks])
+
+        found.sort(key=lambda x: (x["status"], x["path"]))
+        return {
+            "total_paths_tested": len(_WORDLIST),
+            "found_count": len(found),
+            "found_paths": found,
+            "note": "200=accessible, 401/403=exists-but-protected, 301/302=redirected.",
+        }

backend/tools/general_report_tool.py

@@ -0,0 +1,135 @@
+"""``report_finding`` tool for General DAST mode.
+
+Same guarantees as the Enterprise variant but with a more flexible evidence
+schema: a single ``probe`` request_id is the minimum (no mandatory
+``baseline`` / ``cross_access`` pair required for IDOR). The agent still cannot
+add fields or declare a verdict — the schema forbids both.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+
+from backend.schemas.api import GeneralFindingReport
+from backend.verification.evidence_store import EvidenceStore
+
+
+class ReportGeneralFindingTool:
+    """Validate, ground, and record a General DAST candidate finding."""
+
+    name = "report_finding"
+
+    def __init__(self, evidence_store: EvidenceStore) -> None:
+        self._evidence = evidence_store
+        self._findings: list[tuple[str, GeneralFindingReport]] = []
+        self._counter = 0
+
+    def schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Report a CANDIDATE vulnerability finding for deterministic verification. "
+                    "You do NOT decide whether it is real — a separate oracle renders the verdict. "
+                    "Every request_id you cite MUST come from an http_request you actually made this session."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "title": {
+                            "type": "string",
+                            "description": "Short title, e.g. 'Reflected XSS on GET /search?q='.",
+                        },
+                        "hypothesis": {
+                            "type": "string",
+                            "description": "The specific vulnerability hypothesis being tested.",
+                        },
+                        "vuln_class": {
+                            "type": "object",
+                            "properties": {
+                                "cwe": {
+                                    "type": "string",
+                                    "description": "CWE identifier, e.g. 'CWE-89' for SQLi.",
+                                },
+                                "owasp": {
+                                    "type": "string",
+                                    "description": "OWASP Top 10 category, e.g. 'A03:2021'.",
+                                },
+                            },
+                            "required": ["cwe"],
+                        },
+                        "evidence": {
+                            "type": "object",
+                            "properties": {
+                                "probe": {
+                                    "type": "string",
+                                    "description": "request_id of the test request that elicited the anomalous response.",
+                                },
+                                "baseline": {
+                                    "type": "string",
+                                    "description": "request_id of a benign baseline request (same endpoint, safe input).",
+                                },
+                                "controls": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": "request_ids of additional variant requests.",
+                                },
+                            },
+                            "required": ["probe"],
+                        },
+                        "payload": {
+                            "type": "string",
+                            "description": "The exact test payload used (e.g. SQLi string, XSS vector, traversal path).",
+                        },
+                        "rationale": {
+                            "type": "string",
+                            "description": "Concise factual reasoning. NOT a verdict — just explain what you observed.",
+                        },
+                    },
+                    "required": ["title", "hypothesis", "vuln_class", "evidence"],
+                },
+            },
+        }
+
+    async def run(self, **kwargs: Any) -> dict[str, Any]:
+        """Validate, ground, and record a candidate finding."""
+        try:
+            report = GeneralFindingReport.model_validate(kwargs)
+        except ValidationError as exc:
+            return {
+                "error": "invalid_finding",
+                "detail": exc.errors(include_url=False, include_context=False),
+                "note": "Fix the fields and resubmit. You cannot add fields or declare a verdict.",
+            }
+
+        cited = report.cited_request_ids()
+        missing = [rid for rid in cited if not self._evidence.has(rid)]
+        if missing:
+            return {
+                "error": "unknown_request_id",
+                "missing": missing,
+                "note": (
+                    "Each request_id must come from an http_request you actually made. "
+                    "Make the request first, then cite its request_id."
+                ),
+            }
+
+        self._counter += 1
+        finding_id = f"f{self._counter}"
+        self._findings.append((finding_id, report))
+        return {
+            "finding_id": finding_id,
+            "status": "pending_verification",
+            "cited_request_ids": cited,
+            "note": (
+                "Recorded as a candidate. The oracle renders the verdict — "
+                "you have not confirmed anything."
+            ),
+        }
+
+    @property
+    def findings(self) -> list[tuple[str, GeneralFindingReport]]:
+        return list(self._findings)