Add unified security guide and eliminate raw JSON injection patterns

sean- · sean- · commit 489fc903650e · 2026-05-20T10:45:48.000-07:00
Signed-off-by: Sean Chittenden &lt;sean.chittenden@crowdstrike.com&gt;
diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -510,6 +510,7 @@ All `OPENSEARCH_GO_*` environment variables are evaluated once at client initial
 
 ## Guides by Topic
 
+- [**Security**](guides/security.md) - TLS, credentials, input validation, index patterns, error disclosure
 - [Index Lifecycle](guides/index_lifecycle.md)
 - [Document Lifecycle](guides/document_lifecycle.md)
 - [Search](guides/search.md)
diff --git a/guides/advanced_index_actions.md b/guides/advanced_index_actions.md
@@ -1,5 +1,7 @@
 # Advanced Index Actions
 
+> **Note:** Examples in this guide use raw JSON strings for request bodies because the `opensearchapi` package accepts `io.Reader`. When building bodies from user-supplied values, always use `opensearchutil.NewJSONReader` with a Go struct or map instead of string interpolation. See [Security](security.md#request-body-construction) for details.
+
 In this guide, we will look at some advanced index actions that are not covered in the [Index Lifecycle](index_lifecycle.md) guide.
 
 ## Setup
diff --git a/guides/data_streams.md b/guides/data_streams.md
@@ -1,5 +1,7 @@
 # Data Streams API
 
+> **Note:** Examples in this guide use raw JSON strings for request bodies because the `opensearchapi` package accepts `io.Reader`. When building bodies from user-supplied values, always use `opensearchutil.NewJSONReader` with a Go struct or map instead of string interpolation. See [Security](security.md#request-body-construction) for details.
+
 ## Setup
 
 First, create a client instance with the following code:
diff --git a/guides/document_lifecycle.md b/guides/document_lifecycle.md
@@ -1,5 +1,7 @@
 # Document Lifecycle
 
+> **Note:** Examples in this guide use raw JSON strings for request bodies because the `opensearchapi` package accepts `io.Reader`. When building bodies from user-supplied values, always use `opensearchutil.NewJSONReader` with a Go struct or map instead of string interpolation. See [Security](security.md#request-body-construction) for details.
+
 This guide covers OpenSearch Golang Client API actions for Document Lifecycle. You'll learn how to create, read, update, and delete documents in your OpenSearch cluster. Whether you're new to OpenSearch or an experienced user, this guide provides the information you need to manage your document lifecycle effectively.
 
 ## Setup
diff --git a/guides/error_handling.md b/guides/error_handling.md
@@ -1,5 +1,7 @@
 # Error Handling and Partial Failures
 
+> **Note:** Examples in this guide use raw JSON strings for request bodies because the `opensearchapi` package accepts `io.Reader`. When building bodies from user-supplied values, always use `opensearchutil.NewJSONReader` with a Go struct or map instead of string interpolation. See [Security](security.md#request-body-construction) for details.
+
 ## Overview
 
 OpenSearch is a distributed system in which operations may partially succeed. Understanding how to detect and handle partial failures is essential for building reliable applications.
diff --git a/guides/index_lifecycle.md b/guides/index_lifecycle.md
@@ -1,5 +1,7 @@
 # Index Lifecycle
 
+> **Note:** Examples in this guide use raw JSON strings for request bodies because the `opensearchapi` package accepts `io.Reader`. When building bodies from user-supplied values, always use `opensearchutil.NewJSONReader` with a Go struct or map instead of string interpolation. See [Security](security.md#request-body-construction) for details.
+
 This guide covers OpenSearch Golang Client API actions for Index Lifecycle. You'll learn how to create, get, update settings, update mapping, and delete indices in your OpenSearch cluster. We will also leverage index templates to create default settings and mappings for indices of certain patterns.
 
 ## Setup
diff --git a/guides/index_template.md b/guides/index_template.md
@@ -1,5 +1,7 @@
 # Index Template
 
+> **Note:** Examples in this guide use raw JSON strings for request bodies because the `opensearchapi` package accepts `io.Reader`. When building bodies from user-supplied values, always use `opensearchutil.NewJSONReader` with a Go struct or map instead of string interpolation. See [Security](security.md#request-body-construction) for details.
+
 Index templates are a convenient way to define settings, mappings, and aliases for one or more indices when they are created. In this guide, you'll learn how to create an index template and apply it to an index.
 
 ## Setup
diff --git a/guides/search.md b/guides/search.md
@@ -1,5 +1,7 @@
 # Search
 
+> **Note:** Examples in this guide use `opensearchutil.NewJSONReader` for request bodies that contain dynamic values. For static query strings, raw JSON is acceptable. When building bodies from user-supplied values, always use structured serialization. See [Security](security.md#request-body-construction) for details.
+
 OpenSearch provides a powerful search API that allows you to search for documents in an index. The search API supports a number of parameters that allow you to customize the search operation. In this guide, we will explore the search API and its parameters.
 
 # Setup
@@ -21,6 +23,7 @@ import (
 	"github.com/opensearch-project/opensearch-go/v4"
 	"github.com/opensearch-project/opensearch-go/v4/opensearchapi"
 	"github.com/opensearch-project/opensearch-go/v4/opensearchtransport"
+	"github.com/opensearch-project/opensearch-go/v4/opensearchutil"
 )
 
 func main() {
@@ -78,7 +81,11 @@ For search-heavy applications, you can configure the client to automatically rou
 			opensearchapi.IndexReq{
 				Index:      exampleIndex,
 				DocumentID: strconv.Itoa(i),
-				Body:       strings.NewReader(fmt.Sprintf(`{"title": "The Dark Knight %d", "director": "Christopher Nolan", "year": %d}`, i, 2008+i)),
+				Body: opensearchutil.NewJSONReader(map[string]any{
+					"title":    fmt.Sprintf("The Dark Knight %d", i),
+					"director": "Christopher Nolan",
+					"year":     2008 + i,
+				}),
 			},
 		)
 		if err != nil {
@@ -227,7 +234,12 @@ The scroll example above has one weakness: if the index is updated while you are
 	searchResp, err = client.Search(
 		ctx,
 		&opensearchapi.SearchReq{
-			Body: strings.NewReader(fmt.Sprintf(`{ "pit": { "id": "%s", "keep_alive": "1m" } }`, pitCreateResp.PitID)),
+			Body: opensearchutil.NewJSONReader(map[string]any{
+				"pit": map[string]any{
+					"id":         pitCreateResp.PitID,
+					"keep_alive": "1m",
+				},
+			}),
 			Params: opensearchapi.SearchParams{
 				Size: opensearchapi.ToPointer(5),
 				Sort: []string{"year:desc"},
@@ -246,7 +258,13 @@ The scroll example above has one weakness: if the index is updated while you are
 	searchResp, err = client.Search(
 		ctx,
 		&opensearchapi.SearchReq{
-			Body: strings.NewReader(fmt.Sprintf(`{ "pit": { "id": "%s", "keep_alive": "1m" }, "search_after": [ "1994" ] }`, pitCreateResp.PitID)),
+			Body: opensearchutil.NewJSONReader(map[string]any{
+				"pit": map[string]any{
+					"id":         pitCreateResp.PitID,
+					"keep_alive": "1m",
+				},
+				"search_after": []string{"1994"},
+			}),
 			Params: opensearchapi.SearchParams{
 				Size: opensearchapi.ToPointer(5),
 				Sort: []string{"year:desc"},
diff --git a/guides/security.md b/guides/security.md
diff --git a/guides/tasks.md b/guides/tasks.md
