From c40b33ecc34f5a2c33bc47d33e33c577e2ae1c2d Mon Sep 17 00:00:00 2001 From: lyingbug Date: Thu, 15 Oct 2026 14:20:27 +0800 Subject: [PATCH] fix(agent): admit catalog operations only from knowledge API areas (#4317) The operation catalog refused routes under a list of forbidden prefixes, matched as "" or "/". Areas whose names only extend a listed one passed: /sandbox-configs, /storage-backends, /web-search-providers and /im-channels. Areas nobody listed passed too, including /agent/tool-approvals and /agent/prompts, where an annotated operation would let the assistant answer its own approval prompts. Nothing reachable is annotated today, so this closes the gap before an annotation can open it. The check is now an allow-list of first path segments (knowledge bases, knowledge, Wiki, chunks, FAQ). Anything else, including APIs added later, is refused until listed on purpose. Inside those areas, "shares" is refused: who can reach a knowledge base is the user's decision. --- internal/agent/operations/catalog.go | 67 ++++++++++------------- internal/agent/operations/catalog_test.go | 11 ++++ internal/agent/operations/spec.go | 2 +- internal/agent/operations/spec_test.go | 12 ++-- 4 files changed, 48 insertions(+), 44 deletions(-) diff --git a/internal/agent/operations/catalog.go b/internal/agent/operations/catalog.go index b127a7c9..18f0de5f 100644 --- a/internal/agent/operations/catalog.go +++ b/internal/agent/operations/catalog.go @@ -174,36 +174,26 @@ var ( routeParamPattern = regexp.MustCompile(`^[:*][A-Za-z_][A-Za-z0-9_]*$`) ) -// forbiddenRoutePrefixes are API areas that must never be reachable from an -// agent: credentials, sessions, identity, tenancy administration and the -// agent surfaces themselves. Catalog construction fails if an entry points -// into one, so a careless addition is caught by tests rather than review. -var forbiddenRoutePrefixes = []string{ - "/api/v1/auth", - "/api/v1/tenants", - "/api/v1/users", - "/api/v1/me", - "/api/v1/system", - "/api/v1/initialization", - "/api/v1/organizations", - "/api/v1/api-keys", - "/api/v1/models", - "/api/v1/model-credentials", - "/api/v1/mcp-services", - "/api/v1/mcp-endpoints", - "/api/v1/sandbox", - "/api/v1/skills", - "/api/v1/im", - "/api/v1/embed", - "/api/v1/agents", - "/api/v1/agent-chat", - "/api/v1/knowledge-chat", - "/api/v1/sessions", - "/api/v1/datasource", - "/api/v1/web-search", - "/api/v1/storage", - "/api/v1/vector-stores", - "/api/v1/evaluation", +// allowedRouteAreas are the first path segments under /api/v1 an operation +// may live in: the user's knowledge content. Every other area is refused, +// so an API added later (credentials, integrations, identity, the agent's +// own approval and prompt endpoints) stays unreachable until it is listed +// here on purpose. Catalog construction fails otherwise, so a careless +// annotation is caught by tests rather than review. +var allowedRouteAreas = map[string]bool{ + "knowledge-bases": true, + "shared-knowledge-bases": true, + "knowledge": true, + "knowledgebase": true, // Wiki + "chunks": true, + "faq": true, +} + +// forbiddenRouteSegments are refused anywhere inside an allowed area: +// sharing changes who can reach a knowledge base, which the user does +// themselves. +var forbiddenRouteSegments = map[string]bool{ + "shares": true, } var allowedMethods = map[string]bool{ @@ -447,16 +437,16 @@ func (c *Catalog) validateTarget(op Operation) error { return nil } -// parseRoute checks that route is a clean absolute path under /api/v1 and -// outside the forbidden areas, returning its parameter segment names. +// parseRoute checks that route is a clean absolute path in an allowed area +// under /api/v1, returning its parameter segment names. func parseRoute(route string) (map[string]bool, error) { - if !strings.HasPrefix(route, "/api/v1/") { + const base = "/api/v1/" + if !strings.HasPrefix(route, base) { return nil, fmt.Errorf("route %q must be under /api/v1", route) } - for _, prefix := range forbiddenRoutePrefixes { - if route == prefix || strings.HasPrefix(route, prefix+"/") { - return nil, fmt.Errorf("route %q is in a forbidden area", route) - } + area, _, _ := strings.Cut(strings.TrimPrefix(route, base), "/") + if !allowedRouteAreas[area] { + return nil, fmt.Errorf("route %q is outside the areas an agent may reach", route) } params := map[string]bool{} segments := strings.Split(strings.TrimPrefix(route, "/"), "/") @@ -464,6 +454,9 @@ func parseRoute(route string) (map[string]bool, error) { if seg == "" { return nil, fmt.Errorf("route %q has an empty segment", route) } + if forbiddenRouteSegments[seg] { + return nil, fmt.Errorf("route %q reaches %q, which an agent may not", route, seg) + } if seg[0] == ':' || seg[0] == '*' { if !routeParamPattern.MatchString(seg) { return nil, fmt.Errorf("route %q has an invalid parameter %q", route, seg) diff --git a/internal/agent/operations/catalog_test.go b/internal/agent/operations/catalog_test.go index 5df81fb6..5e368fed 100644 --- a/internal/agent/operations/catalog_test.go +++ b/internal/agent/operations/catalog_test.go @@ -37,6 +37,17 @@ func TestNewCatalogRejectsUnsafeDeclarations(t *testing.T) { "forbidden area": readOp("auth.get", "/api/v1/auth/me"), "api keys": readOp("keys.list", "/api/v1/api-keys"), "outside v1": readOp("x.get", "/health"), + // Areas whose names extend a sensitive one, or that no list named. + "sandbox configs": readOp("x.get", "/api/v1/sandbox-configs"), + "storage backends": readOp("x.get", "/api/v1/storage-backends"), + "web search provider": readOp("x.get", "/api/v1/web-search-providers/types"), + "im channels": readOp("x.get", "/api/v1/im-channels"), + "agent approvals": readOp("x.get", "/api/v1/agent/tool-approvals"), + "memory": readOp("x.get", "/api/v1/memory/items"), + "messages": readOp("x.get", "/api/v1/messages/chat-history-stats"), + "a new area": readOp("x.get", "/api/v1/something-new"), + "kb shares": readOp("x.get", "/api/v1/knowledge-bases/:id/shares", kb), + "kb prefix lookalike": readOp("x.get", "/api/v1/knowledge-bases-admin"), "read as POST": { ID: "x.get", Summary: "s", Risk: RiskRead, Method: http.MethodPost, Route: "/api/v1/knowledge-bases", diff --git a/internal/agent/operations/spec.go b/internal/agent/operations/spec.go index aeef0ac0..96ed446f 100644 --- a/internal/agent/operations/spec.go +++ b/internal/agent/operations/spec.go @@ -102,7 +102,7 @@ var specMethods = []string{"get", "post", "put", "patch", "delete"} // FromSpec compiles the operations a Swagger 2.0 document marks with // x-agent. The result still has to pass NewCatalog, which owns the safety -// rules (forbidden areas, risk versus method, approval targets). +// rules (allowed API areas, risk versus method, approval targets). func FromSpec(document []byte) ([]Operation, error) { var doc specDocument if err := json.Unmarshal(document, &doc); err != nil { diff --git a/internal/agent/operations/spec_test.go b/internal/agent/operations/spec_test.go index 168f2a41..371ed68c 100644 --- a/internal/agent/operations/spec_test.go +++ b/internal/agent/operations/spec_test.go @@ -43,7 +43,7 @@ const testSpec = `{ }} }, "paths": { - "/kbs/{id}/docs": {"get": { + "/knowledge-bases/{id}/docs": {"get": { "summary": "List documents", "description": "Human-facing text.", "x-agent": {"id": "doc.list", "risk": "read"}, @@ -62,7 +62,7 @@ const testSpec = `{ {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/definitions/types.Doc"}}}} ]}}} }}, - "/docs/{id}": { + "/knowledge/{id}": { "get": { "summary": "Get a document", "x-agent": {"id": "doc.get", "risk": "read"}, @@ -83,7 +83,7 @@ const testSpec = `{ }}}} } }, - "/docs/{id}/raw": {"get": { + "/knowledge/{id}/raw": {"get": { "summary": "Not for agents", "parameters": [{"name": "id", "in": "path", "type": "string", "required": true}], "responses": {"200": {"schema": {"type": "string"}}} @@ -107,7 +107,7 @@ func TestFromSpecCompilesAnnotatedOperations(t *testing.T) { list, ok := catalog.Get("doc.list") require.True(t, ok) assert.Equal(t, http.MethodGet, list.Method) - assert.Equal(t, "/api/v1/kbs/:id/docs", list.Route) + assert.Equal(t, "/api/v1/knowledge-bases/:id/docs", list.Route) assert.Equal(t, "List documents", list.Summary) assert.Equal(t, "Model-facing text.", list.Description, "the hint replaces the human description") @@ -196,11 +196,11 @@ func TestFromSpecRejectsBadAnnotations(t *testing.T) { } func TestFromSpecKeepsCatalogSafetyRules(t *testing.T) { - forbidden := strings.Replace(testSpec, `"/docs/{id}": {`, `"/api-keys/{id}": {`, 1) + forbidden := strings.Replace(testSpec, `"/knowledge/{id}": {`, `"/api-keys/{id}": {`, 1) ops, err := FromSpec([]byte(forbidden)) require.NoError(t, err) _, err = NewCatalog(ops...) - assert.ErrorContains(t, err, "forbidden area") + assert.ErrorContains(t, err, "outside the areas an agent may reach") readAsDelete := strings.Replace(testSpec, `"risk": "destructive"`, `"risk": "read"`, 1) ops, err = FromSpec([]byte(readAsDelete))