feat(judgement): refuse privileged and undeclared actions in chat (#2071)

Connector actions and lookups now declare privilege change and secret access,
and an MCP server declares both per installation. Chat withholds and refuses
any tool that has either effect or declared nothing, in judgement and at
execution, so an approval cannot convert the refusal. Workflows and the
dashboard are unchanged.
This commit is contained in:
sam committed 2026-11-21 21:28:06 +11:00
1 parent 592d36e0d1
commit bc72655c8e
19 files changed
+660 -73

No files matched your search

+35
View File
@@ -454,6 +454,8 @@ components:
ConnectorsEffect:
additionalProperties: false
properties:
Privileged:
$ref: "#/components/schemas/ConnectorsPrivilegedEffects"
ReadOnly:
type: boolean
Reversibility:
@@ -465,6 +467,7 @@ components:
- ReadOnly
- Reversibility
- Summary
- Privileged
type: object
ConnectorsExtensionKind:
additionalProperties: false
@@ -507,6 +510,8 @@ components:
type: object
digest:
type: string
effects:
$ref: "#/components/schemas/ConnectorsServerEffects"
egress:
items:
type: string
@@ -584,6 +589,9 @@ components:
additionalProperties:
type: string
type: object
effects:
$ref: "#/components/schemas/ConnectorsServerEffects"
description: Whether the server's tools change privileges or access secrets. Chat offers a server only when this is declared and both are false.
egress:
items:
type: string
@@ -627,6 +635,31 @@ components:
- name
- state
type: object
ConnectorsPrivilegedEffects:
additionalProperties: false
properties:
declared:
type: boolean
privilege_change:
type: boolean
secret_access:
type: boolean
required:
- declared
type: object
ConnectorsServerEffects:
additionalProperties: false
properties:
privilege_change:
description: The tools grant roles, change identities or policies, or change control-plane settings
type: boolean
secret_access:
description: The tools read, export or reveal secrets
type: boolean
required:
- privilege_change
- secret_access
type: object
ConnectorsSetting:
additionalProperties: false
properties:
@@ -1770,6 +1803,8 @@ components:
type:
- array
- "null"
workflow:
type: string
required:
- id
- run_id
+85 -39
View File
@@ -679,10 +679,13 @@ func (x *DeliveryType) GetInputSchema() []byte {
}
type LookupType struct {
state protoimpl.MessageState `protogen:"open.v1"`
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
InputSchema []byte `protobuf:"bytes,3,opt,name=input_schema,json=inputSchema,proto3" json:"input_schema,omitempty"`
state protoimpl.MessageState `protogen:"open.v1"`
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
InputSchema []byte `protobuf:"bytes,3,opt,name=input_schema,json=inputSchema,proto3" json:"input_schema,omitempty"`
// effect declares the lookup's effects. Only the effects_declared,
// privilege_change and secret_access fields apply to a lookup.
Effect *Effect `protobuf:"bytes,4,opt,name=effect,proto3" json:"effect,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -738,13 +741,30 @@ func (x *LookupType) GetInputSchema() []byte {
return nil
}
func (x *LookupType) GetEffect() *Effect {
if x != nil {
return x.Effect
}
return nil
}
type Effect struct {
state protoimpl.MessageState `protogen:"open.v1"`
ReadOnly bool `protobuf:"varint,1,opt,name=read_only,json=readOnly,proto3" json:"read_only,omitempty"`
Reversibility Reversibility `protobuf:"varint,2,opt,name=reversibility,proto3,enum=connector.v1.Reversibility" json:"reversibility,omitempty"`
// summary says in plain words what the action does, for example "delete
// files older than 24h under /tmp/runner".
Summary string `protobuf:"bytes,3,opt,name=summary,proto3" json:"summary,omitempty"`
Summary string `protobuf:"bytes,3,opt,name=summary,proto3" json:"summary,omitempty"`
// effects_declared says the connector stated this action's privilege_change
// and secret_access explicitly. With it false the two flags mean nothing: an
// action that never stated its effects is prohibited in chat, which is not
// the same as an action that stated it has none.
EffectsDeclared bool `protobuf:"varint,4,opt,name=effects_declared,json=effectsDeclared,proto3" json:"effects_declared,omitempty"`
// privilege_change says the action changes who may do what: it grants
// roles, changes identities or policies, or changes control-plane settings.
PrivilegeChange bool `protobuf:"varint,5,opt,name=privilege_change,json=privilegeChange,proto3" json:"privilege_change,omitempty"`
// secret_access says the action reads, exports or reveals a secret.
SecretAccess bool `protobuf:"varint,6,opt,name=secret_access,json=secretAccess,proto3" json:"secret_access,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -800,6 +820,27 @@ func (x *Effect) GetSummary() string {
return ""
}
func (x *Effect) GetEffectsDeclared() bool {
if x != nil {
return x.EffectsDeclared
}
return false
}
func (x *Effect) GetPrivilegeChange() bool {
if x != nil {
return x.PrivilegeChange
}
return false
}
func (x *Effect) GetSecretAccess() bool {
if x != nil {
return x.SecretAccess
}
return false
}
// Target is what an action acts on. Connector, action, kind and environment
// together are the action class.
type Target struct {
@@ -1757,16 +1798,20 @@ const file_connector_v1_connector_proto_rawDesc = "" +
"\fDeliveryType\x12\x12\n" +
"\x04name\x18\x01 \x01(\tR\x04name\x12 \n" +
"\vdescription\x18\x02 \x01(\tR\vdescription\x12!\n" +
"\finput_schema\x18\x03 \x01(\fR\vinputSchema\"e\n" +
"\finput_schema\x18\x03 \x01(\fR\vinputSchema\"\x93\x01\n" +
"\n" +
"LookupType\x12\x12\n" +
"\x04name\x18\x01 \x01(\tR\x04name\x12 \n" +
"\vdescription\x18\x02 \x01(\tR\vdescription\x12!\n" +
"\finput_schema\x18\x03 \x01(\fR\vinputSchema\"\x82\x01\n" +
"\finput_schema\x18\x03 \x01(\fR\vinputSchema\x12,\n" +
"\x06effect\x18\x04 \x01(\v2\x14.connector.v1.EffectR\x06effect\"\xfd\x01\n" +
"\x06Effect\x12\x1b\n" +
"\tread_only\x18\x01 \x01(\bR\breadOnly\x12A\n" +
"\rreversibility\x18\x02 \x01(\x0e2\x1b.connector.v1.ReversibilityR\rreversibility\x12\x18\n" +
"\asummary\x18\x03 \x01(\tR\asummary\"n\n" +
"\asummary\x18\x03 \x01(\tR\asummary\x12)\n" +
"\x10effects_declared\x18\x04 \x01(\bR\x0feffectsDeclared\x12)\n" +
"\x10privilege_change\x18\x05 \x01(\bR\x0fprivilegeChange\x12#\n" +
"\rsecret_access\x18\x06 \x01(\bR\fsecretAccess\"n\n" +
"\x06Target\x12\x12\n" +
"\x04kind\x18\x01 \x01(\tR\x04kind\x12\x0e\n" +
"\x02id\x18\x02 \x01(\tR\x02id\x12 \n" +
@@ -1914,37 +1959,38 @@ var file_connector_v1_connector_proto_depIdxs = []int32{
6, // 6: connector.v1.DescribeResponse.settings:type_name -> connector.v1.Setting
0, // 7: connector.v1.Setting.type:type_name -> connector.v1.SettingType
11, // 8: connector.v1.ActionType.effect:type_name -> connector.v1.Effect
1, // 9: connector.v1.Effect.reversibility:type_name -> connector.v1.Reversibility
30, // 10: connector.v1.ParseRequest.headers:type_name -> connector.v1.ParseRequest.HeadersEntry
15, // 11: connector.v1.ParseResponse.events:type_name -> connector.v1.Event
31, // 12: connector.v1.Event.occurred_at:type_name -> google.protobuf.Timestamp
12, // 13: connector.v1.ResolveResponse.target:type_name -> connector.v1.Target
11, // 14: connector.v1.ResolveResponse.effect:type_name -> connector.v1.Effect
12, // 15: connector.v1.TargetFactsRequest.target:type_name -> connector.v1.Target
15, // 16: connector.v1.ListenResponse.events:type_name -> connector.v1.Event
2, // 17: connector.v1.ConnectorService.Configure:input_type -> connector.v1.ConfigureRequest
4, // 18: connector.v1.ConnectorService.Describe:input_type -> connector.v1.DescribeRequest
13, // 19: connector.v1.ConnectorService.Parse:input_type -> connector.v1.ParseRequest
16, // 20: connector.v1.ConnectorService.Resolve:input_type -> connector.v1.ResolveRequest
18, // 21: connector.v1.ConnectorService.Invoke:input_type -> connector.v1.InvokeRequest
20, // 22: connector.v1.ConnectorService.Lookup:input_type -> connector.v1.LookupRequest
22, // 23: connector.v1.ConnectorService.Deliver:input_type -> connector.v1.DeliverRequest
26, // 24: connector.v1.ConnectorService.Listen:input_type -> connector.v1.ListenRequest
24, // 25: connector.v1.ConnectorService.TargetFacts:input_type -> connector.v1.TargetFactsRequest
3, // 26: connector.v1.ConnectorService.Configure:output_type -> connector.v1.ConfigureResponse
5, // 27: connector.v1.ConnectorService.Describe:output_type -> connector.v1.DescribeResponse
14, // 28: connector.v1.ConnectorService.Parse:output_type -> connector.v1.ParseResponse
17, // 29: connector.v1.ConnectorService.Resolve:output_type -> connector.v1.ResolveResponse
19, // 30: connector.v1.ConnectorService.Invoke:output_type -> connector.v1.InvokeResponse
21, // 31: connector.v1.ConnectorService.Lookup:output_type -> connector.v1.LookupResponse
23, // 32: connector.v1.ConnectorService.Deliver:output_type -> connector.v1.DeliverResponse
27, // 33: connector.v1.ConnectorService.Listen:output_type -> connector.v1.ListenResponse
25, // 34: connector.v1.ConnectorService.TargetFacts:output_type -> connector.v1.TargetFactsResponse
26, // [26:35] is the sub-list for method output_type
17, // [17:26] is the sub-list for method input_type
17, // [17:17] is the sub-list for extension type_name
17, // [17:17] is the sub-list for extension extendee
0, // [0:17] is the sub-list for field type_name
11, // 9: connector.v1.LookupType.effect:type_name -> connector.v1.Effect
1, // 10: connector.v1.Effect.reversibility:type_name -> connector.v1.Reversibility
30, // 11: connector.v1.ParseRequest.headers:type_name -> connector.v1.ParseRequest.HeadersEntry
15, // 12: connector.v1.ParseResponse.events:type_name -> connector.v1.Event
31, // 13: connector.v1.Event.occurred_at:type_name -> google.protobuf.Timestamp
12, // 14: connector.v1.ResolveResponse.target:type_name -> connector.v1.Target
11, // 15: connector.v1.ResolveResponse.effect:type_name -> connector.v1.Effect
12, // 16: connector.v1.TargetFactsRequest.target:type_name -> connector.v1.Target
15, // 17: connector.v1.ListenResponse.events:type_name -> connector.v1.Event
2, // 18: connector.v1.ConnectorService.Configure:input_type -> connector.v1.ConfigureRequest
4, // 19: connector.v1.ConnectorService.Describe:input_type -> connector.v1.DescribeRequest
13, // 20: connector.v1.ConnectorService.Parse:input_type -> connector.v1.ParseRequest
16, // 21: connector.v1.ConnectorService.Resolve:input_type -> connector.v1.ResolveRequest
18, // 22: connector.v1.ConnectorService.Invoke:input_type -> connector.v1.InvokeRequest
20, // 23: connector.v1.ConnectorService.Lookup:input_type -> connector.v1.LookupRequest
22, // 24: connector.v1.ConnectorService.Deliver:input_type -> connector.v1.DeliverRequest
26, // 25: connector.v1.ConnectorService.Listen:input_type -> connector.v1.ListenRequest
24, // 26: connector.v1.ConnectorService.TargetFacts:input_type -> connector.v1.TargetFactsRequest
3, // 27: connector.v1.ConnectorService.Configure:output_type -> connector.v1.ConfigureResponse
5, // 28: connector.v1.ConnectorService.Describe:output_type -> connector.v1.DescribeResponse
14, // 29: connector.v1.ConnectorService.Parse:output_type -> connector.v1.ParseResponse
17, // 30: connector.v1.ConnectorService.Resolve:output_type -> connector.v1.ResolveResponse
19, // 31: connector.v1.ConnectorService.Invoke:output_type -> connector.v1.InvokeResponse
21, // 32: connector.v1.ConnectorService.Lookup:output_type -> connector.v1.LookupResponse
23, // 33: connector.v1.ConnectorService.Deliver:output_type -> connector.v1.DeliverResponse
27, // 34: connector.v1.ConnectorService.Listen:output_type -> connector.v1.ListenResponse
25, // 35: connector.v1.ConnectorService.TargetFacts:output_type -> connector.v1.TargetFactsResponse
27, // [27:36] is the sub-list for method output_type
18, // [18:27] is the sub-list for method input_type
18, // [18:18] is the sub-list for extension type_name
18, // [18:18] is the sub-list for extension extendee
0, // [0:18] is the sub-list for field type_name
}
func init() { file_connector_v1_connector_proto_init() }
@@ -0,0 +1,8 @@
-- +goose Up
-- The privileged effects an operator declared for an MCP server: a JSON object
-- with privilege_change and secret_access. Null means nothing is declared, and
-- chat doesn't offer the server's tools.
ALTER TABLE connectors.accepted ADD COLUMN effects jsonb;
-- +goose Down
ALTER TABLE connectors.accepted DROP COLUMN effects;
+12 -8
View File
@@ -91,8 +91,8 @@ func TestTurnActsWithItsOwnersAccess(t *testing.T) {
Toolbox: fakeToolbox{}, Judge: fakeJudge{}, Memory: fakeMemory{},
}
m := &Module{orgID: "default", store: &fakeStore{sessions: map[uuid.UUID]store.Session{}, turns: map[uuid.UUID]store.Turn{}, events: map[uuid.UUID][]store.Event{}}, log: slog.New(slog.DiscardHandler), hub: hub.New()}
action := connectors.Declaration{Connector: "pager", Kind: connectors.KindAction, Name: "page"}
lookup := connectors.Declaration{Connector: "pager", Kind: connectors.KindLookup, Name: "who"}
action := connectors.Declaration{Connector: "pager", Privileged: noPrivilegedEffects, Kind: connectors.KindAction, Name: "page"}
lookup := connectors.Declaration{Connector: "pager", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "who"}
cases := []struct {
name, owner string
run func(context.Context) error
@@ -232,7 +232,7 @@ func TestOmittedToolCannotRun(t *testing.T) {
if err != nil {
t.Fatal(err)
}
decl := connectors.Declaration{Connector: "pager", Kind: connectors.KindLookup, Name: "who"}
decl := connectors.Declaration{Connector: "pager", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "who"}
if _, err := m.call(ctx, d, store.Turn{ID: uuid.New()}, decl, jsontext.Value(`{}`)); !errors.Is(err, errToolUnavailable) {
t.Fatalf("call error = %v, want %v", err, errToolUnavailable)
}
@@ -309,9 +309,9 @@ type collisionBox struct{}
func (collisionBox) Declarations() []connectors.Declaration {
return []connectors.Declaration{
{Connector: "a_b", Kind: connectors.KindLookup, Name: "c"},
{Connector: "a", Kind: connectors.KindLookup, Name: "b_c"},
{Connector: "run", Kind: connectors.KindLookup, Name: "list"},
{Connector: "a_b", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "c"},
{Connector: "a", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "b_c"},
{Connector: "run", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "list"},
}
}
func (collisionBox) Tool(string) (connectors.Tool, bool) { return fakeTool{}, true }
@@ -406,8 +406,8 @@ type fakeToolbox struct{ Toolbox }
func (fakeToolbox) Declarations() []connectors.Declaration {
return []connectors.Declaration{
{Connector: "pager", Kind: connectors.KindAction, Name: "page", Description: "Page the on-call person", Schema: jsontext.Value(`{"type":"object"}`)},
{Connector: "pager", Kind: connectors.KindLookup, Name: "who", Description: "Who is on call", Schema: jsontext.Value(`{"type":"object"}`)},
{Connector: "pager", Privileged: noPrivilegedEffects, Kind: connectors.KindAction, Name: "page", Description: "Page the on-call person", Schema: jsontext.Value(`{"type":"object"}`)},
{Connector: "pager", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "who", Description: "Who is on call", Schema: jsontext.Value(`{"type":"object"}`)},
}
}
@@ -565,3 +565,7 @@ func (f *fakeStore) Events(_ context.Context, turn uuid.UUID, after int64) ([]st
func (f *fakeStore) EventsOf(context.Context, uuid.UUID, []string) ([]store.Event, error) {
return nil, nil
}
// noPrivilegedEffects is a declaration that states it has no privileged effect,
// the only kind chat offers.
var noPrivilegedEffects = connectors.PrivilegedEffects{Declared: true}
+81
View File
@@ -0,0 +1,81 @@
package chat
import (
"encoding/json/jsontext"
"errors"
"log/slog"
"testing"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/platform/hub"
"github.com/samcharles93/archie-core/modules/chat/internal/store"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/governance"
)
type effectsBox struct {
decls []connectors.Declaration
tool *countingTool
}
func (b effectsBox) Declarations() []connectors.Declaration { return b.decls }
func (b effectsBox) Tool(string) (connectors.Tool, bool) { return b.tool, true }
// TestChatOffersAndRunsOnlyDeclaredHarmlessTools guards the chat prohibition:
// even for the organisation owner, a tool that changes privileges, accesses
// secrets or never declared its effects is not described to the model, and a
// call to it is refused before anything runs, including a call made with a
// declaration that was harmless when it was offered.
func TestChatOffersAndRunsOnlyDeclaredHarmlessTools(t *testing.T) {
declare := func(name string, p connectors.PrivilegedEffects) connectors.Declaration {
return connectors.Declaration{Connector: "iam", Kind: connectors.KindLookup, Name: name, Privileged: p}
}
tests := []struct {
name string
decl connectors.Declaration
offered bool
}{
{name: "declared harmless", decl: declare("who", noPrivilegedEffects), offered: true},
{name: "privilege change", decl: declare("grant", connectors.PrivilegedEffects{Declared: true, PrivilegeChange: true})},
{name: "secret access", decl: declare("export", connectors.PrivilegedEffects{Declared: true, SecretAccess: true})},
{name: "never declared", decl: declare("legacy", connectors.PrivilegedEffects{})},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
people := fakePeople{alice: person(alice, governance.RoleOwner)}
box := effectsBox{decls: []connectors.Declaration{tt.decl}, tool: &countingTool{}}
d := Deps{People: people, Access: governance.NewEngine(governance.ShippedOrgPolicies(governance.DefaultOrgID)), Toolbox: box}
m := &Module{
orgID: "default", log: slog.New(slog.DiscardHandler), hub: hub.New(),
store: &fakeStore{sessions: map[uuid.UUID]store.Session{}, turns: map[uuid.UUID]store.Turn{}, events: map[uuid.UUID][]store.Event{}},
}
ctx, err := m.actingAs(t.Context(), d, alice)
if err != nil {
t.Fatal(err)
}
turn := store.Turn{ID: uuid.New(), SessionID: uuid.New(), Owner: alice}
if _, ok := m.tools(ctx, d, turn)[toolName("iam", tt.decl.Name)]; ok != tt.offered {
t.Fatalf("offered = %v, want %v", ok, tt.offered)
}
// The model can name a tool that was never offered, or one whose
// declaration changed after it was offered.
stale := tt.decl
stale.Privileged = noPrivilegedEffects
_, err = m.call(ctx, d, turn, stale, jsontext.Value(`{}`))
if tt.offered {
if err != nil {
t.Fatalf("call = %v, want it to run", err)
}
return
}
if !errors.Is(err, errToolProhibited) {
t.Fatalf("call = %v, want %v", err, errToolProhibited)
}
if box.tool.lookups != 0 {
t.Fatalf("a prohibited tool ran %d times", box.tool.lookups)
}
})
}
}
+3 -3
View File
@@ -79,11 +79,11 @@ func taintDeps(t *testing.T, fs *fakeStore, box Toolbox, judge *taintJudge) (*Mo
}
func untrustedLookup() connectors.Declaration {
return connectors.Declaration{Connector: "web", Kind: connectors.KindLookup, Name: "fetch", Schema: jsontext.Value(`{"type":"object"}`)}
return connectors.Declaration{Connector: "web", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "fetch", Schema: jsontext.Value(`{"type":"object"}`)}
}
func untrustedAction() connectors.Declaration {
return connectors.Declaration{Connector: "mail", Kind: connectors.KindAction, Name: "send", Schema: jsontext.Value(`{"type":"object"}`)}
return connectors.Declaration{Connector: "mail", Privileged: noPrivilegedEffects, Kind: connectors.KindAction, Name: "send", Schema: jsontext.Value(`{"type":"object"}`)}
}
// TestUntrustedOutputTaintsTheSession guards requirement 1 and 2: output from
@@ -95,7 +95,7 @@ func TestUntrustedOutputTaintsTheSession(t *testing.T) {
judge := &taintJudge{level: judgement.ActQuietly}
box := trustBox{decls: []connectors.Declaration{
untrustedLookup(),
{Connector: "internal", Kind: connectors.KindLookup, Name: "runs", TrustLevel: connectors.TrustTrusted, Schema: jsontext.Value(`{"type":"object"}`)},
{Connector: "internal", Privileged: noPrivilegedEffects, Kind: connectors.KindLookup, Name: "runs", TrustLevel: connectors.TrustTrusted, Schema: jsontext.Value(`{"type":"object"}`)},
}}
m, d, session := taintDeps(t, fs, box, judge)
ctx, err := m.actingAs(t.Context(), d, alice)
+20 -8
View File
@@ -22,7 +22,7 @@ import (
)
// principal is who hard rules see acting when the chat agent calls an action.
const principal = "chat"
const principal = judgement.ChatWorkflow
// actingAs is ctx carrying the principal of owner, the person whose
// conversation it is, as a request they made would carry it. It is read from
@@ -87,6 +87,9 @@ func (m *Module) tools(ctx context.Context, d Deps, t store.Turn) core.ToolSet {
// the name is withheld from both.
ambiguous := map[string]bool{}
for _, decl := range d.Toolbox.Declarations() {
if decl.Privileged.ProhibitedInChat() {
continue
}
need := governance.ActionRun
if decl.Kind == connectors.KindLookup {
need = governance.ActionRead
@@ -143,16 +146,21 @@ func toolSummaries(set core.ToolSet) []prompts.ChatTool {
// else exists.
var errToolUnavailable = errors.New("that tool isn't available right now")
// declared reports whether the running registry still declares exactly the
// tool this call was offered for. A connector that stopped, or was replaced by
// one declaring fewer tools, leaves the old call refused.
func declared(d Deps, decl connectors.Declaration) bool {
// errToolProhibited refuses a call to a tool chat never runs: one that changes
// privileges, accesses secrets or doesn't declare its effects.
var errToolProhibited = errors.New("chat can't run that tool: it changes privileges, accesses secrets or doesn't declare its effects. Use the dashboard")
// declared returns what the running registry declares now for the tool this
// call was offered for. A connector that stopped, or was replaced by one
// declaring fewer tools, leaves the old call refused. The effects are read
// from the running declaration, not the one the call was offered with.
func declared(d Deps, decl connectors.Declaration) (connectors.Declaration, bool) {
for _, current := range d.Toolbox.Declarations() {
if current.Connector == decl.Connector && current.Name == decl.Name && current.Kind == decl.Kind {
return true
return current, true
}
}
return false
return connectors.Declaration{}, false
}
// call runs a lookup, or judges an action and runs it only as decided. An
@@ -166,9 +174,13 @@ func (m *Module) call(ctx context.Context, d Deps, t store.Turn, decl connectors
if err := m.allowed(ctx, d, need, governance.KindConnector, decl.Connector); err != nil {
return "", err
}
if !declared(d, decl) {
current, ok := declared(d, decl)
if !ok {
return "", errToolUnavailable
}
if current.Privileged.ProhibitedInChat() {
return "", errToolProhibited
}
tool, ok := d.Toolbox.Tool(decl.Connector)
if !ok {
return "", errToolUnavailable
+45 -4
View File
@@ -49,11 +49,30 @@ const (
Irreversible
)
// PrivilegedEffects is what a tool states about the effects that chat never
// performs. Declared separates a tool that states it has none from one that
// never said, so a tool that is silent is not read as harmless.
type PrivilegedEffects struct {
Declared bool `json:"declared"`
// PrivilegeChange grants roles, changes identities or policies, or changes
// control-plane settings.
PrivilegeChange bool `json:"privilege_change,omitzero"`
// SecretAccess reads, exports or reveals a secret.
SecretAccess bool `json:"secret_access,omitzero"`
}
// ProhibitedInChat reports whether a chat turn may neither be offered nor run
// the tool: it has a privileged effect, or it never declared whether it does.
func (p PrivilegedEffects) ProhibitedInChat() bool {
return !p.Declared || p.PrivilegeChange || p.SecretAccess
}
// Effect describes what one action does.
type Effect struct {
ReadOnly bool
Reversibility Reversibility
Summary string
Privileged PrivilegedEffects
}
// Target is what an action acts on. Connector, action, kind and environment
@@ -96,6 +115,7 @@ type action struct {
}
type lookup struct {
privileged PrivilegedEffects
input *jsonschema.Resolved
description string
schema jsontext.Value
@@ -110,6 +130,9 @@ type Declaration struct {
Description string `json:"description"`
Schema jsontext.Value `json:"schema"`
ReadOnly bool `json:"read_only"`
// Privileged states whether the tool changes privileges or accesses
// secrets. Chat is offered only a tool that declared it does neither.
Privileged PrivilegedEffects `json:"privileged"`
// TrustLevel says whether the tool's output is trusted internal content.
// Anything but TrustTrusted, including empty, is treated as untrusted.
TrustLevel string `json:"trust_level,omitempty"`
@@ -213,7 +236,10 @@ func (c *Connector) load(desc *pb.DescribeResponse) error {
if err != nil {
return fmt.Errorf("connector %q: lookup %q: %w", c.name, l.GetName(), err)
}
c.lookups[l.GetName()] = lookup{input: s, description: l.GetDescription(), schema: schemaOrEmpty(l.GetInputSchema())}
c.lookups[l.GetName()] = lookup{
input: s, description: l.GetDescription(), schema: schemaOrEmpty(l.GetInputSchema()),
privileged: effectFrom(l.GetEffect()).Privileged,
}
}
for _, d := range desc.GetDeliveries() {
s, err := compile(d.GetInputSchema())
@@ -329,12 +355,14 @@ func (c *Connector) Declarations() []Declaration {
l := c.lookups[name]
out = append(out, Declaration{
Connector: c.name, Kind: KindLookup, Name: name, Description: l.description, Schema: l.schema, ReadOnly: true,
Privileged: l.privileged,
})
}
for _, name := range slices.Sorted(maps.Keys(c.actions)) {
a := c.actions[name]
out = append(out, Declaration{
Connector: c.name, Kind: KindAction, Name: name, Description: a.description, Schema: a.schema, ReadOnly: a.effect.ReadOnly,
Privileged: a.effect.Privileged,
})
}
return out
@@ -385,7 +413,8 @@ func (c *Connector) events(wire []*pb.Event) ([]Event, error) {
// Resolve returns the target and effect of one concrete action.
func (c *Connector) Resolve(ctx context.Context, name string, input jsontext.Value) (Resolution, error) {
if _, err := c.action(name, input); err != nil {
declared, err := c.action(name, input)
if err != nil {
return Resolution{}, err
}
req := &pb.ResolveRequest{Action: name, Input: input}
@@ -395,9 +424,18 @@ func (c *Connector) Resolve(ctx context.Context, name string, input jsontext.Val
return Resolution{}, fmt.Errorf("connector %q: resolve %q: %w", c.name, name, err)
}
t := resp.GetTarget()
effect := effectFrom(resp.GetEffect())
// What the action declared holds for every input. A resolution can add a
// privileged effect for this input but can't remove one or declare none
// for an action that never declared.
effect.Privileged = PrivilegedEffects{
Declared: declared.effect.Privileged.Declared,
PrivilegeChange: declared.effect.Privileged.PrivilegeChange || effect.Privileged.PrivilegeChange,
SecretAccess: declared.effect.Privileged.SecretAccess || effect.Privileged.SecretAccess,
}
return Resolution{
Target: Target{Kind: t.GetKind(), ID: t.GetId(), Environment: t.GetEnvironment(), Disposable: t.GetDisposable()},
Effect: effectFrom(resp.GetEffect()),
Effect: effect,
}, nil
}
@@ -486,7 +524,10 @@ func Canonical(input jsontext.Value) jsontext.Value {
}
func effectFrom(e *pb.Effect) Effect {
return Effect{ReadOnly: e.GetReadOnly(), Reversibility: Reversibility(e.GetReversibility()), Summary: e.GetSummary()}
return Effect{
ReadOnly: e.GetReadOnly(), Reversibility: Reversibility(e.GetReversibility()), Summary: e.GetSummary(),
Privileged: PrivilegedEffects{Declared: e.GetEffectsDeclared(), PrivilegeChange: e.GetPrivilegeChange(), SecretAccess: e.GetSecretAccess()},
}
}
func schemaOrEmpty(raw []byte) jsontext.Value {
+8 -4
View File
@@ -36,6 +36,10 @@ type Accepted struct {
// Tools are the lookups and actions an MCP server's acceptance declares,
// as a JSON array.
Tools jsontext.Value `db:"tools"`
// Effects is an MCP server's declared privileged effects, as a JSON
// object. It is nil until the operator declares them. A []byte for the
// same reason as Capabilities.
Effects []byte `db:"effects"`
// Capabilities is what a connector declared when it last loaded, as a JSON
// object. It is nil until then, and acceptance never changes it. It is a
// []byte because database/sql scans NULL into []byte but not into a named
@@ -109,7 +113,7 @@ func New(db *sqlx.DB) *Store { return &Store{db: db} }
func (s *Store) List(ctx context.Context, orgID string) ([]Accepted, error) {
var out []Accepted
if err := s.db.SelectContext(ctx, &out, `
SELECT org_id, name, path, sha256, egress, env, settings, contract, credentials, args, url, tools, capabilities
SELECT org_id, name, path, sha256, egress, env, settings, contract, credentials, args, url, tools, effects, capabilities
FROM connectors.accepted WHERE org_id = $1 ORDER BY name`, orgID); err != nil {
return nil, fmt.Errorf("list connectors: %w", err)
}
@@ -122,13 +126,13 @@ func (s *Store) Upsert(ctx context.Context, a Accepted) error {
return fmt.Errorf("accept %q: unknown contract %q", a.Name, a.Contract)
}
if _, err := s.db.NamedExecContext(ctx, `
INSERT INTO connectors.accepted (org_id, name, path, sha256, egress, env, settings, contract, credentials, args, url, tools)
VALUES (:org_id, :name, :path, :sha256, :egress, :env, :settings, :contract, :credentials, :args, :url, :tools)
INSERT INTO connectors.accepted (org_id, name, path, sha256, egress, env, settings, contract, credentials, args, url, tools, effects)
VALUES (:org_id, :name, :path, :sha256, :egress, :env, :settings, :contract, :credentials, :args, :url, :tools, :effects)
ON CONFLICT (org_id, name) DO UPDATE
SET path = EXCLUDED.path, sha256 = EXCLUDED.sha256, egress = EXCLUDED.egress,
env = EXCLUDED.env, settings = EXCLUDED.settings, contract = EXCLUDED.contract,
credentials = EXCLUDED.credentials, args = EXCLUDED.args, url = EXCLUDED.url,
tools = EXCLUDED.tools, updated_at = now()`, a); err != nil {
tools = EXCLUDED.tools, effects = EXCLUDED.effects, updated_at = now()`, a); err != nil {
return fmt.Errorf("accept connector: %w", err)
}
return nil
+9
View File
@@ -34,6 +34,9 @@ type ExtensionView struct {
SettingsSchema []Setting `json:"settings_schema"`
Credentials map[string]string `json:"credentials"`
Tools jsontext.Value `json:"tools,omitempty"`
// Effects is an MCP server's declaration of its privileged effects; absent
// until declared.
Effects *ServerEffects `json:"effects,omitempty"`
// Capabilities is what a connector declared when it last loaded. It is
// absent for other packages and for a connector that has never loaded.
Capabilities *Capabilities `json:"capabilities,omitempty"`
@@ -79,6 +82,12 @@ func (m *Module) viewOf(a store.Accepted) (ExtensionView, error) {
return ExtensionView{}, fmt.Errorf("credentials: %w", err)
}
}
if len(a.Effects) > 0 {
view.Effects = new(ServerEffects)
if err := json.Unmarshal(a.Effects, view.Effects); err != nil {
return ExtensionView{}, fmt.Errorf("effects: %w", err)
}
}
if len(a.Capabilities) > 0 {
view.Capabilities = new(Capabilities)
if err := json.Unmarshal(a.Capabilities, view.Capabilities); err != nil {
+9 -5
View File
@@ -66,6 +66,9 @@ type ServerSpec struct {
SecretHeaders map[string]string
// Tools are the tools the acceptance permits.
Tools []ToolDecl
// Privileged is what the operator declared about the whole server: every
// tool it offers carries it.
Privileged PrivilegedEffects
}
// ToolDecl is one tool an acceptance permits: a lookup, or an action with the
@@ -81,10 +84,11 @@ type ToolDecl struct {
}
// effect is what the declaration says the tool does. Its reversibility and
// summary are kept for judgement, which is what runs an action.
func (d ToolDecl) effect() Effect {
// summary are kept for judgement, which is what runs an action. privileged is
// the server's declaration, which the tool inherits.
func (d ToolDecl) effect(privileged PrivilegedEffects) Effect {
r, _ := reversibility(d.Reversibility)
return Effect{ReadOnly: d.Kind == KindLookup || d.ReadOnly, Reversibility: r, Summary: d.Summary}
return Effect{ReadOnly: d.Kind == KindLookup || d.ReadOnly, Reversibility: r, Summary: d.Summary, Privileged: privileged}
}
// mcpTool is one declared tool as the server lists it.
@@ -145,7 +149,7 @@ func (s *Server) Declarations() []Declaration {
t := s.tools[name]
out = append(out, Declaration{
Connector: s.name, Kind: t.kind, Name: name,
Description: t.description, Schema: t.schema, ReadOnly: t.effect.ReadOnly,
Description: t.description, Schema: t.schema, ReadOnly: t.effect.ReadOnly, Privileged: t.effect.Privileged,
})
}
return out
@@ -294,7 +298,7 @@ func (s *Server) declared(ctx context.Context, cs *sdk.ClientSession) (map[strin
return nil, fmt.Errorf("mcp server %q: tool %q: %w", s.name, d.Name, err)
}
out[d.Name] = mcpTool{
kind: d.Kind, effect: d.effect(), description: t.Description,
kind: d.Kind, effect: d.effect(s.spec.Privileged), description: t.Description,
input: resolved, schema: schema,
}
}
+33 -1
View File
@@ -2,6 +2,7 @@ package connectors
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
@@ -46,6 +47,24 @@ type mcpRequest struct {
Credentials map[string]string `json:"credentials,omitzero"`
// Tools are the tools the server may offer, and nothing else is offered.
Tools []ToolDecl `json:"tools,omitzero"`
// Effects declares whether the server's tools change privileges or access
// secrets. A server that declares nothing is not offered to chat.
Effects *ServerEffects `json:"effects,omitzero" doc:"Whether the server's tools change privileges or access secrets. Chat offers a server only when this is declared and both are false."`
}
// ServerEffects is an operator's declaration of the privileged effects of an
// MCP server's tools.
type ServerEffects struct {
PrivilegeChange bool `json:"privilege_change" doc:"The tools grant roles, change identities or policies, or change control-plane settings"`
SecretAccess bool `json:"secret_access" doc:"The tools read, export or reveal secrets"`
}
// privileged is the declaration as tools carry it; nil is not declared.
func (e *ServerEffects) privileged() PrivilegedEffects {
if e == nil {
return PrivilegedEffects{}
}
return PrivilegedEffects{Declared: true, PrivilegeChange: e.PrivilegeChange, SecretAccess: e.SecretAccess}
}
// check refuses an acceptance that couldn't work, before anything is stored.
@@ -180,10 +199,16 @@ func (r mcpRequest) accepted(orgID, name string) (store.Accepted, error) {
if err != nil {
return store.Accepted{}, err
}
var effects jsontext.Value
if r.Effects != nil {
if effects, err = json.Marshal(r.Effects); err != nil {
return store.Accepted{}, err
}
}
return store.Accepted{
OrgID: orgID, Name: name, Contract: store.ContractMCP,
Path: r.Path, SHA256: r.SHA256, URL: r.URL, Args: r.Args,
Env: r.Env, Egress: r.Egress, Settings: settings, Credentials: slots, Tools: tools,
Env: r.Env, Egress: r.Egress, Settings: settings, Credentials: slots, Tools: tools, Effects: effects,
}, nil
}
@@ -230,6 +255,13 @@ func (m *Module) serverSpec(ctx context.Context, a store.Accepted) (ServerSpec,
return ServerSpec{}, fmt.Errorf("tools: %w", err)
}
}
if len(a.Effects) > 0 {
var effects ServerEffects
if err := json.Unmarshal(a.Effects, &effects); err != nil {
return ServerSpec{}, fmt.Errorf("effects: %w", err)
}
spec.Privileged = effects.privileged()
}
env, headers, err := m.mcpCredentials(ctx, a, spec.URL != "")
if err != nil {
return ServerSpec{}, err
+109
View File
@@ -0,0 +1,109 @@
package connectors
import (
"context"
"encoding/json/jsontext"
"testing"
"google.golang.org/grpc"
pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1"
)
// effectsClient declares one action with the given effect and resolves it to
// another.
type effectsClient struct {
pb.ConnectorServiceClient
declared, resolved *pb.Effect
}
func (effectsClient) Configure(context.Context, *pb.ConfigureRequest, ...grpc.CallOption) (*pb.ConfigureResponse, error) {
return &pb.ConfigureResponse{}, nil
}
func (c effectsClient) Describe(context.Context, *pb.DescribeRequest, ...grpc.CallOption) (*pb.DescribeResponse, error) {
return &pb.DescribeResponse{Contract: contractVersion, Actions: []*pb.ActionType{{Name: "grant", Effect: c.declared, Idempotent: true}}}, nil
}
func (c effectsClient) Resolve(context.Context, *pb.ResolveRequest, ...grpc.CallOption) (*pb.ResolveResponse, error) {
return &pb.ResolveResponse{Effect: c.resolved}, nil
}
// TestResolveKeepsWhatAnActionDeclared guards the chat prohibition's input: a
// resolution can add a privileged effect for one input, but it can't clear
// what the action declared or declare effects for an action that never did.
func TestResolveKeepsWhatAnActionDeclared(t *testing.T) {
tests := []struct {
name string
declared, resolved *pb.Effect
want PrivilegedEffects
}{
{
name: "the declaration holds when the resolution says nothing",
declared: &pb.Effect{EffectsDeclared: true, PrivilegeChange: true}, resolved: &pb.Effect{},
want: PrivilegedEffects{Declared: true, PrivilegeChange: true},
},
{
name: "a resolution adds a privileged effect",
declared: &pb.Effect{EffectsDeclared: true}, resolved: &pb.Effect{SecretAccess: true},
want: PrivilegedEffects{Declared: true, SecretAccess: true},
},
{
name: "a resolution can't declare for an action that never did",
declared: &pb.Effect{}, resolved: &pb.Effect{EffectsDeclared: true},
want: PrivilegedEffects{},
},
{
name: "a resolution can't clear a declared effect",
declared: &pb.Effect{EffectsDeclared: true, SecretAccess: true}, resolved: &pb.Effect{EffectsDeclared: true},
want: PrivilegedEffects{Declared: true, SecretAccess: true},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
c, err := open(t.Context(), "iam", effectsClient{declared: tt.declared, resolved: tt.resolved}, nil, nil)
if err != nil {
t.Fatal(err)
}
res, err := c.Resolve(t.Context(), "grant", jsontext.Value(`{}`))
if err != nil {
t.Fatal(err)
}
if res.Effect.Privileged != tt.want {
t.Fatalf("resolved effects = %+v, want %+v", res.Effect.Privileged, tt.want)
}
if got := c.Declarations()[0].Privileged; got.Declared != tt.declared.GetEffectsDeclared() {
t.Fatalf("declaration effects = %+v, want declared = %v", got, tt.declared.GetEffectsDeclared())
}
})
}
}
// TestServerToolsInheritTheServersDeclaredEffects guards deny by default for an
// MCP server: until an operator declares its effects every tool is undeclared,
// and afterwards every tool carries the declaration.
func TestServerToolsInheritTheServersDeclaredEffects(t *testing.T) {
tests := []struct {
name string
privileged PrivilegedEffects
wantChat bool
}{
{name: "unset", privileged: (*ServerEffects)(nil).privileged(), wantChat: false},
{name: "declared none", privileged: (&ServerEffects{}).privileged(), wantChat: true},
{name: "declared privilege change", privileged: (&ServerEffects{PrivilegeChange: true}).privileged(), wantChat: false},
{name: "declared secret access", privileged: (&ServerEffects{SecretAccess: true}).privileged(), wantChat: false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
spec := ServerSpec{Name: "metrics", Privileged: tt.privileged, Tools: []ToolDecl{{Name: "query", Kind: KindLookup}}}
s := inMemory(t, spec, fakeTools(t, "query"))
if err := s.Connect(t.Context()); err != nil {
t.Fatal(err)
}
t.Cleanup(s.Close)
if got := !s.Declarations()[0].Privileged.ProhibitedInChat(); got != tt.wantChat {
t.Fatalf("offered to chat = %v, want %v", got, tt.wantChat)
}
})
}
}
+34
View File
@@ -0,0 +1,34 @@
package judgement
// ChatWorkflow is the workflow name a chat turn judges its actions under.
const ChatWorkflow = "chat"
// chatProhibitionRule names the refusal of an action chat must never perform.
// It is code rather than a Cedar policy: Policies.Put replaces the whole
// hard-rules set, so an editable policy could remove the prohibition.
const chatProhibitionRule = "chat-prohibited-effect"
// chatProhibition says why a chat turn may not run the action, or nothing when
// it may. An action is prohibited in chat when it changes privileges, accesses
// secrets, or never declared whether it does. Every other workflow is judged
// by the hard rules and guards alone.
func chatProhibition(workflow string, a Action) (reason string, prohibited bool) {
if workflow != ChatWorkflow {
return "", false
}
p := a.Effect.Privileged
switch {
case !p.Declared:
return "the action doesn't declare its effects, so chat can't run it", true
case p.PrivilegeChange:
return "the action changes privileges, which chat never does", true
case p.SecretAccess:
return "the action accesses secrets, which chat never does", true
}
return "", false
}
// chatRefusal is the decision refusing a prohibited chat action.
func chatRefusal(a Action, reason string) Decision {
return Decision{Action: a, Level: Never, RefusedBy: chatProhibitionRule, Reason: reason, Verdicts: []Verdict{}}
}
+109
View File
@@ -0,0 +1,109 @@
package judgement
import (
"context"
"encoding/json/jsontext"
"errors"
"log/slog"
"sync/atomic"
"testing"
"time"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/judgement/internal/store"
)
func chatTestAction(p connectors.PrivilegedEffects) Action {
input := jsontext.Value(`{"role":"owner"}`)
return Action{
Connector: "iam", Name: "grant", Input: input, Digest: connectors.Digest("grant", input),
Effect: connectors.Effect{Privileged: p},
}
}
// TestChatProhibitsPrivilegedActions guards the chat prohibition: in a chat
// turn an action that changes privileges, accesses secrets or never declared
// its effects is refused at proposal and at execution, with or without an
// approval, and nothing reaches the connector. The same action in another
// workflow is judged as usual, so the dashboard and workflow runs stay open.
// The rule reads only the action and the workflow, so it holds for an owner
// as it does for anyone.
func TestChatProhibitsPrivilegedActions(t *testing.T) {
tests := []struct {
name string
workflow string
privileged connectors.PrivilegedEffects
wantRefusal bool
wantDecision Level
}{
{name: "chat refuses a privilege change", workflow: ChatWorkflow, privileged: connectors.PrivilegedEffects{Declared: true, PrivilegeChange: true}, wantRefusal: true},
{name: "chat refuses secret access", workflow: ChatWorkflow, privileged: connectors.PrivilegedEffects{Declared: true, SecretAccess: true}, wantRefusal: true},
{name: "chat refuses an action that never declared its effects", workflow: ChatWorkflow, privileged: connectors.PrivilegedEffects{}, wantRefusal: true},
{name: "chat runs an action that declared no privileged effect", workflow: ChatWorkflow, privileged: connectors.PrivilegedEffects{Declared: true}, wantDecision: ActQuietly},
{name: "a workflow run may change privileges", workflow: "provision", privileged: connectors.PrivilegedEffects{Declared: true, PrivilegeChange: true}, wantDecision: ActQuietly},
{name: "a workflow run may access secrets", workflow: "rotate", privileged: connectors.PrivilegedEffects{Declared: true, SecretAccess: true}, wantDecision: ActQuietly},
{name: "a workflow run may use an undeclared action", workflow: "provision", privileged: connectors.PrivilegedEffects{}, wantDecision: ActQuietly},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
a := chatTestAction(tt.privileged)
var guarded atomic.Int32
m := &Module{guards: []Guard{fixedGuard{name: "g", ceiling: ActQuietly, calls: &guarded}}}
d := m.decide(withRun(t.Context(), RunContext{Workflow: tt.workflow}), a)
if tt.wantRefusal {
if d.Level != Never || d.RefusedBy != chatProhibitionRule {
t.Fatalf("decision = level %s refused by %q, want never by %q", d.Level, d.RefusedBy, chatProhibitionRule)
}
if guarded.Load() != 0 {
t.Fatal("a guard ran for a prohibited action")
}
} else if d.Level != tt.wantDecision || d.RefusedBy != "" {
t.Fatalf("decision = level %s refused by %q, want %s", d.Level, d.RefusedBy, tt.wantDecision)
}
// Execution checks again, on a decision that reached a runnable or
// held level by any other route.
var invoked atomic.Int32
exec := &Module{tools: oneTool{countingTool{&invoked}}}
for _, level := range []Level{ActQuietly, ProposeAndWait} {
held := Decision{ID: uuid.New(), Level: level, Workflow: tt.workflow, Action: a}
approval := Approval{DecisionID: held.ID, Digest: a.Digest, By: "owner", At: time.Now().UTC()}
_, errRun := exec.Execute(t.Context(), held, a.Input, "k")
_, errApproved := exec.ExecuteApproved(t.Context(), held, approval, a.Input, "k")
if tt.wantRefusal && (!errors.Is(errRun, ErrRefused) || !errors.Is(errApproved, ErrRefused)) {
t.Fatalf("level %s: execute = %v, approved = %v; want both refused", level, errRun, errApproved)
}
}
if tt.wantRefusal && invoked.Load() != 0 {
t.Fatalf("connector invoked %d times for a prohibited action", invoked.Load())
}
if !tt.wantRefusal && invoked.Load() == 0 {
t.Fatal("an action outside the prohibition never ran")
}
})
}
}
type failingPolicies struct{ memoryPolicies }
func (failingPolicies) Policy(context.Context, string, string, int) (store.PolicySet, error) {
return store.PolicySet{}, errors.New("database unavailable")
}
// TestUnreadableHardRulesRefuse guards fail-closed judgement: when the hard
// rules can't be read, no action is judged to run, in chat or anywhere else.
func TestUnreadableHardRulesRefuse(t *testing.T) {
for _, workflow := range []string{ChatWorkflow, "provision"} {
t.Run(workflow, func(t *testing.T) {
p := &Policies{store: &failingPolicies{}, log: slog.New(slog.DiscardHandler)}
m := &Module{rules: []HardRule{p}, guards: []Guard{fixedGuard{name: "g", ceiling: ActQuietly}}}
a := chatTestAction(connectors.PrivilegedEffects{Declared: true})
d := m.decide(withRun(t.Context(), RunContext{Workflow: workflow}), a)
if d.Level != Never || d.RefusedBy != hardRulesUnreadable {
t.Fatalf("decision = level %s refused by %q, want never by %q", d.Level, d.RefusedBy, hardRulesUnreadable)
}
})
}
}
+13
View File
@@ -148,6 +148,9 @@ type Decision struct {
Verdicts []Verdict `json:"verdicts"`
// RefusedBy names the hard rule that refused the action, if one did.
RefusedBy string `json:"refused_by,omitzero"`
// Workflow is the workflow the decision was made for. Execution checks it
// again, so a held chat action stays prohibited whatever approval it has.
Workflow string `json:"workflow,omitzero"`
// ChangeRequest says approval goes through a change request, and
// ChangeRequestRule which change-request rule said so.
ChangeRequest bool `json:"change_request,omitzero"`
@@ -292,6 +295,7 @@ func (m *Module) Assess(ctx context.Context, req Request) (Decision, error) {
}
d := m.decide(withRun(ctx, RunContext{RunID: req.RunID, Key: req.Key, Workflow: req.Workflow, Diagnosis: req.Diagnosis, Evidence: req.Evidence, Overlay: req.Overlay}), a)
d.ID, d.RunID, d.Key, d.At, d.Dry = uuid.New(), req.RunID, req.Key, m.now().UTC(), req.Dry
d.Workflow = req.Workflow
d.Calls = calls.take()
return m.record(ctx, d)
}
@@ -299,6 +303,9 @@ func (m *Module) Assess(ctx context.Context, req Request) (Decision, error) {
// decide runs the hard rules, then every guard in parallel, and folds their
// ceilings: the action runs at the lowest.
func (m *Module) decide(ctx context.Context, a Action) Decision {
if reason, prohibited := chatProhibition(runFrom(ctx).Workflow, a); prohibited {
return chatRefusal(a, reason)
}
for _, r := range m.rules {
if by, reason, refused := r.Refuses(ctx, a); refused {
return Decision{Action: a, Level: Never, RefusedBy: by, Reason: reason, Verdicts: []Verdict{}}
@@ -375,6 +382,9 @@ func (m *Module) guardTimeout() time.Duration {
// Execute runs a decided action if its level lets it run and the input is
// exactly the one judged. key is the idempotency key the connector honours.
func (m *Module) Execute(ctx context.Context, d Decision, input jsontext.Value, key string) (string, error) {
if reason, prohibited := chatProhibition(d.Workflow, d.Action); prohibited {
return "", fmt.Errorf("%w: %s: %s", ErrRefused, chatProhibitionRule, reason)
}
switch {
case d.Level == Never:
return "", fmt.Errorf("%w: %s: %s", ErrRefused, d.RefusedBy, d.Reason)
@@ -447,6 +457,9 @@ func (a Approval) Covers(d Decision) bool {
// and an approval that names another decision or another action runs nothing.
// The action that runs is the one judged, whatever input comes with it.
func (m *Module) ExecuteApproved(ctx context.Context, d Decision, a Approval, input jsontext.Value, key string) (string, error) {
if reason, prohibited := chatProhibition(d.Workflow, d.Action); prohibited {
return "", fmt.Errorf("%w: %s: %s", ErrRefused, chatProhibitionRule, reason)
}
switch {
case d.Level == Never:
return "", fmt.Errorf("%w: %s: %s", ErrRefused, d.RefusedBy, d.Reason)
+13
View File
@@ -127,6 +127,9 @@ message LookupType {
string name = 1;
string description = 2;
bytes input_schema = 3;
// effect declares the lookup's effects. Only the effects_declared,
// privilege_change and secret_access fields apply to a lookup.
Effect effect = 4;
}
enum Reversibility {
@@ -145,6 +148,16 @@ message Effect {
// summary says in plain words what the action does, for example "delete
// files older than 24h under /tmp/runner".
string summary = 3;
// effects_declared says the connector stated this action's privilege_change
// and secret_access explicitly. With it false the two flags mean nothing: an
// action that never stated its effects is prohibited in chat, which is not
// the same as an action that stated it has none.
bool effects_declared = 4;
// privilege_change says the action changes who may do what: it grants
// roles, changes identities or policies, or changes control-plane settings.
bool privilege_change = 5;
// secret_access says the action reads, exports or reveals a secret.
bool secret_access = 6;
}
// Target is what an action acts on. Connector, action, kind and environment
+8
View File
@@ -853,10 +853,17 @@ export interface Extension {
credentials?: Record<string, string>;
/** An MCP server's declared tools, as it was accepted with them. */
tools?: unknown;
/** An MCP server's declared privileged effects; absent until declared. */
effects?: ServerEffects;
/** A connector's declarations; absent until it has loaded. */
capabilities?: Capabilities;
}
export interface ServerEffects {
privilege_change: boolean;
secret_access: boolean;
}
export interface ExtensionInput {
path?: string;
sha256?: string;
@@ -867,6 +874,7 @@ export interface ExtensionInput {
settings?: Record<string, string>;
credentials?: Record<string, string>;
tools?: unknown;
effects?: ServerEffects;
}
export interface Credential {
+26 -1
View File
@@ -50,10 +50,27 @@ function declared(ext: Extension) {
}
const mcp = computed(() => props.kind === "mcp-servers");
/** What an operator declares about an MCP server's tools. Chat offers a server
* only when its effects are declared and neither one applies. */
const EFFECT_OPTIONS = [
{ value: "unset", label: "Not declared", effects: undefined },
{ value: "none", label: "No privileged effects", effects: { privilege_change: false, secret_access: false } },
{ value: "privilege_change", label: "Changes privileges", effects: { privilege_change: true, secret_access: false } },
{ value: "secret_access", label: "Accesses secrets", effects: { privilege_change: false, secret_access: true } },
{ value: "both", label: "Changes privileges and accesses secrets", effects: { privilege_change: true, secret_access: true } },
] as const;
function effectOf(ext?: Extension): string {
const e = ext?.effects;
if (!e) return "unset";
if (e.privilege_change && e.secret_access) return "both";
return e.privilege_change ? "privilege_change" : e.secret_access ? "secret_access" : "none";
}
const editing = ref(false);
const isNew = ref(true);
const schema = ref<Extension["settings_schema"]>([]);
const form = ref({ name: "", path: "", sha256: "", url: "", args: "", egress: "", env: "", credentials: "", tools: "", settings: {} as Record<string, string>, other: "" });
const form = ref({ name: "", path: "", sha256: "", url: "", args: "", egress: "", env: "", credentials: "", tools: "", effects: "unset", settings: {} as Record<string, string>, other: "" });
function open(ext?: Extension): void {
isNew.value = !ext;
actionError.value = "";
@@ -70,6 +87,7 @@ function open(ext?: Extension): void {
env: (ext?.env ?? []).join("\n"),
credentials: toLines(ext?.credentials ?? {}),
tools: ext?.tools ? JSON.stringify(ext.tools, null, 2) : "[]",
effects: effectOf(ext),
settings: Object.fromEntries(Object.entries(settings).filter(([k]) => known.has(k))),
other: toLines(Object.fromEntries(Object.entries(settings).filter(([k]) => !known.has(k)))),
};
@@ -97,6 +115,7 @@ async function submit(): Promise<void> {
body.url = f.url.trim() || undefined;
body.args = list(f.args);
body.tools = JSON.parse(f.tools || "[]");
body.effects = EFFECT_OPTIONS.find((o) => o.value === f.effects)?.effects;
}
await api.acceptExtension(props.kind, f.name.trim(), body);
editing.value = false;
@@ -171,6 +190,12 @@ async function remove(): Promise<void> {
<SettingRow label="Arguments" for="ext-args" hint="One per line."><Textarea id="ext-args" v-model="form.args" class="font-mono" rows="2" /></SettingRow>
<SettingRow label="Tools" for="ext-tools" hint="The tools it may offer, as JSON: name, kind, read_only, reversibility, summary."><Textarea id="ext-tools" v-model="form.tools" class="font-mono" rows="5" /></SettingRow>
</template>
<SettingRow v-if="mcp" label="Effects" for="ext-effects" hint="Chat offers a server only once this says its tools change no privileges and access no secrets.">
<Select v-model="form.effects">
<SelectTrigger id="ext-effects" class="w-full"><SelectValue /></SelectTrigger>
<SelectContent><SelectItem v-for="o in EFFECT_OPTIONS" :key="o.value" :value="o.value">{{ o.label }}</SelectItem></SelectContent>
</Select>
</SettingRow>
<SettingRow v-for="field in schema" :key="field.key" :label="field.label || field.key" :for="`ext-set-${field.key}`" :hint="field.description">
<Select v-if="field.options?.length" v-model="form.settings[field.key]">
<SelectTrigger :id="`ext-set-${field.key}`" class="w-full"><SelectValue /></SelectTrigger>