nat-engine 1__py3-none-any.whl

mannf/product/ingestors/har_ingestor.py

@@ -0,0 +1,976 @@
+# 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.
+
+"""HAR (HTTP Archive) ingestor plugin.
+
+Parses HAR 1.2 files and produces normalised
+:class:`~mannf.product.ingestors.models.IngestedEndpoint` and
+:class:`~mannf.product.ingestors.models.IngestedTestCase` objects from
+recorded HTTP traffic.
+
+HAR files are JSON documents exported by browser dev tools, Fiddler, Charles
+Proxy, and similar tools.  This ingestor is especially useful for teams that
+lack structured API specs — they can record real traffic and let NAT generate
+security and functional test cases from the recordings.
+
+Spec reference: http://www.softwareishard.com/blog/har-12-spec/
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse, parse_qs
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedEndpoint,
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# File extensions considered "static resources" (excluded by default)
+_STATIC_EXTENSIONS: frozenset[str] = frozenset({
+    ".js", ".css", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg",
+    ".woff", ".woff2", ".ttf", ".eot", ".map", ".webp", ".bmp", ".tiff",
+    ".pdf", ".zip", ".gz", ".tar", ".mp4", ".webm", ".mp3", ".wav",
+})
+
+# Headers that indicate authentication requirements
+_AUTH_HEADERS: frozenset[str] = frozenset({
+    "authorization",
+    "cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-access-token",
+    "x-csrf-token",
+    "bearer",
+    "token",
+})
+
+# Sensitive headers to redact from stored values (keep the name but mask value)
+_SENSITIVE_HEADERS: frozenset[str] = frozenset({
+    "authorization",
+    "cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-access-token",
+    "x-csrf-token",
+    "proxy-authorization",
+    "x-forwarded-for",
+    "set-cookie",
+})
+
+# Regex patterns for path normalisation
+_RE_UUID = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+    re.IGNORECASE,
+)
+_RE_NUMERIC_ID = re.compile(r"^\d+$")
+
+# Mutation methods
+_MUTATION_METHODS: frozenset[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+
+def _normalise_path(path: str) -> str:
+    """Replace numeric IDs and UUIDs in *path* with ``{id}`` / ``{uuid}``.
+
+    For example::
+
+        /users/123          →  /users/{id}
+        /items/abc-def-...  →  /items/{uuid}
+        /orgs/42/repos/7    →  /orgs/{id}/repos/{id}
+
+    Parameters
+    ----------
+    path:
+        Raw URL path string.
+
+    Returns
+    -------
+    str
+        Normalised path template.
+    """
+    segments: list[str] = []
+    for segment in path.split("/"):
+        if not segment:
+            segments.append(segment)
+            continue
+        # Strip query string fragment if accidentally included
+        segment = segment.split("?")[0]
+        if _RE_UUID.fullmatch(segment):
+            segments.append("{uuid}")
+        elif _RE_NUMERIC_ID.fullmatch(segment):
+            segments.append("{id}")
+        else:
+            segments.append(segment)
+    return "/".join(segments)
+
+
+def _is_static_resource(path: str) -> bool:
+    """Return ``True`` when *path* ends with a known static file extension.
+
+    Parameters
+    ----------
+    path:
+        URL path to check.
+
+    Returns
+    -------
+    bool
+        ``True`` if the path looks like a static asset.
+    """
+    suffix = Path(path.split("?")[0]).suffix.lower()
+    return suffix in _STATIC_EXTENSIONS
+
+
+def _extract_auth_requirements(headers: list[dict[str, str]]) -> list[str]:
+    """Return a list of auth scheme names detected in *headers*.
+
+    Parameters
+    ----------
+    headers:
+        List of ``{"name": ..., "value": ...}`` header dicts from a HAR entry.
+
+    Returns
+    -------
+    list[str]
+        E.g. ``["bearer"]``, ``["apikey"]``, or ``[]``.
+    """
+    schemes: list[str] = []
+    for header in headers:
+        name_lower = header.get("name", "").lower().strip()
+        value = header.get("value", "")
+        if name_lower == "authorization":
+            # Try to extract scheme from value, e.g. "Bearer <token>"
+            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)
+    return schemes
+
+
+def _sanitise_headers(headers: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Return *headers* with sensitive values replaced by ``"<redacted>"``.
+
+    Parameters
+    ----------
+    headers:
+        Raw header list from a HAR entry.
+
+    Returns
+    -------
+    list[dict[str, str]]
+        Headers safe to store, with sensitive values masked.
+    """
+    result: list[dict[str, str]] = []
+    for h in headers:
+        name = h.get("name", "")
+        value = h.get("value", "")
+        if name.lower().strip() in _SENSITIVE_HEADERS:
+            value = "<redacted>"
+        result.append({"name": name, "value": value})
+    return result
+
+
+def _parse_post_data(post_data: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Extract a request body representation from a HAR ``postData`` block.
+
+    Parameters
+    ----------
+    post_data:
+        The ``postData`` dict from a HAR request, or ``None``.
+
+    Returns
+    -------
+    dict | None
+        A structured body dict, or ``None`` if there is no body.
+    """
+    if not post_data:
+        return None
+    mime_type: str = post_data.get("mimeType", "") or ""
+    text: str = post_data.get("text", "") or ""
+    params: list[dict] = post_data.get("params", []) or []
+
+    body: dict[str, Any] = {"mimeType": mime_type}
+
+    if "application/json" in mime_type and text:
+        try:
+            body["json"] = json.loads(text)
+        except (json.JSONDecodeError, ValueError):
+            body["text"] = text
+    elif params:
+        body["params"] = [
+            {"name": p.get("name", ""), "value": p.get("value", "")}
+            for p in params
+        ]
+    elif text:
+        body["text"] = text
+
+    return body if (body.get("json") or body.get("text") or body.get("params")) else None
+
+
+def _extract_query_params(query_string: list[dict[str, str]]) -> list[dict[str, Any]]:
+    """Convert a HAR ``queryString`` array to parameter dicts.
+
+    Parameters
+    ----------
+    query_string:
+        The ``queryString`` array from a HAR request.
+
+    Returns
+    -------
+    list[dict]
+        Parameter dicts with ``name``, ``in``, and ``required`` keys.
+    """
+    seen: set[str] = set()
+    params: list[dict[str, Any]] = []
+    for qs in query_string:
+        name = qs.get("name", "").strip()
+        if not name or name in seen:
+            continue
+        seen.add(name)
+        params.append({
+            "name": name,
+            "in": "query",
+            "required": False,
+            "value": qs.get("value", ""),
+        })
+    return params
+
+
+def _extract_path_params(normalised_path: str) -> list[dict[str, Any]]:
+    """Extract ``{id}`` and ``{uuid}`` placeholders as path parameters.
+
+    Parameters
+    ----------
+    normalised_path:
+        Path template string, e.g. ``"/users/{id}/posts/{uuid}"``.
+
+    Returns
+    -------
+    list[dict]
+        One parameter dict per placeholder found.
+    """
+    params: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for match in re.finditer(r"\{(\w+)\}", normalised_path):
+        name = match.group(1)
+        if name not in seen:
+            seen.add(name)
+            params.append({
+                "name": name,
+                "in": "path",
+                "required": True,
+            })
+    return params
+
+
+def _endpoint_key(method: str, normalised_path: str) -> str:
+    """Return a deduplication key for a method + normalised path pair.
+
+    Parameters
+    ----------
+    method:
+        HTTP method (uppercase).
+    normalised_path:
+        Normalised path template.
+
+    Returns
+    -------
+    str
+        A unique string key.
+    """
+    return f"{method.upper()}:{normalised_path}"
+
+
+def _priority_for_endpoint(
+    method: str,
+    path: str,
+    auth_requirements: list[str],
+) -> str:
+    """Compute a test priority for an endpoint.
+
+    Rules (highest wins):
+    * Auth endpoints (path contains ``/auth``, ``/login``, ``/token``,
+      ``/logout``, ``/password``) → ``"critical"``
+    * Endpoints that require authentication → ``"high"``
+    * Mutation methods (POST/PUT/PATCH/DELETE) → ``"medium"``
+    * Everything else → ``"low"``
+
+    Parameters
+    ----------
+    method:
+        HTTP method.
+    path:
+        Normalised URL path.
+    auth_requirements:
+        Auth scheme list from :func:`_extract_auth_requirements`.
+
+    Returns
+    -------
+    str
+        One of ``"critical"``, ``"high"``, ``"medium"``, ``"low"``.
+    """
+    path_lower = path.lower()
+    auth_keywords = ("/auth", "/login", "/token", "/logout", "/password",
+                     "/oauth", "/signin", "/signup", "/register")
+    if any(kw in path_lower for kw in auth_keywords):
+        return "critical"
+    if auth_requirements:
+        return "high"
+    if method.upper() in _MUTATION_METHODS:
+        return "medium"
+    return "low"
+
+
+def _generate_test_cases(
+    endpoint: IngestedEndpoint,
+    recorded_status: int,
+    include_response_data: bool,
+    response_body: str | None,
+) -> list[IngestedTestCase]:
+    """Generate test cases for a single *endpoint*.
+
+    Always generates:
+    * A **positive / replay** test case.
+    * A **missing auth** negative test case when auth is required.
+    * A **parameter tampering** test case when path parameters exist.
+
+    Parameters
+    ----------
+    endpoint:
+        The endpoint to generate tests for.
+    recorded_status:
+        The HTTP status code observed in the HAR recording.
+    include_response_data:
+        If ``True`` and *response_body* is non-empty, the positive test case
+        includes a response body snapshot for regression comparison.
+    response_body:
+        Raw response body text, or ``None``.
+
+    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 ---
+    positive_meta: dict[str, Any] = {
+        "test_type": "positive",
+        "recorded_status": recorded_status,
+    }
+    if include_response_data and response_body:
+        positive_meta["expected_response_body"] = response_body
+
+    positive_steps = [
+        {"action": "send_request", "method": method, "path": path},
+        {"action": "assert_status", "expected": recorded_status},
+    ]
+    if include_response_data and response_body:
+        positive_steps.append({"action": "assert_response_body", "snapshot": True})
+
+    test_cases.append(IngestedTestCase(
+        name=f"[{method}] {path} — positive replay",
+        description=(
+            f"Replay the recorded {method} request to {path} and expect "
+            f"HTTP {recorded_status}."
+        ),
+        steps=positive_steps,
+        expected_result=f"HTTP {recorded_status} response",
+        priority=priority,
+        tags=["har", "replay", method.lower()],
+        source_ref=source_ref,
+        metadata=positive_meta,
+    ))
+
+    # --- Missing auth negative test ---
+    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=["har", "security", "auth", method.lower()],
+            source_ref=source_ref,
+            metadata={"test_type": "security_missing_auth"},
+        ))
+
+    # --- Parameter tampering test ---
+    path_params = [p for p in endpoint.parameters if p.get("in") == "path"]
+    if path_params:
+        test_cases.append(IngestedTestCase(
+            name=f"[{method}] {path} — invalid path parameter",
+            description=(
+                f"Send {method} {path} with invalid/unexpected path parameter "
+                f"values and expect 400 or 404."
+            ),
+            steps=[
+                {"action": "send_request", "method": method, "path": path,
+                 "tamper_path_params": True},
+                {"action": "assert_status_in", "expected": [400, 404, 422]},
+            ],
+            expected_result="HTTP 400, 404, or 422 — invalid parameter rejected",
+            priority=priority,
+            tags=["har", "security", "parameter_tampering", method.lower()],
+            source_ref=source_ref,
+            metadata={"test_type": "security_parameter_tampering"},
+        ))
+
+    return test_cases
+
+
+# ---------------------------------------------------------------------------
+# HARIngestor
+# ---------------------------------------------------------------------------
+
+
+class HARIngestor(IngestorPlugin):
+    """Ingestor plugin for HAR (HTTP Archive) files.
+
+    Parses recorded HTTP traffic exported from browser dev tools, Fiddler,
+    Charles Proxy, or similar tools and produces normalised endpoint and
+    test-case objects.
+
+    Config keys
+    -----------
+    base_url_filter : str, optional
+        If set, only ingest entries whose URL starts with this prefix.
+    exclude_static : bool, default True
+        Skip entries for static assets (.js, .css, images, fonts, etc.).
+    include_response_data : bool, default False
+        Capture response bodies for regression testing.
+    min_status : int, optional
+        Only include entries with HTTP status ≥ this value.
+    max_status : int, optional
+        Only include entries with HTTP status ≤ this value.
+    replay_mode : bool, default False
+        When ``True``, produce a single ordered scenario sequence preserving
+        request ordering and timing (inter-request delay in milliseconds) rather
+        than deduplicating endpoints.  The result's ``test_cases`` will contain
+        one :class:`~mannf.product.ingestors.models.IngestedTestCase` per
+        HAR entry (after filtering), grouped as an ordered browser flow scenario
+        compatible with ``FunctionalTestOrchestrator.run()``.
+    """
+
+    name = "har"
+    display_name = "HAR File"
+    description = "Ingest HTTP Archive (HAR) files from browser dev tools or proxies."
+    supported_extensions = [".har"]
+    supported_formats = ["har"]
+
+    # ------------------------------------------------------------------
+    # can_handle
+    # ------------------------------------------------------------------
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return ``True`` for HAR sources.
+
+        Detection rules (in order):
+        1. ``source.format`` is ``"har"`` or ``source.metadata.get("format_hint")``
+           is ``"har"``.
+        2. File extension is ``.har``.
+        3. Content starts with ``{"log":`` or contains both ``"log"`` and
+           ``"entries"`` keys.
+
+        Parameters
+        ----------
+        source:
+            The source to evaluate.
+
+        Returns
+        -------
+        bool
+            ``True`` when the source appears to be a HAR document.
+        """
+        if source.format == "har":
+            return True
+        if source.metadata.get("format_hint") == "har":
+            return True
+
+        if source.path is not None:
+            ext = Path(source.path).suffix.lower()
+            if ext == ".har":
+                return True
+
+        if source.raw_content:
+            stripped = source.raw_content.strip()
+            # Fast check before trying JSON parse
+            if stripped.startswith('{"log"') or stripped.startswith('{ "log"'):
+                return True
+            if '"log"' in stripped and '"entries"' in stripped:
+                try:
+                    data = json.loads(stripped)
+                    return isinstance(data.get("log"), dict) and "entries" in data["log"]
+                except (json.JSONDecodeError, ValueError):
+                    return False
+
+        return False
+
+    # ------------------------------------------------------------------
+    # validate_config
+    # ------------------------------------------------------------------
+
+    def validate_config(self, config: dict) -> list[str]:
+        """Validate HAR ingestor configuration.
+
+        Parameters
+        ----------
+        config:
+            Configuration dict to validate.
+
+        Returns
+        -------
+        list[str]
+            Human-readable error strings; empty list means valid.
+        """
+        errors: list[str] = []
+
+        if "min_status" in config:
+            try:
+                val = int(config["min_status"])
+                if not (100 <= val <= 599):
+                    errors.append("min_status must be between 100 and 599.")
+            except (TypeError, ValueError):
+                errors.append("min_status must be an integer.")
+
+        if "max_status" in config:
+            try:
+                val = int(config["max_status"])
+                if not (100 <= val <= 599):
+                    errors.append("max_status must be between 100 and 599.")
+            except (TypeError, ValueError):
+                errors.append("max_status must be an integer.")
+
+        if "min_status" in config and "max_status" in config:
+            try:
+                mn = int(config["min_status"])
+                mx = int(config["max_status"])
+                if mn > mx:
+                    errors.append("min_status must not be greater than max_status.")
+            except (TypeError, ValueError):
+                pass  # already reported above
+
+        if "base_url_filter" in config:
+            val = config["base_url_filter"]
+            if not isinstance(val, str) or not val.strip():
+                errors.append("base_url_filter must be a non-empty string.")
+
+        if "replay_mode" in config:
+            if not isinstance(config["replay_mode"], bool):
+                errors.append("replay_mode must be a boolean.")
+
+        return errors
+
+    # ------------------------------------------------------------------
+    # ingest
+    # ------------------------------------------------------------------
+
+    async def ingest(self, source: IngestorSource, config: dict) -> IngestResult:
+        """Parse a HAR document and return a normalised :class:`IngestResult`.
+
+        Parameters
+        ----------
+        source:
+            The source to ingest.  Must provide either ``raw_content`` or a
+            valid ``path`` to a HAR JSON file.
+        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.")
+
+        # --- Parse JSON ---
+        try:
+            data: dict[str, Any] = json.loads(content)
+        except (json.JSONDecodeError, ValueError) as exc:
+            return self._make_error_result(source, f"Failed to parse HAR JSON: {exc}")
+
+        # --- Extract log ---
+        log = data.get("log")
+        if not isinstance(log, dict):
+            return self._make_error_result(
+                source, "Invalid HAR: top-level 'log' key missing or not an object."
+            )
+
+        entries: list[dict[str, Any]] = log.get("entries", []) or []
+        if not isinstance(entries, list):
+            return self._make_error_result(
+                source, "Invalid HAR: 'log.entries' is not an array."
+            )
+
+        # --- Config options ---
+        base_url_filter: str = (config.get("base_url_filter") or "").strip()
+        exclude_static: bool = bool(config.get("exclude_static", True))
+        include_response_data: bool = bool(config.get("include_response_data", False))
+        replay_mode: bool = bool(config.get("replay_mode", False))
+        min_status: int | None = None
+        max_status: int | None = None
+        if "min_status" in config:
+            try:
+                min_status = int(config["min_status"])
+            except (TypeError, ValueError):
+                pass
+        if "max_status" in config:
+            try:
+                max_status = int(config["max_status"])
+            except (TypeError, ValueError):
+                pass
+
+        warnings: list[str] = []
+        # Track metadata per unique endpoint key
+        # endpoint_key → IngestedEndpoint
+        endpoint_map: dict[str, IngestedEndpoint] = {}
+        # endpoint_key → list of (status, response_body)
+        response_map: dict[str, list[tuple[int, str | None]]] = {}
+        # replay_mode: ordered list of (entry, raw_url, method, parsed, response_status, response_body)
+        replay_entries: list[dict[str, Any]] = []
+
+        skipped_static = 0
+        skipped_filter = 0
+        skipped_status = 0
+        total_entries = len(entries)
+
+        for entry in entries:
+            if not isinstance(entry, dict):
+                warnings.append("Skipped a non-object entry in log.entries.")
+                continue
+
+            request: dict[str, Any] = entry.get("request") or {}
+            response: dict[str, Any] = entry.get("response") or {}
+
+            if not isinstance(request, dict):
+                warnings.append("Skipped entry with non-object 'request'.")
+                continue
+
+            raw_url: str = request.get("url", "") or ""
+            method: str = (request.get("method", "GET") or "GET").upper()
+
+            if not raw_url:
+                warnings.append("Skipped entry with missing URL.")
+                continue
+
+            # --- Parse URL ---
+            try:
+                parsed = urlparse(raw_url)
+            except Exception:  # noqa: BLE001
+                warnings.append(f"Skipped entry with unparseable URL: {raw_url!r}")
+                continue
+
+            base_url_part = f"{parsed.scheme}://{parsed.netloc}" if parsed.netloc else ""
+            raw_path = parsed.path or "/"
+
+            # --- Apply base_url_filter ---
+            if base_url_filter:
+                if not raw_url.startswith(base_url_filter):
+                    skipped_filter += 1
+                    continue
+
+            # --- Apply static resource filter ---
+            if exclude_static and _is_static_resource(raw_path):
+                skipped_static += 1
+                continue
+
+            # --- Apply status code filter ---
+            response_status: int = 0
+            if isinstance(response, dict):
+                try:
+                    response_status = int(response.get("status", 0))
+                except (TypeError, ValueError):
+                    response_status = 0
+
+            if min_status is not None and response_status < min_status:
+                skipped_status += 1
+                continue
+            if max_status is not None and response_status > max_status:
+                skipped_status += 1
+                continue
+
+            # --- Normalise path ---
+            normalised_path = _normalise_path(raw_path)
+            key = _endpoint_key(method, normalised_path)
+
+            # --- Extract headers ---
+            raw_headers: list[dict] = request.get("headers", []) or []
+            auth_requirements = _extract_auth_requirements(raw_headers)
+            safe_headers = _sanitise_headers(raw_headers)
+
+            # --- Extract parameters ---
+            query_string: list[dict] = request.get("queryString", []) or []
+            query_params = _extract_query_params(query_string)
+            path_params = _extract_path_params(normalised_path)
+            all_params = path_params + query_params
+
+            # --- Extract request body ---
+            post_data: dict | None = request.get("postData")
+            request_body = _parse_post_data(post_data)
+
+            # --- Extract response content type ---
+            response_headers: list[dict] = []
+            response_content_type = ""
+            response_body_text: str | None = None
+            if isinstance(response, dict):
+                response_headers = response.get("headers", []) or []
+                for rh in response_headers:
+                    if rh.get("name", "").lower() == "content-type":
+                        response_content_type = rh.get("value", "")
+                        break
+                if include_response_data:
+                    content_block: dict = response.get("content") or {}
+                    response_body_text = content_block.get("text") or None
+
+            # --- Determine priority ---
+            priority = _priority_for_endpoint(method, normalised_path, auth_requirements)
+
+            # --- Collect replay entry (replay_mode) ---
+            if replay_mode:
+                entry_time_ms: float = 0.0
+                try:
+                    entry_time_ms = float(entry.get("time", 0) or 0)
+                except (TypeError, ValueError):
+                    pass
+                started_at: str = entry.get("startedDateTime", "") or ""
+                replay_entries.append({
+                    "url": raw_url,
+                    "method": method,
+                    "path": normalised_path,
+                    "auth_requirements": auth_requirements,
+                    "request_body": request_body,
+                    "response_status": response_status,
+                    "response_body": response_body_text,
+                    "time_ms": entry_time_ms,
+                    "started_at": started_at,
+                    "priority": priority,
+                })
+
+            if key not in endpoint_map:
+                # Build endpoint
+                metadata: dict[str, Any] = {
+                    "base_url": base_url_part,
+                    "priority": priority,
+                    "original_urls": [raw_url],
+                    "content_types_observed": [],
+                }
+                if response_content_type:
+                    metadata["content_types_observed"].append(response_content_type)
+
+                endpoint_map[key] = IngestedEndpoint(
+                    method=method,
+                    path=normalised_path,
+                    summary=f"{method} {normalised_path}",
+                    description=f"Recorded {method} request to {normalised_path}",
+                    parameters=all_params,
+                    request_body=request_body,
+                    responses={str(response_status): {"description": "Recorded response"}}
+                    if response_status else {},
+                    auth_requirements=auth_requirements,
+                    tags=["har", method.lower()],
+                    metadata=metadata,
+                )
+                response_map[key] = [(response_status, response_body_text)]
+            else:
+                # Merge into existing endpoint
+                existing = endpoint_map[key]
+                if raw_url not in existing.metadata.get("original_urls", []):
+                    existing.metadata.setdefault("original_urls", []).append(raw_url)
+
+                # Merge auth requirements
+                for scheme in auth_requirements:
+                    if scheme not in existing.auth_requirements:
+                        existing.auth_requirements.append(scheme)
+
+                # Merge content types
+                if response_content_type:
+                    ct_list = existing.metadata.setdefault("content_types_observed", [])
+                    if response_content_type not in ct_list:
+                        ct_list.append(response_content_type)
+
+                # Merge query params
+                existing_param_names = {p["name"] for p in existing.parameters}
+                for p in query_params:
+                    if p["name"] not in existing_param_names:
+                        existing.parameters.append(p)
+                        existing_param_names.add(p["name"])
+
+                # Add response status
+                if response_status and str(response_status) not in existing.responses:
+                    existing.responses[str(response_status)] = {
+                        "description": "Recorded response"
+                    }
+
+                response_map[key].append((response_status, response_body_text))
+
+        if not endpoint_map and total_entries > 0:
+            filtered_count = skipped_static + skipped_filter + skipped_status
+            if filtered_count == total_entries:
+                warnings.append(
+                    "All entries were filtered out. Check base_url_filter, "
+                    "exclude_static, and min_status/max_status settings."
+                )
+            else:
+                warnings.append("No valid endpoints could be extracted from the HAR entries.")
+
+        # --- Report filter stats ---
+        if skipped_static:
+            warnings.append(
+                f"Skipped {skipped_static} static resource entries "
+                f"(exclude_static=True)."
+            )
+        if skipped_filter:
+            warnings.append(
+                f"Skipped {skipped_filter} entries that did not match "
+                f"base_url_filter={base_url_filter!r}."
+            )
+        if skipped_status:
+            warnings.append(
+                f"Skipped {skipped_status} entries outside the status code range."
+            )
+
+        # --- Generate test cases ---
+        endpoints = list(endpoint_map.values())
+        test_cases: list[IngestedTestCase] = []
+
+        if replay_mode and replay_entries:
+            # Build a single ordered scenario as an IngestedTestCase with one step per entry
+            steps: list[dict[str, Any]] = []
+            prev_started_at: str = ""
+            for idx, re_entry in enumerate(replay_entries):
+                # Compute inter-request delay from HAR timing metadata
+                delay_ms: float = 0.0
+                if idx > 0:
+                    delay_ms = replay_entries[idx - 1].get("time_ms", 0.0) or 0.0
+
+                step: dict[str, Any] = {
+                    "action": "navigate" if re_entry["method"] == "GET" else "send_request",
+                    "method": re_entry["method"],
+                    "url": re_entry["url"],
+                    "selector": re_entry["url"],
+                    "sequence_index": idx,
+                }
+                if delay_ms > 0:
+                    step["delay_ms"] = delay_ms
+                if re_entry.get("request_body"):
+                    step["body"] = re_entry["request_body"]
+                if re_entry.get("auth_requirements"):
+                    step["auth_requirements"] = re_entry["auth_requirements"]
+                steps.append(step)
+
+                # Add assertion step for expected status
+                if re_entry["response_status"]:
+                    steps.append({
+                        "action": "assert_status",
+                        "expected": re_entry["response_status"],
+                        "sequence_index": idx,
+                    })
+
+            # Determine priority from most-frequent priority value
+            all_priorities = [e.get("priority", "medium") for e in replay_entries]
+            priority_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+            top_priority = min(all_priorities, key=lambda p: priority_order.get(p, 2))
+
+            test_cases.append(IngestedTestCase(
+                name="HAR replay sequence",
+                description=(
+                    f"Ordered replay of {len(replay_entries)} recorded requests "
+                    f"preserving original request sequence and timing."
+                ),
+                steps=steps,
+                expected_result="All recorded requests complete with their expected HTTP status codes.",
+                priority=top_priority,
+                tags=["har", "replay", "ordered_sequence"],
+                source_ref="har_replay",
+                metadata={
+                    "test_type": "replay_sequence",
+                    "replay_mode": True,
+                    "entry_count": len(replay_entries),
+                },
+            ))
+        else:
+            for ep in endpoints:
+                key = _endpoint_key(ep.method, ep.path)
+                recorded_responses = response_map.get(key, [])
+                # Use the most common status code for the positive test
+                if recorded_responses:
+                    statuses = [s for s, _ in recorded_responses if s]
+                    recorded_status = max(set(statuses), key=statuses.count) if statuses else 200
+                    # Use the first available response body (if captured)
+                    resp_body = next(
+                        (b for _, b in recorded_responses if b is not None), None
+                    )
+                else:
+                    recorded_status = 200
+                    resp_body = None
+
+                test_cases.extend(
+                    _generate_test_cases(ep, recorded_status, include_response_data, resp_body)
+                )
+
+        # --- Stats ---
+        stats: dict[str, Any] = {
+            "total_entries": total_entries,
+            "endpoints_count": len(endpoints),
+            "test_cases_count": len(test_cases),
+            "skipped_static": skipped_static,
+            "skipped_filter": skipped_filter,
+            "skipped_status": skipped_status,
+            "include_response_data": include_response_data,
+            "replay_mode": replay_mode,
+        }
+
+        return IngestResult(
+            success=True,
+            source=source,
+            endpoints=endpoints,
+            test_cases=test_cases,
+            errors=[],
+            warnings=warnings,
+            stats=stats,
+        )