nat-engine 1__py3-none-any.whl

mannf/product/ingestors/curl_ingestor.py

@@ -0,0 +1,1019 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""cURL/Batch Import ingestor plugin.
+
+Parses cURL commands (individual or batch files containing multiple cURL
+commands) and extracts endpoints, request details, and test case intents.
+
+Common sources:
+* Browser dev tools "Copy as cURL"
+* Postman "Copy as cURL" exports
+* API documentation cURL examples
+* Shell history / saved cURL scripts
+
+Supported cURL flags
+--------------------
+``-X`` / ``--request``
+    HTTP method (default ``GET``, or ``POST`` when ``-d`` / ``--data`` is present).
+``-H`` / ``--header``
+    Request header (repeatable).
+``-d`` / ``--data`` / ``--data-raw`` / ``--data-binary`` / ``--data-urlencode``
+    Request body.
+``-F`` / ``--form``
+    Multipart form field.
+``-u`` / ``--user``
+    Basic auth (``user:password``).
+``-k`` / ``--insecure``
+    Skip TLS verification (stored as metadata).
+``-L`` / ``--location``
+    Follow redirects (stored as metadata).
+``--compressed``
+    Accept compressed response (stored as metadata).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shlex
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse, parse_qs, urlencode, urljoin
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Headers that indicate authentication requirements
+_AUTH_HEADERS: frozenset[str] = frozenset({
+    "authorization",
+    "cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-access-token",
+    "x-csrf-token",
+})
+
+# Mutation HTTP methods
+_MUTATION_METHODS: frozenset[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+# Auth keywords in path
+_AUTH_PATH_KEYWORDS: tuple[str, ...] = (
+    "/auth", "/login", "/token", "/logout", "/password",
+    "/oauth", "/signin", "/signup", "/register",
+)
+
+# ---------------------------------------------------------------------------
+# cURL argument parsing
+# ---------------------------------------------------------------------------
+
+
+def _split_curl_commands(text: str) -> list[str]:
+    """Split *text* into individual cURL command strings.
+
+    Handles:
+    * Line continuation via ``\\`` at end of line (including Windows ``\\r\\n``).
+    * Comment lines starting with ``#``.
+    * Empty lines between commands.
+    * Mixed single-line and multi-line cURL commands.
+
+    Parameters
+    ----------
+    text:
+        Raw content that may contain one or more cURL commands.
+
+    Returns
+    -------
+    list[str]
+        List of raw cURL command strings, each on a single (joined) line.
+    """
+    # Normalise Windows line endings
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+
+    # First, join lines that end with backslash (line continuation)
+    joined_lines: list[str] = []
+    current = ""
+    for line in text.split("\n"):
+        stripped = line.rstrip()
+        if stripped.endswith("\\"):
+            # Remove the trailing backslash and accumulate
+            current += stripped[:-1] + " "
+        else:
+            current += stripped
+            joined_lines.append(current)
+            current = ""
+    if current.strip():
+        joined_lines.append(current)
+
+    # Now split into individual curl command blocks
+    commands: list[str] = []
+    current_cmd = ""
+    for line in joined_lines:
+        stripped = line.strip()
+        # Skip comment lines and empty lines
+        if not stripped or stripped.startswith("#"):
+            if current_cmd.strip():
+                commands.append(current_cmd.strip())
+                current_cmd = ""
+            continue
+        # If this line starts a new curl command and we already have one
+        if re.match(r"^curl\s", stripped, re.IGNORECASE):
+            if current_cmd.strip():
+                commands.append(current_cmd.strip())
+            current_cmd = stripped
+        else:
+            # Continuation of previous command (shouldn't happen after join, but be safe)
+            current_cmd = (current_cmd + " " + stripped).strip()
+
+    if current_cmd.strip():
+        commands.append(current_cmd.strip())
+
+    return [cmd for cmd in commands if cmd.strip()]
+
+
+def _tokenise(command: str) -> list[str]:
+    """Split a cURL command string into tokens, handling quoted strings.
+
+    Uses :mod:`shlex` with POSIX mode for robust handling of quoted strings,
+    escaped characters, and spaces within arguments.
+
+    Parameters
+    ----------
+    command:
+        Single-line cURL command string.
+
+    Returns
+    -------
+    list[str]
+        List of tokens.
+
+    Raises
+    ------
+    ValueError
+        If the command string cannot be tokenised (e.g., unmatched quotes).
+    """
+    try:
+        lex = shlex.shlex(command, posix=True)
+        lex.whitespace_split = True
+        lex.whitespace = " \t"
+        return list(lex)
+    except ValueError:
+        # Fallback: basic split on whitespace, stripping surrounding quotes
+        tokens: list[str] = []
+        for part in re.split(r"\s+", command):
+            if (part.startswith('"') and part.endswith('"')) or \
+               (part.startswith("'") and part.endswith("'")):
+                part = part[1:-1]
+            tokens.append(part)
+        return [t for t in tokens if t]
+
+
+def _parse_curl_command(command: str) -> dict[str, Any]:
+    """Parse a single cURL command string into a structured dict.
+
+    Parameters
+    ----------
+    command:
+        Raw cURL command string (single line, after joining continuations).
+
+    Returns
+    -------
+    dict
+        Parsed fields:
+
+        * ``url`` (str | None)
+        * ``method`` (str)
+        * ``headers`` (list[tuple[str, str]])
+        * ``body`` (str | None)
+        * ``form_data`` (list[str])
+        * ``basic_auth`` (str | None) — raw ``user:password`` string
+        * ``insecure`` (bool)
+        * ``follow_redirects`` (bool)
+        * ``compressed`` (bool)
+        * ``errors`` (list[str])
+    """
+    result: dict[str, Any] = {
+        "url": None,
+        "method": None,  # None means "not specified yet"
+        "headers": [],
+        "body": None,
+        "form_data": [],
+        "basic_auth": None,
+        "insecure": False,
+        "follow_redirects": False,
+        "compressed": False,
+        "errors": [],
+    }
+
+    try:
+        tokens = _tokenise(command)
+    except ValueError as exc:
+        result["errors"].append(f"Failed to tokenise command: {exc}")
+        return result
+
+    if not tokens:
+        result["errors"].append("Empty command.")
+        return result
+
+    # Strip leading 'curl' token (case-insensitive)
+    idx = 0
+    if tokens[idx].lower() == "curl":
+        idx += 1
+
+    def _next_arg(i: int) -> tuple[str | None, int]:
+        """Return (tokens[i+1], i+2) or (None, i+1) if out of bounds."""
+        if i + 1 < len(tokens):
+            return tokens[i + 1], i + 2
+        return None, i + 1
+
+    while idx < len(tokens):
+        tok = tokens[idx]
+
+        # --- Short flags that take a value ---
+        if tok in ("-X", "--request"):
+            val, idx = _next_arg(idx)
+            if val:
+                result["method"] = val.upper()
+            else:
+                result["errors"].append(f"Flag {tok} requires a value.")
+
+        elif tok in ("-H", "--header"):
+            val, idx = _next_arg(idx)
+            if val:
+                # Split "Name: Value" into (name, value)
+                colon_pos = val.find(":")
+                if colon_pos >= 0:
+                    h_name = val[:colon_pos].strip()
+                    h_val = val[colon_pos + 1:].strip()
+                else:
+                    h_name = val
+                    h_val = ""
+                result["headers"].append((h_name, h_val))
+            else:
+                result["errors"].append(f"Flag {tok} requires a value.")
+
+        elif tok in ("-d", "--data", "--data-raw", "--data-binary", "--data-urlencode"):
+            val, idx = _next_arg(idx)
+            if val is not None:
+                if result["body"] is None:
+                    result["body"] = val
+                else:
+                    # Multiple -d flags: concatenate with &
+                    result["body"] = result["body"] + "&" + val
+            else:
+                result["errors"].append(f"Flag {tok} requires a value.")
+
+        elif tok in ("-F", "--form"):
+            val, idx = _next_arg(idx)
+            if val is not None:
+                result["form_data"].append(val)
+            else:
+                result["errors"].append(f"Flag {tok} requires a value.")
+
+        elif tok in ("-u", "--user"):
+            val, idx = _next_arg(idx)
+            if val:
+                result["basic_auth"] = val
+            else:
+                result["errors"].append(f"Flag {tok} requires a value.")
+
+        # --- Boolean flags ---
+        elif tok in ("-k", "--insecure"):
+            result["insecure"] = True
+            idx += 1
+
+        elif tok in ("-L", "--location"):
+            result["follow_redirects"] = True
+            idx += 1
+
+        elif tok == "--compressed":
+            result["compressed"] = True
+            idx += 1
+
+        # --- Flags to ignore (common curl flags that don't affect the request model) ---
+        elif tok in ("-s", "--silent", "-S", "--show-error", "-v", "--verbose",
+                     "-i", "--include", "-I", "--head", "-o", "--output",
+                     "-w", "--write-out", "--connect-timeout", "--max-time",
+                     "-m", "--retry", "--retry-delay", "--retry-max-time",
+                     "--http1.0", "--http1.1", "--http2", "--http3",
+                     "--tlsv1", "--tlsv1.0", "--tlsv1.1", "--tlsv1.2", "--tlsv1.3",
+                     "--cacert", "--capath", "--cert", "--key", "--pass",
+                     "--ssl", "--ssl-reqd"):
+            # Some of these take a value, some don't — try to skip intelligently
+            flags_with_value = {
+                "-o", "--output", "-w", "--write-out",
+                "--connect-timeout", "--max-time", "-m",
+                "--retry", "--retry-delay", "--retry-max-time",
+                "--cacert", "--capath", "--cert", "--key", "--pass",
+            }
+            if tok in flags_with_value:
+                _, idx = _next_arg(idx)
+            else:
+                idx += 1
+
+        # --- Long flags with = syntax: e.g. --header="Content-Type: application/json" ---
+        elif tok.startswith("--") and "=" in tok:
+            flag, _, value = tok.partition("=")
+            # Re-inject as separate token pair for re-processing
+            tokens = tokens[:idx] + [flag, value] + tokens[idx + 1:]
+            # Don't advance idx — re-process from the same position
+
+        # --- Short flag with no space: e.g. -XPOST ---
+        elif re.match(r"^-[A-Za-z].+", tok) and not tok.startswith("--"):
+            short_flag = tok[:2]
+            remainder = tok[2:]
+            tokens = tokens[:idx] + [short_flag, remainder] + tokens[idx + 1:]
+            # Don't advance — re-process
+
+        # --- URL (not a flag) ---
+        elif not tok.startswith("-"):
+            # Could be the URL; strip surrounding quotes if any
+            url_candidate = tok
+            if (url_candidate.startswith('"') and url_candidate.endswith('"')) or \
+               (url_candidate.startswith("'") and url_candidate.endswith("'")):
+                url_candidate = url_candidate[1:-1]
+            if result["url"] is None:
+                result["url"] = url_candidate
+            # If we already have a URL, this might be a positional arg to ignore
+            idx += 1
+
+        else:
+            # Unknown flag — skip it (and its potential value if it looks like a value flag)
+            logger.debug("CurlIngestor: unknown flag %r — skipping.", tok)
+            idx += 1
+
+    # --- Infer method from context ---
+    if result["method"] is None:
+        if result["body"] is not None or result["form_data"]:
+            result["method"] = "POST"
+        else:
+            result["method"] = "GET"
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# URL / header helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_url(raw_url: str, base_url_override: str | None = None) -> dict[str, Any]:
+    """Parse *raw_url* into components.
+
+    Parameters
+    ----------
+    raw_url:
+        The URL string from the cURL command (may be relative or absolute).
+    base_url_override:
+        If set, replace the scheme+host of the URL with this value.
+
+    Returns
+    -------
+    dict
+        Keys: ``base_url``, ``path``, ``query_params`` (list[dict]), ``full_url``.
+    """
+    url = raw_url.strip()
+    # Strip surrounding quotes
+    if (url.startswith('"') and url.endswith('"')) or \
+       (url.startswith("'") and url.endswith("'")):
+        url = url[1:-1]
+
+    if base_url_override:
+        # Replace the scheme+host with the override base URL
+        try:
+            parsed_orig = urlparse(url)
+            base_parsed = urlparse(base_url_override.rstrip("/"))
+            url = f"{base_parsed.scheme}://{base_parsed.netloc}{parsed_orig.path}"
+            if parsed_orig.query:
+                url += f"?{parsed_orig.query}"
+            if parsed_orig.fragment:
+                url += f"#{parsed_orig.fragment}"
+        except Exception:  # noqa: BLE001
+            pass  # use original URL
+
+    try:
+        parsed = urlparse(url)
+    except Exception:  # noqa: BLE001
+        return {
+            "base_url": "",
+            "path": url,
+            "query_params": [],
+            "full_url": url,
+        }
+
+    base_url = ""
+    if parsed.scheme and parsed.netloc:
+        base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    path = parsed.path or "/"
+
+    query_params: list[dict[str, Any]] = []
+    if parsed.query:
+        for name, values in parse_qs(parsed.query, keep_blank_values=True).items():
+            for value in values:
+                query_params.append({
+                    "name": name,
+                    "in": "query",
+                    "required": False,
+                    "value": value,
+                })
+
+    return {
+        "base_url": base_url,
+        "path": path,
+        "query_params": query_params,
+        "full_url": url,
+    }
+
+
+def _detect_auth_requirements(
+    headers: list[tuple[str, str]],
+    basic_auth: str | None,
+) -> list[str]:
+    """Return auth scheme names detected from headers and basic auth.
+
+    Parameters
+    ----------
+    headers:
+        List of (name, value) header tuples.
+    basic_auth:
+        Raw ``user:password`` string from ``-u``, or ``None``.
+
+    Returns
+    -------
+    list[str]
+        E.g. ``["bearer"]``, ``["basic"]``, ``["apikey"]``.
+    """
+    schemes: list[str] = []
+    for name, value in headers:
+        name_lower = name.lower().strip()
+        if name_lower == "authorization":
+            parts = value.split(None, 1)
+            scheme = parts[0].lower() if parts else "bearer"
+            if scheme not in schemes:
+                schemes.append(scheme)
+        elif name_lower == "cookie":
+            if "cookie" not in schemes:
+                schemes.append("cookie")
+        elif name_lower in _AUTH_HEADERS:
+            if name_lower not in schemes:
+                schemes.append(name_lower)
+    if basic_auth:
+        if "basic" not in schemes:
+            schemes.append("basic")
+    return schemes
+
+
+def _detect_content_type(
+    headers: list[tuple[str, str]],
+    body: str | None,
+    form_data: list[str],
+) -> str:
+    """Infer the content type from headers or body.
+
+    Parameters
+    ----------
+    headers:
+        Request headers as (name, value) pairs.
+    body:
+        Raw body string, if any.
+    form_data:
+        Form data fields, if any.
+
+    Returns
+    -------
+    str
+        A MIME type string, e.g. ``"application/json"``.
+    """
+    for name, value in headers:
+        if name.lower().strip() == "content-type":
+            return value.split(";")[0].strip()
+
+    if form_data:
+        return "multipart/form-data"
+
+    if body:
+        stripped = body.strip()
+        if stripped.startswith("{") or stripped.startswith("["):
+            return "application/json"
+        if "=" in stripped and "&" in stripped:
+            return "application/x-www-form-urlencoded"
+
+    return ""
+
+
+def _build_request_body(
+    body: str | None,
+    form_data: list[str],
+    content_type: str,
+) -> dict[str, Any] | None:
+    """Build a structured request body representation.
+
+    Parameters
+    ----------
+    body:
+        Raw body string.
+    form_data:
+        Form fields from ``-F``.
+    content_type:
+        Detected content type.
+
+    Returns
+    -------
+    dict | None
+        Structured body dict, or ``None`` if no body.
+    """
+    if form_data:
+        fields: list[dict[str, str]] = []
+        for field in form_data:
+            eq_pos = field.find("=")
+            if eq_pos >= 0:
+                fname = field[:eq_pos].strip()
+                fval = field[eq_pos + 1:].strip()
+                # Strip surrounding quotes from value
+                if (fval.startswith('"') and fval.endswith('"')) or \
+                   (fval.startswith("'") and fval.endswith("'")):
+                    fval = fval[1:-1]
+            else:
+                fname = field
+                fval = ""
+            fields.append({"name": fname, "value": fval})
+        return {"mimeType": "multipart/form-data", "params": fields}
+
+    if body is None:
+        return None
+
+    result: dict[str, Any] = {"mimeType": content_type or "application/octet-stream"}
+
+    if "application/json" in content_type:
+        try:
+            result["json"] = json.loads(body)
+        except (json.JSONDecodeError, ValueError):
+            result["text"] = body
+    else:
+        result["text"] = body
+
+    return result
+
+
+def _priority_for_endpoint(
+    method: str,
+    path: str,
+    auth_requirements: list[str],
+) -> str:
+    """Compute a test priority for an endpoint.
+
+    Rules (highest wins):
+
+    * Path contains auth-related keywords → ``"critical"``
+    * Endpoint requires authentication → ``"high"``
+    * Mutation method (POST/PUT/PATCH/DELETE) → ``"medium"``
+    * Everything else → ``"low"``
+
+    Parameters
+    ----------
+    method:
+        HTTP method.
+    path:
+        URL path.
+    auth_requirements:
+        Auth scheme list.
+
+    Returns
+    -------
+    str
+        One of ``"critical"``, ``"high"``, ``"medium"``, ``"low"``.
+    """
+    path_lower = path.lower()
+    if any(kw in path_lower for kw in _AUTH_PATH_KEYWORDS):
+        return "critical"
+    if auth_requirements:
+        return "high"
+    if method.upper() in _MUTATION_METHODS:
+        return "medium"
+    return "low"
+
+
+def _endpoint_key(method: str, path: str) -> str:
+    """Return a deduplication key for a *method* + *path* pair."""
+    return f"{method.upper()}:{path}"
+
+
+# ---------------------------------------------------------------------------
+# Test case generation
+# ---------------------------------------------------------------------------
+
+
+def _generate_test_cases(endpoint: IngestedEndpoint) -> list[IngestedTestCase]:
+    """Generate test cases for a single *endpoint*.
+
+    Always generates:
+
+    * A **positive / replay** test case.
+    * A **missing auth** security test case when auth is required.
+    * A **parameter tampering** test case when query or path parameters exist.
+
+    Parameters
+    ----------
+    endpoint:
+        The endpoint to generate tests for.
+
+    Returns
+    -------
+    list[IngestedTestCase]
+        Generated test cases.
+    """
+    test_cases: list[IngestedTestCase] = []
+    method = endpoint.method
+    path = endpoint.path
+    priority = endpoint.metadata.get("priority", "medium")
+    source_ref = f"{method} {path}"
+
+    # --- Positive / replay ---
+    test_cases.append(IngestedTestCase(
+        name=f"[{method}] {path} — positive replay",
+        description=(
+            f"Replay the original {method} request to {path} and expect a "
+            f"successful response."
+        ),
+        steps=[
+            {"action": "send_request", "method": method, "path": path},
+            {"action": "assert_status_in", "expected": [200, 201, 202, 204]},
+        ],
+        expected_result="HTTP 2xx — successful response",
+        priority=priority,
+        tags=["curl", "replay", method.lower()],
+        source_ref=source_ref,
+        metadata={"test_type": "positive"},
+    ))
+
+    # --- Missing auth ---
+    if endpoint.auth_requirements:
+        test_cases.append(IngestedTestCase(
+            name=f"[{method}] {path} — missing auth",
+            description=(
+                f"Send {method} {path} without the required authentication "
+                f"headers and expect 401 or 403."
+            ),
+            steps=[
+                {
+                    "action": "send_request",
+                    "method": method,
+                    "path": path,
+                    "omit_headers": list(endpoint.auth_requirements),
+                },
+                {"action": "assert_status_in", "expected": [401, 403]},
+            ],
+            expected_result="HTTP 401 or 403 — Unauthorized / Forbidden",
+            priority=priority,
+            tags=["curl", "security", "auth", method.lower()],
+            source_ref=source_ref,
+            metadata={"test_type": "security_missing_auth"},
+        ))
+
+    # --- Parameter tampering ---
+    has_params = any(
+        p.get("in") in ("query", "path")
+        for p in endpoint.parameters
+    )
+    if has_params:
+        test_cases.append(IngestedTestCase(
+            name=f"[{method}] {path} — parameter manipulation",
+            description=(
+                f"Send {method} {path} with manipulated/unexpected parameter "
+                f"values and expect 400, 404, or 422."
+            ),
+            steps=[
+                {
+                    "action": "send_request",
+                    "method": method,
+                    "path": path,
+                    "tamper_params": True,
+                },
+                {"action": "assert_status_in", "expected": [400, 404, 422]},
+            ],
+            expected_result="HTTP 400, 404, or 422 — invalid parameter rejected",
+            priority=priority,
+            tags=["curl", "security", "parameter_manipulation", method.lower()],
+            source_ref=source_ref,
+            metadata={"test_type": "security_parameter_manipulation"},
+        ))
+
+    return test_cases
+
+
+# ---------------------------------------------------------------------------
+# CurlIngestor
+# ---------------------------------------------------------------------------
+
+
+class CurlIngestor(IngestorPlugin):
+    """Ingestor plugin for cURL commands (individual or batch files).
+
+    Parses cURL commands copied from browser dev tools, API documentation,
+    Postman exports, or shell history and produces normalised endpoint and
+    test-case objects.
+
+    Config keys
+    -----------
+    base_url_override : str, optional
+        Replace the base URL (scheme + host) for all commands.
+    default_headers : dict[str, str], optional
+        Headers to add to every parsed request.
+    ignore_insecure : bool, default False
+        If ``True``, suppress warnings for ``-k`` / ``--insecure`` flags.
+    """
+
+    name = "curl"
+    display_name = "cURL / Batch cURL"
+    description = (
+        "Ingest cURL commands (individual or batch files) to generate "
+        "structured scan targets and test cases."
+    )
+    supported_extensions = [".sh", ".curl", ".txt"]
+    supported_formats = ["curl"]
+
+    # ------------------------------------------------------------------
+    # can_handle
+    # ------------------------------------------------------------------
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return ``True`` for cURL sources.
+
+        Detection rules (in order):
+
+        1. ``source.format`` is ``"curl"`` or ``source.metadata.get("format_hint")``
+           is ``"curl"``.
+        2. ``source.raw_content`` starts with ``curl `` (case-insensitive) or
+           contains a line starting with ``curl ``.
+
+        Parameters
+        ----------
+        source:
+            The source to evaluate.
+
+        Returns
+        -------
+        bool
+            ``True`` when the source appears to contain cURL commands.
+        """
+        if source.format == "curl":
+            return True
+        if source.metadata.get("format_hint") == "curl":
+            return True
+
+        if source.raw_content:
+            content = source.raw_content.strip()
+            # Fast path: content starts with "curl "
+            if re.match(r"^curl\s", content, re.IGNORECASE):
+                return True
+            # Scan lines for any that start with "curl "
+            for line in content.splitlines():
+                if re.match(r"^\s*curl\s", line, re.IGNORECASE):
+                    return True
+
+        return False
+
+    # ------------------------------------------------------------------
+    # validate_config
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate cURL ingestor configuration.
+
+        Parameters
+        ----------
+        config:
+            Configuration dict.
+
+        Returns
+        -------
+        list[str]
+            Human-readable error strings; empty list means valid.
+        """
+        errors: list[str] = []
+
+        if "base_url_override" in config:
+            val = config["base_url_override"]
+            if not isinstance(val, str) or not val.strip():
+                errors.append("base_url_override must be a non-empty string.")
+            else:
+                try:
+                    parsed = urlparse(val)
+                    if not parsed.scheme or not parsed.netloc:
+                        errors.append(
+                            "base_url_override must be a full URL with scheme and host "
+                            "(e.g., 'https://api.example.com')."
+                        )
+                except Exception:  # noqa: BLE001
+                    errors.append("base_url_override is not a valid URL.")
+
+        if "default_headers" in config:
+            val = config["default_headers"]
+            if not isinstance(val, dict):
+                errors.append("default_headers must be a dict mapping header names to values.")
+            else:
+                for k, v in val.items():
+                    if not isinstance(k, str) or not isinstance(v, str):
+                        errors.append(
+                            "default_headers keys and values must all be strings."
+                        )
+                        break
+
+        if "ignore_insecure" in config:
+            val = config["ignore_insecure"]
+            if not isinstance(val, bool):
+                errors.append("ignore_insecure must be a boolean.")
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # ingest
+    # ------------------------------------------------------------------
+
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Parse cURL commands and return a normalised :class:`IngestResult`.
+
+        Parameters
+        ----------
+        source:
+            The source to ingest.  Must provide either ``raw_content`` or a
+            valid ``path`` to a file containing one or more cURL commands.
+        config:
+            Plugin-specific configuration.  See class docstring for keys.
+
+        Returns
+        -------
+        IngestResult
+            Populated result on success; ``success=False`` with ``errors`` on
+            failure.
+        """
+        # --- Read content ---
+        try:
+            content = self._read_source(source)
+        except (FileNotFoundError, ValueError) as exc:
+            return self._make_error_result(source, str(exc))
+
+        if not content or not content.strip():
+            return self._make_error_result(source, "Empty content — nothing to ingest.")
+
+        # --- Config ---
+        base_url_override: str | None = config.get("base_url_override") or None
+        default_headers: dict[str, str] = config.get("default_headers") or {}
+        ignore_insecure: bool = bool(config.get("ignore_insecure", False))
+
+        warnings: list[str] = []
+
+        # --- Split into individual commands ---
+        raw_commands = _split_curl_commands(content)
+        if not raw_commands:
+            return self._make_error_result(
+                source, "No cURL commands found in content."
+            )
+
+        # --- Parse each command ---
+        endpoint_map: dict[str, IngestedEndpoint] = {}
+        test_cases: list[IngestedTestCase] = []
+        skipped = 0
+
+        for cmd_index, raw_cmd in enumerate(raw_commands):
+            parsed = _parse_curl_command(raw_cmd)
+
+            # Propagate parse errors as warnings
+            for err in parsed.get("errors", []):
+                warnings.append(f"Command #{cmd_index + 1}: {err}")
+
+            url_str = parsed.get("url")
+            if not url_str:
+                warnings.append(
+                    f"Command #{cmd_index + 1}: No URL found — skipping."
+                )
+                skipped += 1
+                continue
+
+            # --- Merge default headers ---
+            headers: list[tuple[str, str]] = list(parsed["headers"])
+            for dh_name, dh_val in default_headers.items():
+                # Only add if not already present (case-insensitive)
+                existing_names = {h[0].lower() for h in headers}
+                if dh_name.lower() not in existing_names:
+                    headers.append((dh_name, dh_val))
+
+            # --- Parse URL ---
+            url_info = _parse_url(url_str, base_url_override)
+            path = url_info["path"]
+            base_url = url_info["base_url"]
+            query_params = url_info["query_params"]
+
+            # --- Method ---
+            method = (parsed.get("method") or "GET").upper()
+
+            # --- Auth ---
+            auth_requirements = _detect_auth_requirements(
+                headers, parsed.get("basic_auth")
+            )
+
+            # --- Content type & body ---
+            body = parsed.get("body")
+            form_data = parsed.get("form_data") or []
+            content_type = _detect_content_type(headers, body, form_data)
+            request_body = _build_request_body(body, form_data, content_type)
+
+            # --- Warnings for insecure / follow redirects ---
+            if parsed.get("insecure") and not ignore_insecure:
+                warnings.append(
+                    f"Command #{cmd_index + 1}: -k/--insecure flag detected — "
+                    f"TLS verification disabled ({method} {url_str})."
+                )
+
+            # --- Priority ---
+            priority = _priority_for_endpoint(method, path, auth_requirements)
+
+            # --- Build parameters list ---
+            # Path parameters are extracted from curly-brace templates if present;
+            # for curl we don't typically normalise IDs, but respect explicit templates.
+            path_params: list[dict[str, Any]] = []
+            for match in re.finditer(r"\{(\w+)\}", path):
+                path_params.append({
+                    "name": match.group(1),
+                    "in": "path",
+                    "required": True,
+                })
+            all_params = path_params + query_params
+
+            # --- Deduplicate ---
+            key = _endpoint_key(method, path)
+
+            if key not in endpoint_map:
+                # Build auth_requirements as header references
+                metadata: dict[str, Any] = {
+                    "base_url": base_url,
+                    "priority": priority,
+                    "original_urls": [url_info["full_url"]],
+                    "insecure": parsed.get("insecure", False),
+                    "follow_redirects": parsed.get("follow_redirects", False),
+                    "compressed": parsed.get("compressed", False),
+                }
+                if parsed.get("basic_auth"):
+                    metadata["has_basic_auth"] = True
+
+                endpoint_map[key] = IngestedEndpoint(
+                    method=method,
+                    path=path,
+                    summary=f"{method} {path}",
+                    description=f"Extracted from cURL command: {method} {url_str}",
+                    parameters=all_params,
+                    request_body=request_body,
+                    responses={},
+                    auth_requirements=auth_requirements,
+                    tags=["curl", method.lower()],
+                    metadata=metadata,
+                )
+            else:
+                # Merge into existing
+                existing = endpoint_map[key]
+                if url_info["full_url"] not in existing.metadata.get("original_urls", []):
+                    existing.metadata.setdefault("original_urls", []).append(
+                        url_info["full_url"]
+                    )
+                for scheme in auth_requirements:
+                    if scheme not in existing.auth_requirements:
+                        existing.auth_requirements.append(scheme)
+
+        # --- Generate test cases ---
+        endpoints = list(endpoint_map.values())
+        for ep in endpoints:
+            test_cases.extend(_generate_test_cases(ep))
+
+        # --- Stats ---
+        stats: dict[str, Any] = {
+            "commands_found": len(raw_commands),
+            "endpoints_extracted": len(endpoints),
+            "test_cases_generated": len(test_cases),
+            "commands_skipped": skipped,
+            "warnings_count": len(warnings),
+        }
+
+        return IngestResult(
+            success=True,
+            source=source,
+            endpoints=endpoints,
+            test_cases=test_cases,
+            errors=[],
+            warnings=warnings,
+            stats=stats,
+        )