From 12b08a1636bb80b8bdc8917b64220524235429cc Mon Sep 17 00:00:00 2001 From: mickael emirkanian Date: Tue, 7 Jul 2026 14:49:50 -0400 Subject: [PATCH 1/2] docs(authz): clarify daemon parsing semantics Signed-off-by: mickael emirkanian --- docs/extend/plugins_authorization.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index 8c84d6e384d1..c3509163fdca 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -95,6 +95,12 @@ The Engine's authorization middleware fails closed: when a plugin returns an err the request is denied and the error is surfaced to the client. Plugins should also fail closed: if the plugin cannot confidently evaluate a request, it should return an error or `Allow: false`. +> [!WARNING] +> The plugin receives the [**raw** request body](#authzpluginauthzreq) from the daemon, so the +> plugin must apply the same decoding semantics to ensure it is correctly evaluating +> the request. The daemon decodes JSON **case-insensitively**, **last-one-wins**, +> and does not reject duplicate or case-variant keys. + ### Response body size and partial buffering The internal buffer that holds the response body between the daemon's HTTP From 888ead0aabfa0041bcc86fa0eb8810afb82d48d6 Mon Sep 17 00:00:00 2001 From: mickael emirkanian Date: Wed, 8 Jul 2026 09:53:17 -0400 Subject: [PATCH 2/2] address review comments Signed-off-by: mickael emirkanian --- docs/extend/plugins_authorization.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index c3509163fdca..605fac16fa04 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -96,10 +96,16 @@ the request is denied and the error is surfaced to the client. Plugins should al cannot confidently evaluate a request, it should return an error or `Allow: false`. > [!WARNING] -> The plugin receives the [**raw** request body](#authzpluginauthzreq) from the daemon, so the -> plugin must apply the same decoding semantics to ensure it is correctly evaluating -> the request. The daemon decodes JSON **case-insensitively**, **last-one-wins**, -> and does not reject duplicate or case-variant keys. +> Because the plugin receives the [**raw** request body](#authzpluginauthzreq) from the daemon, it must +> apply the same decoding semantics as the daemon to be sure it evaluates the request the daemon will +> act on. The daemon decodes JSON with Go's [`encoding/json.Unmarshal`](https://pkg.go.dev/encoding/json#Unmarshal). +> +> The same requirement applies to the response body. Plugins that depend on `ResponseBody` +> inspection for redaction or content-filtering should restrict their policies to endpoints +> whose response is produced as a single write (typical of REST-style API responses). For +> commands whose responses are streamed or are likely to exceed the [buffer](#response-body-size-and-partial-buffering) through multiple +> writes, do not rely on `ResponseBody` for security-relevant decisions; perform the filtering +> in a separate layer in front of the daemon. ### Response body size and partial buffering @@ -117,15 +123,6 @@ is the practical effect of this 64 KiB threshold combined with the is immediately drained to the client and is therefore no longer available for plugin inspection by the time the handler returns. -> [!NOTE] -> Plugins that depend on `ResponseBody` inspection for redaction or -> content-filtering should restrict their policies to endpoints whose -> response is produced as a single write (typical of REST-style API -> responses). For commands whose responses are streamed or are likely to -> exceed the buffer through multiple writes, do not rely on `ResponseBody` -> for security-relevant decisions; perform the filtering in a separate -> layer in front of the daemon. - During request/response processing, some authorization flows might need to do additional queries to the Docker daemon. To complete such flows, plugins can call the daemon API similar to a regular user. To enable these