splitagent 0.0.3__py3-none-any.whl

splitagent/tools/exploit.py

@@ -0,0 +1,318 @@
+"""Controlled exploitation probes.
+
+Every probe here is non-destructive: it injects benign markers and inspects
+the response for evidence. No tool deletes data, writes files or launches a
+shell on the target. When ``safe_mode`` is enabled the probes stop at the
+detection stage and never chain into exploitation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+import httpx
+
+from splitagent.tools.base import Tool, ToolContext
+from splitagent.tools.http_pool import get_client
+
+SQL_ERRORS = (
+    "you have an error in your sql syntax",
+    "warning: mysql",
+    "unclosed quotation mark",
+    "quoted string not properly terminated",
+    "sqlstate",
+    "pg_query",
+    "psql:",
+    "syntax error at or near",
+    "ora-01756",
+    "ora-00933",
+    "microsoft odbc",
+    "odbc sql server driver",
+    "native client",
+    "sqlite3::",
+    "jdbc",
+    "doctrine\\query",
+)
+
+CANARY = "splitagentcanary"
+XSS_MARKER = f"<svg/onload=alert('{CANARY}')>"
+CMD_MARKER = f"splitagent_{CANARY}"
+TRAVERSAL_PAYLOADS = (
+    "../../../../../../etc/passwd",
+    "..%2f..%2f..%2f..%2fetc%2fpasswd",
+    "....//....//....//etc/passwd",
+    "/etc/passwd",
+)
+
+
+def _inject(url: str, parameter: str, value: str) -> str:
+    parsed = urlparse(url)
+    query = dict(parse_qsl(parsed.query, keep_blank_values=True))
+    query[parameter] = value
+    return urlunparse(parsed._replace(query=urlencode(query)))
+
+
+async def _send(
+    ctx: ToolContext, url: str, method: str = "GET", data: dict[str, Any] | None = None
+) -> httpx.Response:
+    ctx.check_scope(url)
+    client = await get_client(follow=False, verify=False, timeout=15.0, headers=ctx.auth_headers())
+    return await client.request(method.upper(), url, data=data)
+
+
+def _evidence(response: httpx.Response, needles: list[str]) -> str:
+    body = response.text[:20000]
+    for needle in needles:
+        index = body.lower().find(needle.lower())
+        if index >= 0:
+            start = max(0, index - 120)
+            return body[start : index + len(needle) + 120].replace("\n", " ")
+    return body[:400].replace("\n", " ")
+
+
+async def test_sqli(
+    ctx: ToolContext, url: str, parameter: str, method: str = "GET"
+) -> dict[str, Any]:
+    baseline = await _send(ctx, url, method)
+    findings: list[str] = []
+    for payload in ("'", '"', "')", "' OR '1'='1"):
+        probe_url = _inject(url, parameter, payload)
+        response = await _send(ctx, probe_url, method)
+        body = response.text.lower()
+        for signature in SQL_ERRORS:
+            if signature in body:
+                findings.append(f"payload={payload!r} signature={signature!r}")
+                break
+    vulnerable = bool(findings)
+    return {
+        "vulnerable": vulnerable,
+        "test": "sql_injection",
+        "parameter": parameter,
+        "baseline_status": baseline.status_code,
+        "evidence": findings or "no SQL error signatures observed",
+        "confidence": "high" if vulnerable else "low",
+    }
+
+
+async def test_xss(
+    ctx: ToolContext, url: str, parameter: str, method: str = "GET"
+) -> dict[str, Any]:
+    probe_url = _inject(url, parameter, XSS_MARKER)
+    response = await _send(ctx, probe_url, method)
+    reflected = XSS_MARKER.lower() in response.text.lower()
+    content_type = response.headers.get("content-type", "")
+    html_context = "html" in content_type.lower() or "<html" in response.text[:500].lower()
+    return {
+        "vulnerable": bool(reflected and html_context),
+        "test": "reflected_xss",
+        "parameter": parameter,
+        "reflected": reflected,
+        "content_type": content_type,
+        "evidence": _evidence(response, [CANARY]) if reflected else "marker not reflected",
+        "confidence": "high" if (reflected and html_context) else "low",
+    }
+
+
+async def test_path_traversal(
+    ctx: ToolContext, url: str, parameter: str, method: str = "GET"
+) -> dict[str, Any]:
+    for payload in TRAVERSAL_PAYLOADS:
+        probe_url = _inject(url, parameter, payload)
+        response = await _send(ctx, probe_url, method)
+        if "root:x:0:0" in response.text or "daemon:x:" in response.text:
+            return {
+                "vulnerable": True,
+                "test": "path_traversal",
+                "parameter": parameter,
+                "payload": payload,
+                "evidence": _evidence(response, ["root:x:0:0", "daemon:x:"]),
+                "confidence": "high",
+            }
+    return {
+        "vulnerable": False,
+        "test": "path_traversal",
+        "parameter": parameter,
+        "evidence": "no file-disclosure signature observed",
+        "confidence": "low",
+    }
+
+
+async def test_open_redirect(
+    ctx: ToolContext, url: str, parameter: str, method: str = "GET"
+) -> dict[str, Any]:
+    canary_url = "https://example.com/splitagent-redirect-canary"
+    probe_url = _inject(url, parameter, canary_url)
+    response = await _send(ctx, probe_url, method)
+    location = response.headers.get("location", "")
+    redirected = "example.com/splitagent-redirect-canary" in location
+    return {
+        "vulnerable": redirected,
+        "test": "open_redirect",
+        "parameter": parameter,
+        "status": response.status_code,
+        "location": location,
+        "evidence": f"Location: {location}" if redirected else "no external redirect",
+        "confidence": "high" if redirected else "low",
+    }
+
+
+async def test_command_injection(
+    ctx: ToolContext, url: str, parameter: str, method: str = "GET"
+) -> dict[str, Any]:
+    payload = f";echo {CMD_MARKER}"
+    probe_url = _inject(url, parameter, payload)
+    response = await _send(ctx, probe_url, method)
+    injected = CMD_MARKER in response.text
+    return {
+        "vulnerable": injected,
+        "test": "command_injection",
+        "parameter": parameter,
+        "evidence": _evidence(response, [CMD_MARKER]) if injected else "marker not found",
+        "confidence": "high" if injected else "low",
+    }
+
+
+async def test_cors(ctx: ToolContext, url: str) -> dict[str, Any]:
+    origin = "https://evil.splitagent.test"
+    ctx.check_scope(url)
+    client = await get_client(follow=False, verify=False, timeout=10.0, headers=ctx.auth_headers())
+    response = await client.get(url, headers={"Origin": origin})
+    allow_origin = response.headers.get("access-control-allow-origin", "")
+    allow_creds = response.headers.get("access-control-allow-credentials", "")
+    vulnerable = allow_origin in ("*", origin)
+    return {
+        "vulnerable": vulnerable,
+        "test": "cors_misconfiguration",
+        "allow_origin": allow_origin,
+        "allow_credentials": allow_creds,
+        "evidence": f"ACAO={allow_origin!r} ACAC={allow_creds!r}",
+        "confidence": "high" if vulnerable else "low",
+    }
+
+
+async def test_http_methods(ctx: ToolContext, url: str) -> dict[str, Any]:
+    ctx.check_scope(url)
+    allowed: list[str] = []
+    client = await get_client(follow=False, verify=False, timeout=10.0, headers=ctx.auth_headers())
+    for method in ("GET", "POST", "PUT", "DELETE", "TRACE", "OPTIONS", "PATCH"):
+        try:
+            response = await client.request(method, url)
+        except httpx.HTTPError:
+            continue
+        if response.status_code < 400 or response.status_code == 405:
+            allowed.append(f"{method}:{response.status_code}")
+    dangerous = [m for m in allowed if m.split(":")[0] in ("PUT", "DELETE", "TRACE")]
+    return {
+        "vulnerable": bool(dangerous),
+        "test": "http_methods",
+        "allowed": allowed,
+        "dangerous": dangerous,
+        "evidence": ", ".join(allowed),
+        "confidence": "medium" if dangerous else "low",
+    }
+
+
+async def test_directory_listing(ctx: ToolContext, url: str) -> dict[str, Any]:
+    response = await _send(ctx, url)
+    body = response.text.lower()
+    listing = "index of /" in body and "<a href=" in body
+    return {
+        "vulnerable": listing,
+        "test": "directory_listing",
+        "status": response.status_code,
+        "evidence": _evidence(response, ["index of /"]) if listing else "no listing",
+        "confidence": "high" if listing else "low",
+    }
+
+
+def red_exploit_tools(ctx: ToolContext) -> list[Tool]:
+    def _params(extra: dict[str, Any]) -> dict[str, Any]:
+        base = {
+            "url": {"type": "string"},
+            "parameter": {"type": "string"},
+            "method": {"type": "string", "default": "GET"},
+        }
+        base.update(extra)
+        return {"type": "object", "properties": base, "required": ["url", "parameter"]}
+
+    return [
+        Tool(
+            name="test_sql_injection",
+            description=(
+                "Non-destructive SQL injection detection: injects quote payloads "
+                "and looks for database error signatures."
+            ),
+            parameters=_params({}),
+            func=lambda url, parameter, method="GET": test_sqli(ctx, url, parameter, method),
+            scope="red",
+        ),
+        Tool(
+            name="test_xss",
+            description=("Reflected XSS detection using a unique marker in the parameter."),
+            parameters=_params({}),
+            func=lambda url, parameter, method="GET": test_xss(ctx, url, parameter, method),
+            scope="red",
+        ),
+        Tool(
+            name="test_path_traversal",
+            description="Detect file disclosure via path traversal payloads.",
+            parameters=_params({}),
+            func=lambda url, parameter, method="GET": test_path_traversal(
+                ctx, url, parameter, method
+            ),
+            scope="red",
+        ),
+        Tool(
+            name="test_open_redirect",
+            description="Detect open redirect by injecting an external canary URL.",
+            parameters=_params({}),
+            func=lambda url, parameter, method="GET": test_open_redirect(
+                ctx, url, parameter, method
+            ),
+            scope="red",
+        ),
+        Tool(
+            name="test_command_injection",
+            description=("Detect OS command injection using a benign echo marker."),
+            parameters=_params({}),
+            func=lambda url, parameter, method="GET": test_command_injection(
+                ctx, url, parameter, method
+            ),
+            scope="red",
+            dangerous=True,
+        ),
+        Tool(
+            name="test_cors",
+            description="Check for permissive CORS configuration.",
+            parameters={
+                "type": "object",
+                "properties": {"url": {"type": "string"}},
+                "required": ["url"],
+            },
+            func=lambda url: test_cors(ctx, url),
+            scope="red",
+        ),
+        Tool(
+            name="test_http_methods",
+            description="Enumerate supported HTTP methods and flag dangerous ones.",
+            parameters={
+                "type": "object",
+                "properties": {"url": {"type": "string"}},
+                "required": ["url"],
+            },
+            func=lambda url: test_http_methods(ctx, url),
+            scope="red",
+        ),
+        Tool(
+            name="test_directory_listing",
+            description="Check whether a directory exposes an automatic index.",
+            parameters={
+                "type": "object",
+                "properties": {"url": {"type": "string"}},
+                "required": ["url"],
+            },
+            func=lambda url: test_directory_listing(ctx, url),
+            scope="red",
+        ),
+    ]

splitagent/tools/http_pool.py

@@ -0,0 +1,109 @@
+"""A shared HTTP connection pool for the reconnaissance tools.
+
+Every web tool used to build its own ``httpx.AsyncClient`` per call, which
+means a fresh TCP handshake, a fresh TLS handshake and a fresh DNS lookup for
+every single request. During a crawl or a path sweep that dominates the wall
+clock. One client with keep-alive removes it entirely.
+
+The pool is keyed by the flags that affect connection reuse (redirect and
+verification policy), created lazily and closed by the engine at the end of a
+run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+_CLIENTS: dict[tuple[Any, ...], httpx.AsyncClient] = {}
+_LOCK = asyncio.Lock()
+
+DEFAULT_LIMITS = httpx.Limits(
+    max_connections=64,
+    max_keepalive_connections=32,
+    keepalive_expiry=30.0,
+)
+
+
+def _http2_available() -> bool:
+    """HTTP/2 needs the optional ``h2`` package; degrade silently without it."""
+    try:
+        import h2  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+HTTP2 = _http2_available()
+
+
+def _key(
+    follow: bool, verify: bool, timeout: float, headers: dict[str, str] | None
+) -> tuple[Any, ...]:
+    # Headers participate in the key so authenticated and anonymous traffic
+    # never share a connection pool (and therefore never leak a cookie).
+    header_key = tuple(sorted((headers or {}).items()))
+    return (follow, verify, timeout, header_key)
+
+
+async def get_client(
+    *,
+    follow: bool = True,
+    verify: bool = False,
+    timeout: float = 15.0,
+    headers: dict[str, str] | None = None,
+) -> httpx.AsyncClient:
+    """Return a pooled client for the given transport policy.
+
+    The headers become the client's defaults. Callers must NOT pass the same
+    headers per-request: httpx appends request headers to the client defaults,
+    which would send each one twice and the server would reject the request as
+    having conflicting headers. Use :func:`request_headers` to get the extras
+    that still need to be added (a per-call override such as ``Origin``).
+    """
+    key = _key(follow, verify, timeout, headers)
+    client = _CLIENTS.get(key)
+    if client is not None and not client.is_closed:
+        return client
+    async with _LOCK:
+        client = _CLIENTS.get(key)
+        if client is not None and not client.is_closed:
+            return client
+        client = httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=follow,
+            verify=verify,
+            headers=dict(headers or {}),
+            limits=DEFAULT_LIMITS,
+            http2=HTTP2,
+        )
+        _CLIENTS[key] = client
+        return client
+
+
+def request_headers(
+    client: httpx.AsyncClient, overrides: dict[str, str] | None = None
+) -> dict[str, str]:
+    """Return only the headers a caller must add on top of the client defaults.
+
+    Anything already present as a client default is dropped, so a request never
+    carries the same header twice.
+    """
+    if not overrides:
+        return {}
+    defaults = {name.lower() for name in client.headers}
+    return {name: value for name, value in overrides.items() if name.lower() not in defaults}
+
+
+async def aclose_all() -> None:
+    """Close every pooled client (called when a run finishes)."""
+    async with _LOCK:
+        clients = list(_CLIENTS.values())
+        _CLIENTS.clear()
+    for client in clients:
+        try:
+            await client.aclose()
+        except Exception:
+            pass