From c8d43436e2a038088fb76bdb8d8bcb067cd684f9 Mon Sep 17 00:00:00 2001
From: Christophe Papazian <christophe.papazian@datadoghq.com>
Date: Wed, 22 Jul 2026 13:53:48 +0200
Subject: [PATCH] feat(appsec): report DD_APPSEC_AGENTIC_ONBOARDING in config
 telemetry

RFC-1113: register DD_APPSEC_AGENTIC_ONBOARDING as an ordinary string
configuration key so its raw value is reported verbatim in configuration
telemetry. Telemetry-only marker set by the agentic onboarding solution;
carries no behavior. Reported on every app-started, empty with
origin=default when unset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ext/configuration.h                           |  1 +
 metadata/supported-configurations.json        |  7 +++
 .../appsec/agentic_onboarding_is_sent_01.phpt | 36 +++++++++++++
 .../appsec/agentic_onboarding_is_sent_02.phpt | 37 +++++++++++++
 tests/ext/appsec/agentic_onboarding_test.inc  | 54 +++++++++++++++++++
 5 files changed, 135 insertions(+)
 create mode 100644 tests/ext/appsec/agentic_onboarding_is_sent_01.phpt
 create mode 100644 tests/ext/appsec/agentic_onboarding_is_sent_02.phpt
 create mode 100644 tests/ext/appsec/agentic_onboarding_test.inc

diff --git a/ext/configuration.h b/ext/configuration.h
index f3d1b811db9..e68326c8912 100644
--- a/ext/configuration.h
+++ b/ext/configuration.h
@@ -70,6 +70,7 @@ enum datadog_sidecar_connection_mode {
     CONFIG(BOOL, DD_TRACE_FORCE_FLUSH_ON_SIGINT, "false") /* true if pid == 1 || ppid == 1 */                  \
     CONFIG(BOOL, DD_APPSEC_ENABLED, "false", .ini_change = zai_config_system_ini_change)                       \
     CONFIG(BOOL, DD_APPSEC_RASP_ENABLED , "true")                                                              \
+    CONFIG(STRING, DD_APPSEC_AGENTIC_ONBOARDING, "")                                                           \
     CONFIG(INT, DD_TRACE_AGENT_TIMEOUT, DD_CFG_EXPSTR(DD_TRACE_AGENT_TIMEOUT_VAL),                             \
            .ini_change = zai_config_system_ini_change)                                                         \
     CONFIG(INT, DD_TRACE_AGENT_CONNECT_TIMEOUT, DD_CFG_EXPSTR(DD_TRACE_AGENT_CONNECT_TIMEOUT_VAL),             \
diff --git a/metadata/supported-configurations.json b/metadata/supported-configurations.json
index e589ee49431..54a5feb45f6 100644
--- a/metadata/supported-configurations.json
+++ b/metadata/supported-configurations.json
@@ -36,6 +36,13 @@
         "default": "true"
       }
     ],
+    "DD_APPSEC_AGENTIC_ONBOARDING": [
+      {
+        "implementation": "A",
+        "type": "string",
+        "default": ""
+      }
+    ],
     "DD_APPSEC_AUTOMATED_USER_EVENTS_TRACKING_ENABLED": [
       {
         "implementation": "A",
diff --git a/tests/ext/appsec/agentic_onboarding_is_sent_01.phpt b/tests/ext/appsec/agentic_onboarding_is_sent_01.phpt
new file mode 100644
index 00000000000..f43bb0ac86c
--- /dev/null
+++ b/tests/ext/appsec/agentic_onboarding_is_sent_01.phpt
@@ -0,0 +1,36 @@
+--TEST--
+DD_APPSEC_AGENTIC_ONBOARDING flag is sent via telemetry with default (empty) value
+--DESCRIPTION--
+RFC-1113: telemetry-only marker; always reported, empty with origin=default when unset
+--SKIPIF--
+<?php
+if (getenv('PHP_PEAR_RUNTESTS') === '1') die("skip: pecl run-tests does not support {PWD}");
+if (PHP_OS === "WINNT" && PHP_VERSION_ID < 70400) die("skip: Windows on PHP 7.2 and 7.3 have permission issues with synchronous access to telemetry");
+if (getenv('USE_ZEND_ALLOC') === '0' && !getenv("SKIP_ASAN")) die('skip timing sensitive test - valgrind is too slow');
+require __DIR__ . '/../includes/clear_skipif_telemetry.inc'
+?>
+--ENV--
+DD_TRACE_GENERATE_ROOT_SPAN=0
+DD_INSTRUMENTATION_TELEMETRY_ENABLED=1
+--INI--
+datadog.trace.agent_url="file://{PWD}/agentic_onboarding_is_sent_01-telemetry.out"
+--FILE_EXTERNAL--
+agentic_onboarding_test.inc
+--EXPECT--
+array(5) {
+  ["name"]=>
+  string(28) "DD_APPSEC_AGENTIC_ONBOARDING"
+  ["value"]=>
+  string(0) ""
+  ["origin"]=>
+  string(7) "default"
+  ["config_id"]=>
+  NULL
+  ["seq_id"]=>
+  NULL
+}
+string(4) "Sent"
+--CLEAN--
+<?php
+
+@unlink(__DIR__ . '/agentic_onboarding_is_sent_01-telemetry.out');
diff --git a/tests/ext/appsec/agentic_onboarding_is_sent_02.phpt b/tests/ext/appsec/agentic_onboarding_is_sent_02.phpt
new file mode 100644
index 00000000000..a8bd547e60c
--- /dev/null
+++ b/tests/ext/appsec/agentic_onboarding_is_sent_02.phpt
@@ -0,0 +1,37 @@
+--TEST--
+DD_APPSEC_AGENTIC_ONBOARDING flag is sent via telemetry with its raw value
+--DESCRIPTION--
+RFC-1113: telemetry-only marker; the raw string value is reported verbatim with origin=env_var
+--SKIPIF--
+<?php
+if (getenv('PHP_PEAR_RUNTESTS') === '1') die("skip: pecl run-tests does not support {PWD}");
+if (PHP_OS === "WINNT" && PHP_VERSION_ID < 70400) die("skip: Windows on PHP 7.2 and 7.3 have permission issues with synchronous access to telemetry");
+if (getenv('USE_ZEND_ALLOC') === '0' && !getenv("SKIP_ASAN")) die('skip timing sensitive test - valgrind is too slow');
+require __DIR__ . '/../includes/clear_skipif_telemetry.inc'
+?>
+--ENV--
+DD_TRACE_GENERATE_ROOT_SPAN=0
+DD_INSTRUMENTATION_TELEMETRY_ENABLED=1
+DD_APPSEC_AGENTIC_ONBOARDING=true
+--INI--
+datadog.trace.agent_url="file://{PWD}/agentic_onboarding_is_sent_02-telemetry.out"
+--FILE_EXTERNAL--
+agentic_onboarding_test.inc
+--EXPECT--
+array(5) {
+  ["name"]=>
+  string(28) "DD_APPSEC_AGENTIC_ONBOARDING"
+  ["value"]=>
+  string(4) "true"
+  ["origin"]=>
+  string(7) "env_var"
+  ["config_id"]=>
+  NULL
+  ["seq_id"]=>
+  NULL
+}
+string(4) "Sent"
+--CLEAN--
+<?php
+
+@unlink(__DIR__ . '/agentic_onboarding_is_sent_02-telemetry.out');
diff --git a/tests/ext/appsec/agentic_onboarding_test.inc b/tests/ext/appsec/agentic_onboarding_test.inc
new file mode 100644
index 00000000000..89adfc53d22
--- /dev/null
+++ b/tests/ext/appsec/agentic_onboarding_test.inc
@@ -0,0 +1,54 @@
+<?php
+DDTrace\start_span();
+$root = DDTrace\root_span();
+
+$id = basename(__FILE__, ".php");
+
+$root->service = $id.'-telemetry-app';
+$root->meta['env'] = 'test-env';
+
+DDTrace\close_span();
+
+// At this stage, the service and env are stored to be used by telemetry
+dd_trace_serialize_closed_spans();
+
+dd_trace_internal_fn("finalize_telemetry");
+
+for ($i = 0; $i < 300; ++$i) {
+    usleep(100000);
+    if (file_exists(__DIR__ . '/'.$id.'-telemetry.out')) {
+        $batches = [];
+        foreach (file(__DIR__ . '/'.$id.'-telemetry.out') as $l) {
+            if ($l) {
+                $json = json_decode($l, true);
+                if ($json) {
+                    if ($json["application"]["service_name"] == "background_sender-php-service" || $json["application"]["service_name"] == "datadog-ipc-helper") {
+                        continue;
+                    }
+                    array_push($batches, ...($json["request_type"] == "message-batch" ? $json["payload"] : [$json]));
+                }
+            }
+        }
+        $found = array_filter($batches, function ($json) {
+            if ($json["request_type"] !== "app-client-configuration-change") {
+                return false;
+            }
+            foreach($json["payload"]["configuration"] as $configuration) {
+                if (stripos($configuration["name"], "agentic_onboarding") !== false) {
+                    var_dump($configuration);
+                    return true;
+                }
+            }
+            return false;
+        });
+        if (count($found) == 1) {
+            var_dump("Sent");
+            break;
+        }
+    }
+}
+if ($i == 300) {
+    var_dump(file(__DIR__ . '/'.$id.'-telemetry.out'));
+}
+
+?>