From f72213b70f949583523a73aa67697d82e5a997b7 Mon Sep 17 00:00:00 2001
From: Pranav Gupta <pragupta@microsoft.com>
Date: Tue, 16 Dec 2025 11:11:16 +0530
Subject: [PATCH] docs: Add untrusted data security warnings to System.Speech
 APIs

Add untrusted-data-instance-note to APIs that handle external XML/SRGS/SSML/audio files to warn developers about security risks when processing untrusted data.

Changes:
- SrgsDocument: Added class-level warning and warnings to constructors that accept file paths and XmlReader
- Grammar: Added warnings to constructors that accept file paths and streams
- PromptBuilder: Added warnings to AppendSsml(XmlReader) and AppendAudio(string) methods
- GrammarBuilder: Added warnings to AppendRuleReference methods that accept file paths

These APIs can load and parse external files which may contain corrupted or malicious content. The warnings direct developers to validate all inputs per OWASP guidelines.
---
 .../SrgsDocument.xml                                   |  6 ++++++
 xml/System.Speech.Recognition/Grammar.xml              |  8 ++++++++
 xml/System.Speech.Recognition/GrammarBuilder.xml       |  4 ++++
 xml/System.Speech.Synthesis/PromptBuilder.xml          | 10 +++++++++-
 4 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml
index 1c329a5e37b..4b3ca1d838a 100644
--- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml
+++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml
@@ -31,6 +31,8 @@
     <remarks>
       <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  You can you construct an empty <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> instance and build a grammar by adding instances of classes that represent SRGS elements, such as <xref:System.Speech.Recognition.SrgsGrammar.SrgsRule>, <xref:System.Speech.Recognition.SrgsGrammar.SrgsOneOf>,<xref:System.Speech.Recognition.SrgsGrammar.SrgsItem>, <xref:System.Speech.Recognition.SrgsGrammar.SrgsRuleRef>, <xref:System.Speech.Recognition.SrgsGrammar.SrgsSemanticInterpretationTag>, and <xref:System.Speech.Recognition.SrgsGrammar.SrgsToken>. You can also construct an <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> instance from an existing SRGS-compliant XML grammar file, from an instance of <xref:System.Speech.Recognition.SrgsGrammar.SrgsRule>, or from an instance of <xref:System.Speech.Recognition.GrammarBuilder>.
 
@@ -284,6 +286,8 @@ recognizer.LoadGrammarAsync(g);
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Examples
  The following example creates a new <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> from the file named "srgsDocumentFile.xml".
 
@@ -326,6 +330,8 @@ if (File.Exists(srgsDocumentFile))
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Examples
  The following example creates a new instance of <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> from an instance of <xref:System.Xml.XmlReader> that references the file "srgsDocumentFile.xml".
 
diff --git a/xml/System.Speech.Recognition/Grammar.xml b/xml/System.Speech.Recognition/Grammar.xml
index 673bfaebf5d..f724dfc9c10 100644
--- a/xml/System.Speech.Recognition/Grammar.xml
+++ b/xml/System.Speech.Recognition/Grammar.xml
@@ -437,6 +437,8 @@ private static Grammar CreateSrgsDocumentGrammar()
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  This constructor does not pass any parameters to the initialization handler, and the description should not define an initialization handler that requires arguments.
 
@@ -540,6 +542,8 @@ private static Grammar CreateGrammarFromFile()
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  This constructor does not pass any parameters to the initialization handler, and the description should not define an initialization handler that requires arguments.
 
@@ -774,6 +778,8 @@ namespace SampleRecognition
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  This constructor does not pass any parameters to the initialization handler, and the description should not define an initialization handler that requires arguments.
 
@@ -1223,6 +1229,8 @@ private static Grammar CreateSrgsDocumentGrammar3()
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  Parameters for an initialization handler may also be specified.
 
diff --git a/xml/System.Speech.Recognition/GrammarBuilder.xml b/xml/System.Speech.Recognition/GrammarBuilder.xml
index 55d51b26a41..7bbb1c4b7f6 100644
--- a/xml/System.Speech.Recognition/GrammarBuilder.xml
+++ b/xml/System.Speech.Recognition/GrammarBuilder.xml
@@ -2002,6 +2002,8 @@ grammarWithDictation.Name = "Grammar with Dictation";
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  The URI provided by the `path` argument may be local or remote. The application must have read access to the location of specified grammar files.
 
@@ -2089,6 +2091,8 @@ private static Grammar CreateCitiesGrammar1()
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  The URI provided by the `path` argument may be local or remote. The application must have read access to the location of specified grammar files.
 
diff --git a/xml/System.Speech.Synthesis/PromptBuilder.xml b/xml/System.Speech.Synthesis/PromptBuilder.xml
index 9f0a8a7c8a4..1649b671bc8 100644
--- a/xml/System.Speech.Synthesis/PromptBuilder.xml
+++ b/xml/System.Speech.Synthesis/PromptBuilder.xml
@@ -200,7 +200,13 @@ public void MySimpleText ()
       <Docs>
         <param name="path">A fully qualified path to the audio file.</param>
         <summary>Appends the specified audio file to the <see cref="T:System.Speech.Synthesis.PromptBuilder" />.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="AppendAudio">
@@ -960,6 +966,8 @@ namespace SampleSynthesis
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 ## Remarks
  The SSML file must be an XML-format file that conforms to the [Speech Synthesis Markup Language (SSML) Version 1.0](https://www.w3.org/TR/speech-synthesis/) specification.