Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(agent): admit catalog operations only from knowledge API areas (#4317)

lyingbugc40b33ecc34f
diff --git a/internal/agent/operations/catalog.go b/internal/agent/operations/catalog.go
index b127a7c9a..18f0de5fd 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 5df81fb63..5e368fedb 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 aeef0ac0e..96ed446f1 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 168f2a41b..371ed68cc 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))