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))