Add system-tests for API Security Testing - Normalized Route RFC (#6947)

christophe-papazian · claude · web-flow · commit b6fabca6a718 · 2026-05-20T13:49:04.000+02:00
Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/manifests/cpp_nginx.yml b/manifests/cpp_nginx.yml
@@ -50,6 +50,7 @@ manifest:
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_Headers: v1.8.0
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_on_Block: v1.8.0
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: irrelevant (not applicable to proxies)
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: irrelevant (not applicable to proxies)
   tests/appsec/iast/sink/: irrelevant (ASM is not implemented in C++)
   tests/appsec/iast/source/: irrelevant (ASM is not implemented in C++)
   tests/appsec/iast/source/test_parameter_value.py::TestParameterValue::test_source_reported: irrelevant
diff --git a/manifests/dotnet.yml b/manifests/dotnet.yml
@@ -63,6 +63,7 @@ manifest:
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_Headers: v2.46.0
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_on_Block: v3.26.3
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: missing_feature
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_ExtendedLocation: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_StackTrace: missing_feature
diff --git a/manifests/envoy.yml b/manifests/envoy.yml
@@ -3,6 +3,7 @@
 manifest:
   tests/appsec/api_security/test_endpoints.py: irrelevant (language not implementing this feature)
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: irrelevant (not applicable to proxies)
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: irrelevant (not applicable to proxies)
   tests/appsec/test_alpha.py: v1.72.0
   tests/appsec/test_blocking_addresses.py: v1.72.0
   tests/appsec/test_blocking_addresses.py::Test_BlockingGraphqlResolvers: irrelevant
diff --git a/manifests/golang.yml b/manifests/golang.yml
@@ -84,6 +84,7 @@ manifest:
         net-http: v2.1.0-dev  # Using SDK-style
         uds-echo: v2.5.0  # Modified by easy win activation script
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: missing_feature
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_ExtendedLocation: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_StackTrace: missing_feature
diff --git a/manifests/haproxy.yml b/manifests/haproxy.yml
@@ -3,6 +3,7 @@
 manifest:
   tests/appsec/api_security/test_endpoints.py: irrelevant (language not implementing this feature)
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: irrelevant (not applicable to proxies)
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: irrelevant (not applicable to proxies)
   tests/appsec/test_alpha.py: v2.4.0
   tests/appsec/test_blocking_addresses.py: v2.4.0
   tests/appsec/test_blocking_addresses.py::Test_BlockingGraphqlResolvers: irrelevant
diff --git a/manifests/java.yml b/manifests/java.yml
@@ -284,6 +284,7 @@ manifest:
         spring-boot-3-native: irrelevant (GraalVM. Tracing support only)
         vertx3: missing_feature
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: missing_feature
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_ExtendedLocation: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_StackTrace: missing_feature
diff --git a/manifests/nodejs.yml b/manifests/nodejs.yml
@@ -228,6 +228,7 @@ manifest:
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_Headers: *ref_4_21_0
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_on_Block: missing_feature
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: *ref_5_104_0
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection:
     - weblog_declaration:
         "*": *ref_5_20_0
diff --git a/manifests/php.yml b/manifests/php.yml
@@ -97,6 +97,7 @@ manifest:
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_Headers: v0.94.0
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_on_Block: v1.11.0-dev
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: missing_feature
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_ExtendedLocation: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_StackTrace: missing_feature
diff --git a/manifests/python.yml b/manifests/python.yml
@@ -135,6 +135,7 @@ manifest:
         fastapi: v2.5.0
   tests/appsec/api_security/test_schemas.py::Test_Schema_Response_on_Block: v3.10.0.dev
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: v4.9.0-rc2
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast:
     - weblog_declaration:
         tornado: v4.3.1  # Modified by easy win activation script
diff --git a/manifests/ruby.yml b/manifests/ruby.yml
@@ -182,6 +182,7 @@ manifest:
         graphql23: missing_feature (no way to separate request paths)
         rack: missing_feature (performance impact of JSON parsing)
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: missing_feature
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_ExtendedLocation: missing_feature
   tests/appsec/iast/sink/test_code_injection.py::TestCodeInjection_StackTrace: missing_feature
diff --git a/manifests/rust.yml b/manifests/rust.yml
@@ -6,6 +6,7 @@ manifest:
   tests/appsec/api_security/test_endpoint_fallback.py: missing_feature
   tests/appsec/api_security/test_endpoints.py: irrelevant (language not implementing this feature)
   tests/appsec/api_security_testing/test_headers_collection.py::Test_SecurityTestingHeaders: missing_feature
+  tests/appsec/api_security_testing/test_normalized_route.py::Test_NormalizedRoute: missing_feature
   tests/appsec/iast/source/test_parameter_value.py::TestParameterValue::test_source_reported: irrelevant
   tests/appsec/test_only_python.py::Test_ImportError: irrelevant (specific tests for python tracer)
   tests/appsec/test_traces.py::Test_AppSecEventSpanTags::test_header_collection: irrelevant (test)
diff --git a/tests/appsec/api_security_testing/test_normalized_route.py b/tests/appsec/api_security_testing/test_normalized_route.py
@@ -0,0 +1,134 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the the Apache License Version 2.0.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2026 Datadog, Inc.
+
+import re
+
+from utils import interfaces, rfc, weblog, features, scenarios
+from utils._weblog import HttpResponse
+
+
+NORMALIZED_ROUTE_TAG = "_dd.appsec.normalized_route"
+HTTP_ROUTE_TAG = "http.route"
+
+# RFC-1103 syntax validator for `_dd.appsec.normalized_route`.
+# Atomic elements are slash-separated; static constants use [A-Za-z0-9.-~_] or
+# percent-encoded sequences; dynamic parameters use {name} where name may
+# contain anything except the six reserved characters /?#+{} (with `+` allowed
+# only as the rule-5 combining marker between framework-supplied subnames).
+# Percent-encoded sequences are accepted in either case (RFC 3986 normalization
+# treats them as equivalent), even though the RFC text recommends uppercase.
+_STATIC_CHAR = r"[A-Za-z0-9.\-~_]|%[0-9A-Fa-f]{2}"
+_PARAM_NAME = r"(?:[^/?#+{}]|%[0-9A-Fa-f]{2})+(?:\+(?:[^/?#+{}]|%[0-9A-Fa-f]{2})+)*"
+_ATOMIC_ELEMENT = rf"(?:(?:{_STATIC_CHAR})+|\{{{_PARAM_NAME}\}})"
+_NORMALIZED_ROUTE_REGEX = re.compile(rf"^/(?:{_ATOMIC_ELEMENT}(?:/{_ATOMIC_ELEMENT})*/?)?$")
+
+
+@rfc("https://docs.google.com/document/d/1XfjniR6v6pL2V5JtxYdpiKbOF08tA9q2Sefk36gtXhs")
+@features.api_security_normalized_route
+@scenarios.appsec_api_security
+class Test_NormalizedRoute:
+    """RFC-1103: tracers emit `_dd.appsec.normalized_route` on every request
+    span that already carries `http.route` when API Security is enabled.
+
+    The tag is a per-request, framework-agnostic representation of the matched
+    route. Rules 1-6 govern leading slash, atomic-element separation,
+    static-constant character set, parameter-name grammar, intra-segment
+    composition and the catch-all tail exception.
+    """
+
+    @staticmethod
+    def _get_meta(response: HttpResponse) -> dict:
+        assert response.status_code == 200, f"unexpected status {response.status_code}: {response!r}"
+        span = interfaces.library.get_root_span(request=response)
+        return span.get("meta", {}) or {}
+
+    @staticmethod
+    def _require_normalized(meta: dict) -> str:
+        # Per RFC, the tag is required whenever `http.route` is present and API
+        # Security is enabled. Surface a clearer message than a None mismatch
+        # when the framework does not (yet) set `http.route` at all.
+        assert meta.get(HTTP_ROUTE_TAG), (
+            f"{HTTP_ROUTE_TAG} not set on entry span; normalized_route contract is conditioned on it"
+        )
+        normalized = meta.get(NORMALIZED_ROUTE_TAG)
+        assert normalized is not None, (
+            f"{NORMALIZED_ROUTE_TAG} must be set when {HTTP_ROUTE_TAG}={meta[HTTP_ROUTE_TAG]!r} "
+            f"and API Security is enabled"
+        )
+        assert isinstance(normalized, str), f"{NORMALIZED_ROUTE_TAG} must be a string, got {type(normalized).__name__}"
+        # Every emitted value must conform to the RFC grammar regardless of the
+        # underlying route shape; a malformed value is a tracer bug.
+        assert _NORMALIZED_ROUTE_REGEX.match(normalized), (
+            f"{NORMALIZED_ROUTE_TAG}={normalized!r} does not conform to RFC-1103 syntax"
+        )
+        return normalized
+
+    def setup_static_route(self):
+        self.r_static = weblog.get("/waf")
+
+    def test_static_route(self):
+        """A static route (no path parameters) normalizes to its literal path.
+
+        `/waf` is declared without parameters across all weblogs, so the
+        normalized route is fully determined by the declaration and must match
+        exactly. This also exercises rule 1 (leading slash) and rule 3
+        (safe-character static constant) without any framework-specific naming.
+        """
+        meta = self._get_meta(self.r_static)
+        normalized = self._require_normalized(meta)
+        assert normalized == "/waf", f"expected '/waf', got {normalized!r}"
+
+    def setup_single_param_route_with_static_prefix(self):
+        # `/sample_rate_route/0` resolves under a static-prefixed parameterized
+        # route. The static prefix `sample_rate_route` lets us also assert
+        # the underscore is preserved as part of rule 3's safe character set.
+        self.r_single_param = weblog.get("/sample_rate_route/0")
+
+    def test_single_param_route_with_static_prefix(self):
+        """Rule 3 + rule 5: underscore stays unencoded in the static segment;
+        the trailing segment is exactly one `{name}` (single-param-per-segment).
+        """
+        meta = self._get_meta(self.r_single_param)
+        normalized = self._require_normalized(meta)
+        # First atomic element is a static constant with an underscore; second
+        # is a single dynamic parameter. Don't pin the param name -- it differs
+        # across framework conventions.
+        assert re.fullmatch(r"/sample_rate_route/\{[^/{}]+\}", normalized), (
+            f"expected '/sample_rate_route/{{<param>}}', got {normalized!r}"
+        )
+
+    def setup_two_param_route(self):
+        # `/tag_value/<tag>/<status>` is declared across every weblog with two
+        # consecutive dynamic parameters in two separate URL segments. Rule 5
+        # then requires one atomic element per segment.
+        self.r_two_param = weblog.get("/tag_value/foo/200")
+
+    def test_two_param_route(self):
+        """Rule 5: two parameters in separate segments yield two atomic dynamic elements.
+
+        The parameter names themselves are framework-supplied (the weblogs use
+        `tag_value`/`status_code` in most stacks but `tag`/`status` in the
+        .NET controller); the contract under test is the structural shape,
+        not the exact names. The names must still conform to the RFC grammar,
+        which the regex validator enforces.
+        """
+        meta = self._get_meta(self.r_two_param)
+        normalized = self._require_normalized(meta)
+        assert re.fullmatch(r"/tag_value/\{[^/{}]+\}/\{[^/{}]+\}", normalized), (
+            f"expected '/tag_value/{{<param1>}}/{{<param2>}}', got {normalized!r}"
+        )
+
+    def setup_query_string_not_in_route(self):
+        # Rule 5 reminder: query parameters must not appear in the normalized
+        # route. The /headers endpoint accepts query parameters but they must
+        # be stripped from the normalized form.
+        self.r_with_qs = weblog.get("/headers?one=1&two=2")
+
+    def test_query_string_not_in_route(self):
+        """Rule 5 reminder: query parameters are not part of the normalized route."""
+        meta = self._get_meta(self.r_with_qs)
+        normalized = self._require_normalized(meta)
+        assert "?" not in normalized, f"query string leaked into normalized route: {normalized!r}"
+        # `/headers` is also declared without parameters across weblogs.
+        assert normalized == "/headers", f"expected '/headers', got {normalized!r}"
diff --git a/utils/_features.py b/utils/_features.py
@@ -2944,5 +2944,16 @@ def api_security_testing_headers_collection(test_object):
         """
         return _mark_test_object(test_object, feature_id=556, owner=_Owner.asm)
 
+    @staticmethod
+    def api_security_normalized_route(test_object):
+        """API Security Testing - Normalized Route: tracers emit a per-request
+        `_dd.appsec.normalized_route` span tag on every request span that already
+        carries `http.route` when API Security is enabled. The tag follows the
+        RFC-1103 normalized-route grammar.
+
+        https://feature-parity.us1.prod.dog/#/?feature=557
+        """
+        return _mark_test_object(test_object, feature_id=557, owner=_Owner.asm)
+
 
 features = _Features()
