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

The operation catalog refused routes under a list of forbidden prefixes,
matched as "<prefix>" or "<prefix>/". 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.
main
lyingbug 2026-10-15 14:20:27 +08:00 committed by GitHub
parent 33b77f8440
commit c40b33ecc3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 48 additions and 44 deletions

View File

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

View File

@ -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",

View File

@ -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 {

View File

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