diff --git a/internal/app/archie/run.go b/internal/app/archie/run.go index ac9501bf1..00c676153 100644 --- a/internal/app/archie/run.go +++ b/internal/app/archie/run.go @@ -124,10 +124,12 @@ func work(ctx context.Context, loops ...func(context.Context)) func() { // newJudgement returns the judgement module and the action classes its // precedent guard reads. A failed action tightens its class. -func newJudgement(db *sqlx.DB, log *slog.Logger, conns judgement.Tools, freezes judgement.Freezes) (*judgement.Module, *judgement.Classes) { +func newJudgement(db *sqlx.DB, log *slog.Logger, conns *connectors.Module, freezes judgement.Freezes) (*judgement.Module, *judgement.Classes) { classes := judgement.NewClasses(db, log.With("module", "judgement"), orgID) - return judgement.NewModule(db, log.With("module", "judgement"), orgID, conns, nil, - []judgement.Guard{judgement.Reversibility{}, judgement.Precedent{Classes: classes}, judgement.Freeze{Freezes: freezes}}, classes), classes + judge := judgement.NewModule(db, log.With("module", "judgement"), orgID, conns, nil, + []judgement.Guard{judgement.Reversibility{}, judgement.Precedent{Classes: classes}, judgement.Freeze{Freezes: freezes}}, classes) + judge.UseExtensions(conns) + return judge, classes } // orgID is the one organisation until hosting is multi-tenant. diff --git a/internal/contracts/guard/v1/guard.pb.go b/internal/contracts/guard/v1/guard.pb.go new file mode 100644 index 000000000..7458f8707 --- /dev/null +++ b/internal/contracts/guard/v1/guard.pb.go @@ -0,0 +1,960 @@ +// Code generated by protoc-gen-go. DO NOT EDIT. +// versions: +// protoc-gen-go v1.36.11 +// protoc (unknown) +// source: guard/v1/guard.proto + +package guardv1 + +import ( + protoreflect "google.golang.org/protobuf/reflect/protoreflect" + protoimpl "google.golang.org/protobuf/runtime/protoimpl" + durationpb "google.golang.org/protobuf/types/known/durationpb" + timestamppb "google.golang.org/protobuf/types/known/timestamppb" + reflect "reflect" + sync "sync" + unsafe "unsafe" +) + +const ( + // Verify that this generated code is sufficiently up-to-date. + _ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion) + // Verify that runtime/protoimpl is sufficiently up-to-date. + _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20) +) + +type Reversibility int32 + +const ( + Reversibility_REVERSIBILITY_UNSPECIFIED Reversibility = 0 + Reversibility_REVERSIBILITY_UNDONE_AUTOMATICALLY Reversibility = 1 + Reversibility_REVERSIBILITY_RECOVERABLE Reversibility = 2 + Reversibility_REVERSIBILITY_IRREVERSIBLE Reversibility = 3 +) + +// Enum value maps for Reversibility. +var ( + Reversibility_name = map[int32]string{ + 0: "REVERSIBILITY_UNSPECIFIED", + 1: "REVERSIBILITY_UNDONE_AUTOMATICALLY", + 2: "REVERSIBILITY_RECOVERABLE", + 3: "REVERSIBILITY_IRREVERSIBLE", + } + Reversibility_value = map[string]int32{ + "REVERSIBILITY_UNSPECIFIED": 0, + "REVERSIBILITY_UNDONE_AUTOMATICALLY": 1, + "REVERSIBILITY_RECOVERABLE": 2, + "REVERSIBILITY_IRREVERSIBLE": 3, + } +) + +func (x Reversibility) Enum() *Reversibility { + p := new(Reversibility) + *p = x + return p +} + +func (x Reversibility) String() string { + return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x)) +} + +func (Reversibility) Descriptor() protoreflect.EnumDescriptor { + return file_guard_v1_guard_proto_enumTypes[0].Descriptor() +} + +func (Reversibility) Type() protoreflect.EnumType { + return &file_guard_v1_guard_proto_enumTypes[0] +} + +func (x Reversibility) Number() protoreflect.EnumNumber { + return protoreflect.EnumNumber(x) +} + +// Deprecated: Use Reversibility.Descriptor instead. +func (Reversibility) EnumDescriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{0} +} + +// Ceiling is the five-level scale, from the most autonomy to the least. +type Ceiling int32 + +const ( + Ceiling_CEILING_UNSPECIFIED Ceiling = 0 + Ceiling_CEILING_ACT_QUIETLY Ceiling = 1 + Ceiling_CEILING_ACT_AND_TELL Ceiling = 2 + Ceiling_CEILING_PROPOSE_AND_WAIT Ceiling = 3 + Ceiling_CEILING_ESCALATE Ceiling = 4 + Ceiling_CEILING_NEVER Ceiling = 5 +) + +// Enum value maps for Ceiling. +var ( + Ceiling_name = map[int32]string{ + 0: "CEILING_UNSPECIFIED", + 1: "CEILING_ACT_QUIETLY", + 2: "CEILING_ACT_AND_TELL", + 3: "CEILING_PROPOSE_AND_WAIT", + 4: "CEILING_ESCALATE", + 5: "CEILING_NEVER", + } + Ceiling_value = map[string]int32{ + "CEILING_UNSPECIFIED": 0, + "CEILING_ACT_QUIETLY": 1, + "CEILING_ACT_AND_TELL": 2, + "CEILING_PROPOSE_AND_WAIT": 3, + "CEILING_ESCALATE": 4, + "CEILING_NEVER": 5, + } +) + +func (x Ceiling) Enum() *Ceiling { + p := new(Ceiling) + *p = x + return p +} + +func (x Ceiling) String() string { + return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x)) +} + +func (Ceiling) Descriptor() protoreflect.EnumDescriptor { + return file_guard_v1_guard_proto_enumTypes[1].Descriptor() +} + +func (Ceiling) Type() protoreflect.EnumType { + return &file_guard_v1_guard_proto_enumTypes[1] +} + +func (x Ceiling) Number() protoreflect.EnumNumber { + return protoreflect.EnumNumber(x) +} + +// Deprecated: Use Ceiling.Descriptor instead. +func (Ceiling) EnumDescriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{1} +} + +// Strength is how much a finding's evidence supports it. +type Strength int32 + +const ( + Strength_STRENGTH_UNSPECIFIED Strength = 0 + Strength_STRENGTH_WEAK Strength = 1 + Strength_STRENGTH_MODERATE Strength = 2 + Strength_STRENGTH_STRONG Strength = 3 +) + +// Enum value maps for Strength. +var ( + Strength_name = map[int32]string{ + 0: "STRENGTH_UNSPECIFIED", + 1: "STRENGTH_WEAK", + 2: "STRENGTH_MODERATE", + 3: "STRENGTH_STRONG", + } + Strength_value = map[string]int32{ + "STRENGTH_UNSPECIFIED": 0, + "STRENGTH_WEAK": 1, + "STRENGTH_MODERATE": 2, + "STRENGTH_STRONG": 3, + } +) + +func (x Strength) Enum() *Strength { + p := new(Strength) + *p = x + return p +} + +func (x Strength) String() string { + return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x)) +} + +func (Strength) Descriptor() protoreflect.EnumDescriptor { + return file_guard_v1_guard_proto_enumTypes[2].Descriptor() +} + +func (Strength) Type() protoreflect.EnumType { + return &file_guard_v1_guard_proto_enumTypes[2] +} + +func (x Strength) Number() protoreflect.EnumNumber { + return protoreflect.EnumNumber(x) +} + +// Deprecated: Use Strength.Descriptor instead. +func (Strength) EnumDescriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{2} +} + +type ConfigureRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Settings map[string]string `protobuf:"bytes,1,rep,name=settings,proto3" json:"settings,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` + Secrets map[string]string `protobuf:"bytes,2,rep,name=secrets,proto3" json:"secrets,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ConfigureRequest) Reset() { + *x = ConfigureRequest{} + mi := &file_guard_v1_guard_proto_msgTypes[0] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ConfigureRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ConfigureRequest) ProtoMessage() {} + +func (x *ConfigureRequest) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[0] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ConfigureRequest.ProtoReflect.Descriptor instead. +func (*ConfigureRequest) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{0} +} + +func (x *ConfigureRequest) GetSettings() map[string]string { + if x != nil { + return x.Settings + } + return nil +} + +func (x *ConfigureRequest) GetSecrets() map[string]string { + if x != nil { + return x.Secrets + } + return nil +} + +type ConfigureResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ConfigureResponse) Reset() { + *x = ConfigureResponse{} + mi := &file_guard_v1_guard_proto_msgTypes[1] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ConfigureResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ConfigureResponse) ProtoMessage() {} + +func (x *ConfigureResponse) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[1] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ConfigureResponse.ProtoReflect.Descriptor instead. +func (*ConfigureResponse) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{1} +} + +type DescribeRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *DescribeRequest) Reset() { + *x = DescribeRequest{} + mi := &file_guard_v1_guard_proto_msgTypes[2] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *DescribeRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*DescribeRequest) ProtoMessage() {} + +func (x *DescribeRequest) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[2] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use DescribeRequest.ProtoReflect.Descriptor instead. +func (*DescribeRequest) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{2} +} + +type DescribeResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + // contract is the contract version the guard speaks, "v1". + Contract string `protobuf:"bytes,1,opt,name=contract,proto3" json:"contract,omitempty"` + Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"` + // version is the guard's own release, recorded with each verdict. + Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"` + // advisory says the guard's verdicts are recorded and set no ceiling. + Advisory bool `protobuf:"varint,4,opt,name=advisory,proto3" json:"advisory,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *DescribeResponse) Reset() { + *x = DescribeResponse{} + mi := &file_guard_v1_guard_proto_msgTypes[3] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *DescribeResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*DescribeResponse) ProtoMessage() {} + +func (x *DescribeResponse) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[3] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use DescribeResponse.ProtoReflect.Descriptor instead. +func (*DescribeResponse) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{3} +} + +func (x *DescribeResponse) GetContract() string { + if x != nil { + return x.Contract + } + return "" +} + +func (x *DescribeResponse) GetName() string { + if x != nil { + return x.Name + } + return "" +} + +func (x *DescribeResponse) GetVersion() string { + if x != nil { + return x.Version + } + return "" +} + +func (x *DescribeResponse) GetAdvisory() bool { + if x != nil { + return x.Advisory + } + return false +} + +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=guard.v1.Reversibility" json:"reversibility,omitempty"` + Summary string `protobuf:"bytes,3,opt,name=summary,proto3" json:"summary,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *Effect) Reset() { + *x = Effect{} + mi := &file_guard_v1_guard_proto_msgTypes[4] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *Effect) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*Effect) ProtoMessage() {} + +func (x *Effect) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[4] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use Effect.ProtoReflect.Descriptor instead. +func (*Effect) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{4} +} + +func (x *Effect) GetReadOnly() bool { + if x != nil { + return x.ReadOnly + } + return false +} + +func (x *Effect) GetReversibility() Reversibility { + if x != nil { + return x.Reversibility + } + return Reversibility_REVERSIBILITY_UNSPECIFIED +} + +func (x *Effect) GetSummary() string { + if x != nil { + return x.Summary + } + return "" +} + +type Target struct { + state protoimpl.MessageState `protogen:"open.v1"` + Kind string `protobuf:"bytes,1,opt,name=kind,proto3" json:"kind,omitempty"` + Id string `protobuf:"bytes,2,opt,name=id,proto3" json:"id,omitempty"` + Environment string `protobuf:"bytes,3,opt,name=environment,proto3" json:"environment,omitempty"` + Disposable bool `protobuf:"varint,4,opt,name=disposable,proto3" json:"disposable,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *Target) Reset() { + *x = Target{} + mi := &file_guard_v1_guard_proto_msgTypes[5] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *Target) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*Target) ProtoMessage() {} + +func (x *Target) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[5] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use Target.ProtoReflect.Descriptor instead. +func (*Target) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{5} +} + +func (x *Target) GetKind() string { + if x != nil { + return x.Kind + } + return "" +} + +func (x *Target) GetId() string { + if x != nil { + return x.Id + } + return "" +} + +func (x *Target) GetEnvironment() string { + if x != nil { + return x.Environment + } + return "" +} + +func (x *Target) GetDisposable() bool { + if x != nil { + return x.Disposable + } + return false +} + +type RunContext struct { + state protoimpl.MessageState `protogen:"open.v1"` + RunId string `protobuf:"bytes,1,opt,name=run_id,json=runId,proto3" json:"run_id,omitempty"` + // decision_key identifies the attempt to run the action. + DecisionKey string `protobuf:"bytes,2,opt,name=decision_key,json=decisionKey,proto3" json:"decision_key,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *RunContext) Reset() { + *x = RunContext{} + mi := &file_guard_v1_guard_proto_msgTypes[6] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *RunContext) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*RunContext) ProtoMessage() {} + +func (x *RunContext) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[6] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use RunContext.ProtoReflect.Descriptor instead. +func (*RunContext) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{6} +} + +func (x *RunContext) GetRunId() string { + if x != nil { + return x.RunId + } + return "" +} + +func (x *RunContext) GetDecisionKey() string { + if x != nil { + return x.DecisionKey + } + return "" +} + +type JudgeRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + Connector string `protobuf:"bytes,1,opt,name=connector,proto3" json:"connector,omitempty"` + Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"` + Input []byte `protobuf:"bytes,3,opt,name=input,proto3" json:"input,omitempty"` + // digest identifies the exact action: its name and input. + Digest string `protobuf:"bytes,4,opt,name=digest,proto3" json:"digest,omitempty"` + Target *Target `protobuf:"bytes,5,opt,name=target,proto3" json:"target,omitempty"` + Effect *Effect `protobuf:"bytes,6,opt,name=effect,proto3" json:"effect,omitempty"` + Run *RunContext `protobuf:"bytes,7,opt,name=run,proto3" json:"run,omitempty"` + // deadline is how long the host waits for the verdict. + Deadline *durationpb.Duration `protobuf:"bytes,8,opt,name=deadline,proto3" json:"deadline,omitempty"` + // at is the host's clock when the action was put to the guard. + At *timestamppb.Timestamp `protobuf:"bytes,9,opt,name=at,proto3" json:"at,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *JudgeRequest) Reset() { + *x = JudgeRequest{} + mi := &file_guard_v1_guard_proto_msgTypes[7] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *JudgeRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*JudgeRequest) ProtoMessage() {} + +func (x *JudgeRequest) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[7] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use JudgeRequest.ProtoReflect.Descriptor instead. +func (*JudgeRequest) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{7} +} + +func (x *JudgeRequest) GetConnector() string { + if x != nil { + return x.Connector + } + return "" +} + +func (x *JudgeRequest) GetName() string { + if x != nil { + return x.Name + } + return "" +} + +func (x *JudgeRequest) GetInput() []byte { + if x != nil { + return x.Input + } + return nil +} + +func (x *JudgeRequest) GetDigest() string { + if x != nil { + return x.Digest + } + return "" +} + +func (x *JudgeRequest) GetTarget() *Target { + if x != nil { + return x.Target + } + return nil +} + +func (x *JudgeRequest) GetEffect() *Effect { + if x != nil { + return x.Effect + } + return nil +} + +func (x *JudgeRequest) GetRun() *RunContext { + if x != nil { + return x.Run + } + return nil +} + +func (x *JudgeRequest) GetDeadline() *durationpb.Duration { + if x != nil { + return x.Deadline + } + return nil +} + +func (x *JudgeRequest) GetAt() *timestamppb.Timestamp { + if x != nil { + return x.At + } + return nil +} + +type Finding struct { + state protoimpl.MessageState `protogen:"open.v1"` + Text string `protobuf:"bytes,1,opt,name=text,proto3" json:"text,omitempty"` + // evidence is what the finding rests on, in plain words. + Evidence string `protobuf:"bytes,2,opt,name=evidence,proto3" json:"evidence,omitempty"` + Strength Strength `protobuf:"varint,3,opt,name=strength,proto3,enum=guard.v1.Strength" json:"strength,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *Finding) Reset() { + *x = Finding{} + mi := &file_guard_v1_guard_proto_msgTypes[8] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *Finding) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*Finding) ProtoMessage() {} + +func (x *Finding) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[8] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use Finding.ProtoReflect.Descriptor instead. +func (*Finding) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{8} +} + +func (x *Finding) GetText() string { + if x != nil { + return x.Text + } + return "" +} + +func (x *Finding) GetEvidence() string { + if x != nil { + return x.Evidence + } + return "" +} + +func (x *Finding) GetStrength() Strength { + if x != nil { + return x.Strength + } + return Strength_STRENGTH_UNSPECIFIED +} + +type JudgeResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + // ceiling must be set. A guard with no concern answers CEILING_ACT_QUIETLY. + Ceiling Ceiling `protobuf:"varint,1,opt,name=ceiling,proto3,enum=guard.v1.Ceiling" json:"ceiling,omitempty"` + Findings []*Finding `protobuf:"bytes,2,rep,name=findings,proto3" json:"findings,omitempty"` + // blind_spots are what the guard could not see. + BlindSpots []string `protobuf:"bytes,3,rep,name=blind_spots,json=blindSpots,proto3" json:"blind_spots,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *JudgeResponse) Reset() { + *x = JudgeResponse{} + mi := &file_guard_v1_guard_proto_msgTypes[9] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *JudgeResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*JudgeResponse) ProtoMessage() {} + +func (x *JudgeResponse) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[9] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use JudgeResponse.ProtoReflect.Descriptor instead. +func (*JudgeResponse) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{9} +} + +func (x *JudgeResponse) GetCeiling() Ceiling { + if x != nil { + return x.Ceiling + } + return Ceiling_CEILING_UNSPECIFIED +} + +func (x *JudgeResponse) GetFindings() []*Finding { + if x != nil { + return x.Findings + } + return nil +} + +func (x *JudgeResponse) GetBlindSpots() []string { + if x != nil { + return x.BlindSpots + } + return nil +} + +var File_guard_v1_guard_proto protoreflect.FileDescriptor + +const file_guard_v1_guard_proto_rawDesc = "" + + "\n" + + "\x14guard/v1/guard.proto\x12\bguard.v1\x1a\x1egoogle/protobuf/duration.proto\x1a\x1fgoogle/protobuf/timestamp.proto\"\x94\x02\n" + + "\x10ConfigureRequest\x12D\n" + + "\bsettings\x18\x01 \x03(\v2(.guard.v1.ConfigureRequest.SettingsEntryR\bsettings\x12A\n" + + "\asecrets\x18\x02 \x03(\v2'.guard.v1.ConfigureRequest.SecretsEntryR\asecrets\x1a;\n" + + "\rSettingsEntry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\x1a:\n" + + "\fSecretsEntry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"\x13\n" + + "\x11ConfigureResponse\"\x11\n" + + "\x0fDescribeRequest\"x\n" + + "\x10DescribeResponse\x12\x1a\n" + + "\bcontract\x18\x01 \x01(\tR\bcontract\x12\x12\n" + + "\x04name\x18\x02 \x01(\tR\x04name\x12\x18\n" + + "\aversion\x18\x03 \x01(\tR\aversion\x12\x1a\n" + + "\badvisory\x18\x04 \x01(\bR\badvisory\"~\n" + + "\x06Effect\x12\x1b\n" + + "\tread_only\x18\x01 \x01(\bR\breadOnly\x12=\n" + + "\rreversibility\x18\x02 \x01(\x0e2\x17.guard.v1.ReversibilityR\rreversibility\x12\x18\n" + + "\asummary\x18\x03 \x01(\tR\asummary\"n\n" + + "\x06Target\x12\x12\n" + + "\x04kind\x18\x01 \x01(\tR\x04kind\x12\x0e\n" + + "\x02id\x18\x02 \x01(\tR\x02id\x12 \n" + + "\venvironment\x18\x03 \x01(\tR\venvironment\x12\x1e\n" + + "\n" + + "disposable\x18\x04 \x01(\bR\n" + + "disposable\"F\n" + + "\n" + + "RunContext\x12\x15\n" + + "\x06run_id\x18\x01 \x01(\tR\x05runId\x12!\n" + + "\fdecision_key\x18\x02 \x01(\tR\vdecisionKey\"\xcd\x02\n" + + "\fJudgeRequest\x12\x1c\n" + + "\tconnector\x18\x01 \x01(\tR\tconnector\x12\x12\n" + + "\x04name\x18\x02 \x01(\tR\x04name\x12\x14\n" + + "\x05input\x18\x03 \x01(\fR\x05input\x12\x16\n" + + "\x06digest\x18\x04 \x01(\tR\x06digest\x12(\n" + + "\x06target\x18\x05 \x01(\v2\x10.guard.v1.TargetR\x06target\x12(\n" + + "\x06effect\x18\x06 \x01(\v2\x10.guard.v1.EffectR\x06effect\x12&\n" + + "\x03run\x18\a \x01(\v2\x14.guard.v1.RunContextR\x03run\x125\n" + + "\bdeadline\x18\b \x01(\v2\x19.google.protobuf.DurationR\bdeadline\x12*\n" + + "\x02at\x18\t \x01(\v2\x1a.google.protobuf.TimestampR\x02at\"i\n" + + "\aFinding\x12\x12\n" + + "\x04text\x18\x01 \x01(\tR\x04text\x12\x1a\n" + + "\bevidence\x18\x02 \x01(\tR\bevidence\x12.\n" + + "\bstrength\x18\x03 \x01(\x0e2\x12.guard.v1.StrengthR\bstrength\"\x8c\x01\n" + + "\rJudgeResponse\x12+\n" + + "\aceiling\x18\x01 \x01(\x0e2\x11.guard.v1.CeilingR\aceiling\x12-\n" + + "\bfindings\x18\x02 \x03(\v2\x11.guard.v1.FindingR\bfindings\x12\x1f\n" + + "\vblind_spots\x18\x03 \x03(\tR\n" + + "blindSpots*\x95\x01\n" + + "\rReversibility\x12\x1d\n" + + "\x19REVERSIBILITY_UNSPECIFIED\x10\x00\x12&\n" + + "\"REVERSIBILITY_UNDONE_AUTOMATICALLY\x10\x01\x12\x1d\n" + + "\x19REVERSIBILITY_RECOVERABLE\x10\x02\x12\x1e\n" + + "\x1aREVERSIBILITY_IRREVERSIBLE\x10\x03*\x9c\x01\n" + + "\aCeiling\x12\x17\n" + + "\x13CEILING_UNSPECIFIED\x10\x00\x12\x17\n" + + "\x13CEILING_ACT_QUIETLY\x10\x01\x12\x18\n" + + "\x14CEILING_ACT_AND_TELL\x10\x02\x12\x1c\n" + + "\x18CEILING_PROPOSE_AND_WAIT\x10\x03\x12\x14\n" + + "\x10CEILING_ESCALATE\x10\x04\x12\x11\n" + + "\rCEILING_NEVER\x10\x05*c\n" + + "\bStrength\x12\x18\n" + + "\x14STRENGTH_UNSPECIFIED\x10\x00\x12\x11\n" + + "\rSTRENGTH_WEAK\x10\x01\x12\x15\n" + + "\x11STRENGTH_MODERATE\x10\x02\x12\x13\n" + + "\x0fSTRENGTH_STRONG\x10\x032\xd1\x01\n" + + "\fGuardService\x12D\n" + + "\tConfigure\x12\x1a.guard.v1.ConfigureRequest\x1a\x1b.guard.v1.ConfigureResponse\x12A\n" + + "\bDescribe\x12\x19.guard.v1.DescribeRequest\x1a\x1a.guard.v1.DescribeResponse\x128\n" + + "\x05Judge\x12\x16.guard.v1.JudgeRequest\x1a\x17.guard.v1.JudgeResponseB\xa4\x01\n" + + "\fcom.guard.v1B\n" + + "GuardProtoP\x01ZGgithub.com/samcharles93/archie-core/internal/contracts/guard/v1;guardv1\xa2\x02\x03GXX\xaa\x02\bGuard.V1\xca\x02\bGuard\\V1\xe2\x02\x14Guard\\V1\\GPBMetadata\xea\x02\tGuard::V1b\x06proto3" + +var ( + file_guard_v1_guard_proto_rawDescOnce sync.Once + file_guard_v1_guard_proto_rawDescData []byte +) + +func file_guard_v1_guard_proto_rawDescGZIP() []byte { + file_guard_v1_guard_proto_rawDescOnce.Do(func() { + file_guard_v1_guard_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_guard_v1_guard_proto_rawDesc), len(file_guard_v1_guard_proto_rawDesc))) + }) + return file_guard_v1_guard_proto_rawDescData +} + +var file_guard_v1_guard_proto_enumTypes = make([]protoimpl.EnumInfo, 3) +var file_guard_v1_guard_proto_msgTypes = make([]protoimpl.MessageInfo, 12) +var file_guard_v1_guard_proto_goTypes = []any{ + (Reversibility)(0), // 0: guard.v1.Reversibility + (Ceiling)(0), // 1: guard.v1.Ceiling + (Strength)(0), // 2: guard.v1.Strength + (*ConfigureRequest)(nil), // 3: guard.v1.ConfigureRequest + (*ConfigureResponse)(nil), // 4: guard.v1.ConfigureResponse + (*DescribeRequest)(nil), // 5: guard.v1.DescribeRequest + (*DescribeResponse)(nil), // 6: guard.v1.DescribeResponse + (*Effect)(nil), // 7: guard.v1.Effect + (*Target)(nil), // 8: guard.v1.Target + (*RunContext)(nil), // 9: guard.v1.RunContext + (*JudgeRequest)(nil), // 10: guard.v1.JudgeRequest + (*Finding)(nil), // 11: guard.v1.Finding + (*JudgeResponse)(nil), // 12: guard.v1.JudgeResponse + nil, // 13: guard.v1.ConfigureRequest.SettingsEntry + nil, // 14: guard.v1.ConfigureRequest.SecretsEntry + (*durationpb.Duration)(nil), // 15: google.protobuf.Duration + (*timestamppb.Timestamp)(nil), // 16: google.protobuf.Timestamp +} +var file_guard_v1_guard_proto_depIdxs = []int32{ + 13, // 0: guard.v1.ConfigureRequest.settings:type_name -> guard.v1.ConfigureRequest.SettingsEntry + 14, // 1: guard.v1.ConfigureRequest.secrets:type_name -> guard.v1.ConfigureRequest.SecretsEntry + 0, // 2: guard.v1.Effect.reversibility:type_name -> guard.v1.Reversibility + 8, // 3: guard.v1.JudgeRequest.target:type_name -> guard.v1.Target + 7, // 4: guard.v1.JudgeRequest.effect:type_name -> guard.v1.Effect + 9, // 5: guard.v1.JudgeRequest.run:type_name -> guard.v1.RunContext + 15, // 6: guard.v1.JudgeRequest.deadline:type_name -> google.protobuf.Duration + 16, // 7: guard.v1.JudgeRequest.at:type_name -> google.protobuf.Timestamp + 2, // 8: guard.v1.Finding.strength:type_name -> guard.v1.Strength + 1, // 9: guard.v1.JudgeResponse.ceiling:type_name -> guard.v1.Ceiling + 11, // 10: guard.v1.JudgeResponse.findings:type_name -> guard.v1.Finding + 3, // 11: guard.v1.GuardService.Configure:input_type -> guard.v1.ConfigureRequest + 5, // 12: guard.v1.GuardService.Describe:input_type -> guard.v1.DescribeRequest + 10, // 13: guard.v1.GuardService.Judge:input_type -> guard.v1.JudgeRequest + 4, // 14: guard.v1.GuardService.Configure:output_type -> guard.v1.ConfigureResponse + 6, // 15: guard.v1.GuardService.Describe:output_type -> guard.v1.DescribeResponse + 12, // 16: guard.v1.GuardService.Judge:output_type -> guard.v1.JudgeResponse + 14, // [14:17] is the sub-list for method output_type + 11, // [11:14] is the sub-list for method input_type + 11, // [11:11] is the sub-list for extension type_name + 11, // [11:11] is the sub-list for extension extendee + 0, // [0:11] is the sub-list for field type_name +} + +func init() { file_guard_v1_guard_proto_init() } +func file_guard_v1_guard_proto_init() { + if File_guard_v1_guard_proto != nil { + return + } + type x struct{} + out := protoimpl.TypeBuilder{ + File: protoimpl.DescBuilder{ + GoPackagePath: reflect.TypeOf(x{}).PkgPath(), + RawDescriptor: unsafe.Slice(unsafe.StringData(file_guard_v1_guard_proto_rawDesc), len(file_guard_v1_guard_proto_rawDesc)), + NumEnums: 3, + NumMessages: 12, + NumExtensions: 0, + NumServices: 1, + }, + GoTypes: file_guard_v1_guard_proto_goTypes, + DependencyIndexes: file_guard_v1_guard_proto_depIdxs, + EnumInfos: file_guard_v1_guard_proto_enumTypes, + MessageInfos: file_guard_v1_guard_proto_msgTypes, + }.Build() + File_guard_v1_guard_proto = out.File + file_guard_v1_guard_proto_goTypes = nil + file_guard_v1_guard_proto_depIdxs = nil +} diff --git a/internal/contracts/guard/v1/guard_grpc.pb.go b/internal/contracts/guard/v1/guard_grpc.pb.go new file mode 100644 index 000000000..edb5d5760 --- /dev/null +++ b/internal/contracts/guard/v1/guard_grpc.pb.go @@ -0,0 +1,219 @@ +// Code generated by protoc-gen-go-grpc. DO NOT EDIT. +// versions: +// - protoc-gen-go-grpc v1.6.2 +// - protoc (unknown) +// source: guard/v1/guard.proto + +package guardv1 + +import ( + context "context" + grpc "google.golang.org/grpc" + codes "google.golang.org/grpc/codes" + status "google.golang.org/grpc/status" +) + +// This is a compile-time assertion to ensure that this generated file +// is compatible with the grpc package it is being compiled against. +// Requires gRPC-Go v1.64.0 or later. +const _ = grpc.SupportPackageIsVersion9 + +const ( + GuardService_Configure_FullMethodName = "/guard.v1.GuardService/Configure" + GuardService_Describe_FullMethodName = "/guard.v1.GuardService/Describe" + GuardService_Judge_FullMethodName = "/guard.v1.GuardService/Judge" +) + +// GuardServiceClient is the client API for GuardService service. +// +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// GuardService is the surface a guard extension serves. A guard judges one +// concrete action and answers with a ceiling on the five-level scale. The host +// asks every running guard about every action and runs the action at the lowest +// ceiling. +type GuardServiceClient interface { + // Configure hands the guard its settings and resolved secrets, once, right + // after launch and before any Judge. + Configure(ctx context.Context, in *ConfigureRequest, opts ...grpc.CallOption) (*ConfigureResponse, error) + // Describe names the guard and says whether its verdicts count. + Describe(ctx context.Context, in *DescribeRequest, opts ...grpc.CallOption) (*DescribeResponse, error) + // Judge returns the guard's verdict on one action. The host enforces the + // request's deadline: a guard that errors, answers late or answers without + // a ceiling holds the action at propose and wait, unless it is advisory. + Judge(ctx context.Context, in *JudgeRequest, opts ...grpc.CallOption) (*JudgeResponse, error) +} + +type guardServiceClient struct { + cc grpc.ClientConnInterface +} + +func NewGuardServiceClient(cc grpc.ClientConnInterface) GuardServiceClient { + return &guardServiceClient{cc} +} + +func (c *guardServiceClient) Configure(ctx context.Context, in *ConfigureRequest, opts ...grpc.CallOption) (*ConfigureResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(ConfigureResponse) + err := c.cc.Invoke(ctx, GuardService_Configure_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *guardServiceClient) Describe(ctx context.Context, in *DescribeRequest, opts ...grpc.CallOption) (*DescribeResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(DescribeResponse) + err := c.cc.Invoke(ctx, GuardService_Describe_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +func (c *guardServiceClient) Judge(ctx context.Context, in *JudgeRequest, opts ...grpc.CallOption) (*JudgeResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(JudgeResponse) + err := c.cc.Invoke(ctx, GuardService_Judge_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +// GuardServiceServer is the server API for GuardService service. +// All implementations must embed UnimplementedGuardServiceServer +// for forward compatibility. +// +// GuardService is the surface a guard extension serves. A guard judges one +// concrete action and answers with a ceiling on the five-level scale. The host +// asks every running guard about every action and runs the action at the lowest +// ceiling. +type GuardServiceServer interface { + // Configure hands the guard its settings and resolved secrets, once, right + // after launch and before any Judge. + Configure(context.Context, *ConfigureRequest) (*ConfigureResponse, error) + // Describe names the guard and says whether its verdicts count. + Describe(context.Context, *DescribeRequest) (*DescribeResponse, error) + // Judge returns the guard's verdict on one action. The host enforces the + // request's deadline: a guard that errors, answers late or answers without + // a ceiling holds the action at propose and wait, unless it is advisory. + Judge(context.Context, *JudgeRequest) (*JudgeResponse, error) + mustEmbedUnimplementedGuardServiceServer() +} + +// UnimplementedGuardServiceServer must be embedded to have +// forward compatible implementations. +// +// NOTE: this should be embedded by value instead of pointer to avoid a nil +// pointer dereference when methods are called. +type UnimplementedGuardServiceServer struct{} + +func (UnimplementedGuardServiceServer) Configure(context.Context, *ConfigureRequest) (*ConfigureResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Configure not implemented") +} +func (UnimplementedGuardServiceServer) Describe(context.Context, *DescribeRequest) (*DescribeResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Describe not implemented") +} +func (UnimplementedGuardServiceServer) Judge(context.Context, *JudgeRequest) (*JudgeResponse, error) { + return nil, status.Error(codes.Unimplemented, "method Judge not implemented") +} +func (UnimplementedGuardServiceServer) mustEmbedUnimplementedGuardServiceServer() {} +func (UnimplementedGuardServiceServer) testEmbeddedByValue() {} + +// UnsafeGuardServiceServer may be embedded to opt out of forward compatibility for this service. +// Use of this interface is not recommended, as added methods to GuardServiceServer will +// result in compilation errors. +type UnsafeGuardServiceServer interface { + mustEmbedUnimplementedGuardServiceServer() +} + +func RegisterGuardServiceServer(s grpc.ServiceRegistrar, srv GuardServiceServer) { + // If the following call panics, it indicates UnimplementedGuardServiceServer was + // embedded by pointer and is nil. This will cause panics if an + // unimplemented method is ever invoked, so we test this at initialization + // time to prevent it from happening at runtime later due to I/O. + if t, ok := srv.(interface{ testEmbeddedByValue() }); ok { + t.testEmbeddedByValue() + } + s.RegisterService(&GuardService_ServiceDesc, srv) +} + +func _GuardService_Configure_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(ConfigureRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(GuardServiceServer).Configure(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: GuardService_Configure_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(GuardServiceServer).Configure(ctx, req.(*ConfigureRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _GuardService_Describe_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(DescribeRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(GuardServiceServer).Describe(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: GuardService_Describe_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(GuardServiceServer).Describe(ctx, req.(*DescribeRequest)) + } + return interceptor(ctx, in, info, handler) +} + +func _GuardService_Judge_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(JudgeRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(GuardServiceServer).Judge(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: GuardService_Judge_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(GuardServiceServer).Judge(ctx, req.(*JudgeRequest)) + } + return interceptor(ctx, in, info, handler) +} + +// GuardService_ServiceDesc is the grpc.ServiceDesc for GuardService service. +// It's only intended for direct use with grpc.RegisterService, +// and not to be introspected or modified (even as a copy) +var GuardService_ServiceDesc = grpc.ServiceDesc{ + ServiceName: "guard.v1.GuardService", + HandlerType: (*GuardServiceServer)(nil), + Methods: []grpc.MethodDesc{ + { + MethodName: "Configure", + Handler: _GuardService_Configure_Handler, + }, + { + MethodName: "Describe", + Handler: _GuardService_Describe_Handler, + }, + { + MethodName: "Judge", + Handler: _GuardService_Judge_Handler, + }, + }, + Streams: []grpc.StreamDesc{}, + Metadata: "guard/v1/guard.proto", +} diff --git a/internal/platform/pg/migrations/00024_connectors_guard_contract.sql b/internal/platform/pg/migrations/00024_connectors_guard_contract.sql new file mode 100644 index 000000000..a063fa352 --- /dev/null +++ b/internal/platform/pg/migrations/00024_connectors_guard_contract.sql @@ -0,0 +1,12 @@ +-- +goose Up +-- A guard extension is an accepted package like a connector or a secret engine. +ALTER TABLE connectors.accepted DROP CONSTRAINT accepted_contract_check; +ALTER TABLE connectors.accepted + ADD CONSTRAINT accepted_contract_check + CHECK (contract IN ('connector', 'secretengine', 'mcp', 'guard')); + +-- +goose Down +DELETE FROM connectors.accepted WHERE contract = 'guard'; +ALTER TABLE connectors.accepted DROP CONSTRAINT accepted_contract_check; +ALTER TABLE connectors.accepted + ADD CONSTRAINT accepted_contract_check CHECK (contract IN ('connector', 'secretengine', 'mcp')); diff --git a/modules/connectors/guards.go b/modules/connectors/guards.go new file mode 100644 index 000000000..bfd4fa0d2 --- /dev/null +++ b/modules/connectors/guards.go @@ -0,0 +1,148 @@ +package connectors + +import ( + "context" + "errors" + "fmt" + "time" + + goplugin "github.com/hashicorp/go-plugin" + "google.golang.org/grpc" + "google.golang.org/protobuf/types/known/durationpb" + "google.golang.org/protobuf/types/known/timestamppb" + + gpb "github.com/samcharles93/archie-core/internal/contracts/guard/v1" + "github.com/samcharles93/archie-core/modules/connectors/internal/host" +) + +// guardSurface names the guard contract in the plugin handshake. +const guardSurface = "guard" + +// GuardRequest is one concrete action put to a guard extension. +type GuardRequest struct { + Connector string + Name string + Input []byte + Digest string + Target Target + Effect Effect + RunID string + DecisionKey string + // Deadline is how long the host waits; the caller's context enforces it. + Deadline time.Duration + At time.Time +} + +// GuardFinding is one thing a guard noticed. Strength is "weak", "moderate" +// or "strong", or empty when the guard didn't say. +type GuardFinding struct { + Text string + Evidence string + Strength string +} + +// GuardAnswer is a guard extension's verdict. Ceiling is 1 (act quietly) to 5 +// (never), or 0 when the guard gave none. +type GuardAnswer struct { + Ceiling int + Findings []GuardFinding + BlindSpots []string +} + +// Guard is a running guard extension. +type Guard struct { + name string + version string + digest string + advisory bool + client gpb.GuardServiceClient +} + +// NewGuard wraps a client of a guard extension. digest is the package digest +// recorded with every verdict. +func NewGuard(name, version, digest string, advisory bool, client gpb.GuardServiceClient) *Guard { + return &Guard{name: name, version: version, digest: digest, advisory: advisory, client: client} +} + +// Name is the guard's name in verdicts. +func (g *Guard) Name() string { return g.name } + +// Version is the guard's own release, as it described itself. +func (g *Guard) Version() string { return g.version } + +// Digest is the SHA-256 of the package that is running. +func (g *Guard) Digest() string { return g.digest } + +// Advisory says the guard's verdicts set no ceiling. +func (g *Guard) Advisory() bool { return g.advisory } + +// Judge asks the guard about one action. ctx bounds the wait. +func (g *Guard) Judge(ctx context.Context, r GuardRequest) (GuardAnswer, error) { + resp, err := g.client.Judge(ctx, &gpb.JudgeRequest{ + Connector: r.Connector, Name: r.Name, Input: r.Input, Digest: r.Digest, + Target: &gpb.Target{Kind: r.Target.Kind, Id: r.Target.ID, Environment: r.Target.Environment, Disposable: r.Target.Disposable}, + Effect: &gpb.Effect{ReadOnly: r.Effect.ReadOnly, Reversibility: gpb.Reversibility(r.Effect.Reversibility), Summary: r.Effect.Summary}, + Run: &gpb.RunContext{RunId: r.RunID, DecisionKey: r.DecisionKey}, + Deadline: durationpb.New(r.Deadline), + At: timestamppb.New(r.At), + }) + if err != nil { + return GuardAnswer{}, fmt.Errorf("guard %q: %w", g.name, err) + } + a := GuardAnswer{Ceiling: int(resp.GetCeiling()), BlindSpots: resp.GetBlindSpots()} + for _, f := range resp.GetFindings() { + a.Findings = append(a.Findings, GuardFinding{Text: f.GetText(), Evidence: f.GetEvidence(), Strength: strengthName(f.GetStrength())}) + } + return a, nil +} + +func strengthName(s gpb.Strength) string { + switch s { + case gpb.Strength_STRENGTH_WEAK: + return "weak" + case gpb.Strength_STRENGTH_MODERATE: + return "moderate" + case gpb.Strength_STRENGTH_STRONG: + return "strong" + } + return "" +} + +// StartGuard launches a guard extension, configures it and asks it to +// describe itself. +func (h *Host) StartGuard(ctx context.Context, spec Spec) (*Guard, error) { + raw, err := h.procs.Start(ctx, host.Spec{ + Name: spec.Name, Path: spec.Path, SHA256: spec.SHA256, Env: spec.Env, Egress: spec.Egress, + }, guardSurface, &guardPlugin{}) + if err != nil { + return nil, err + } + client, ok := raw.(gpb.GuardServiceClient) + if !ok { + h.procs.Stop(spec.Name) + return nil, fmt.Errorf("guard %q: plugin is not a guard", spec.Name) + } + if _, err := client.Configure(ctx, &gpb.ConfigureRequest{Settings: spec.Settings, Secrets: spec.Secrets}); err != nil { + h.procs.Stop(spec.Name) + return nil, fmt.Errorf("guard %q: configure: %w", spec.Name, err) + } + desc, err := client.Describe(ctx, &gpb.DescribeRequest{}) + if err != nil { + h.procs.Stop(spec.Name) + return nil, fmt.Errorf("guard %q: describe: %w", spec.Name, err) + } + return NewGuard(spec.Name, desc.GetVersion(), spec.SHA256, desc.GetAdvisory(), client), nil +} + +// guardPlugin is the host side of the go-plugin handshake for guards. +type guardPlugin struct { + goplugin.NetRPCUnsupportedPlugin +} + +func (*guardPlugin) GRPCServer(*goplugin.GRPCBroker, *grpc.Server) error { + return errors.New("guards are served by extensions, not by the host") +} + +func (*guardPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, conn *grpc.ClientConn) (any, error) { + return gpb.NewGuardServiceClient(conn), nil +} diff --git a/modules/connectors/internal/store/store.go b/modules/connectors/internal/store/store.go index b600feef7..682b2377c 100644 --- a/modules/connectors/internal/store/store.go +++ b/modules/connectors/internal/store/store.go @@ -24,7 +24,8 @@ type Accepted struct { Egress Strings `db:"egress"` Env Strings `db:"env"` Settings jsontext.Value `db:"settings"` - // Contract is ContractConnector, ContractSecretEngine or ContractMCP. + // Contract is ContractConnector, ContractSecretEngine, ContractMCP or + // ContractGuard. Contract string `db:"contract"` // Credentials maps a slot to a credential name, as a JSON object. Credentials jsontext.Value `db:"credentials"` @@ -42,6 +43,7 @@ const ( ContractConnector = "connector" ContractSecretEngine = "secretengine" ContractMCP = "mcp" + ContractGuard = "guard" ) // Credential is a credential's sealed fields. diff --git a/modules/connectors/module.go b/modules/connectors/module.go index c6934a923..fd996c584 100644 --- a/modules/connectors/module.go +++ b/modules/connectors/module.go @@ -26,7 +26,7 @@ import ( // validName is the shape of a connector name: it appears in logs and URLs. var validName = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`) -// Module runs an organisation's accepted connectors and secret engines, +// Module runs an organisation's accepted connectors, secret engines and guards, // keeps the credentials they are configured with, and serves their // administration. type Module struct { @@ -39,6 +39,7 @@ type Module struct { mu sync.RWMutex running map[string]*Connector engines map[string]*Engine + guards map[string]*Guard // servers are the accepted MCP servers, and stops ends each one's // supervisor. servers map[string]*Server @@ -71,7 +72,7 @@ func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, sealing Sealing) (*M } return &Module{ orgID: orgID, host: NewHost(log), store: store.New(db), sealer: sealer, log: log, - running: map[string]*Connector{}, engines: map[string]*Engine{}, failed: map[string]string{}, + running: map[string]*Connector{}, engines: map[string]*Engine{}, guards: map[string]*Guard{}, failed: map[string]string{}, servers: map[string]*Server{}, stops: map[string]context.CancelFunc{}, }, nil } @@ -131,6 +132,17 @@ func (m *Module) Tool(name string) (Tool, bool) { return s, ok } +// Guards lists the running guard extensions in name order. +func (m *Module) Guards() []*Guard { + m.mu.RLock() + defer m.mu.RUnlock() + var out []*Guard + for _, name := range slices.Sorted(maps.Keys(m.guards)) { + out = append(out, m.guards[name]) + } + return out +} + // Delivering lists the running connectors that send the named delivery, in // name order: the channels a message goes out on. func (m *Module) Delivering(delivery string) []*Connector { @@ -178,6 +190,11 @@ func (m *Module) Ready(context.Context) error { problems = append(problems, name+": process exited") } } + for name := range m.guards { + if !m.host.Alive(name) { + problems = append(problems, name+": process exited") + } + } servers := maps.Clone(m.servers) m.mu.RUnlock() for _, name := range slices.Sorted(maps.Keys(servers)) { @@ -211,9 +228,11 @@ func (m *Module) Close() { func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { mux.Handle("PUT /api/connectors/{name}", guard(m.accept(store.ContractConnector))) mux.Handle("PUT /api/secret-engines/{name}", guard(m.accept(store.ContractSecretEngine))) + mux.Handle("PUT /api/guards/{name}", guard(m.accept(store.ContractGuard))) mux.Handle("PUT /api/mcp-servers/{name}", guard(http.HandlerFunc(m.acceptServer))) mux.Handle("DELETE /api/connectors/{name}", guard(m.remove(store.ContractConnector))) mux.Handle("DELETE /api/secret-engines/{name}", guard(m.remove(store.ContractSecretEngine))) + mux.Handle("DELETE /api/guards/{name}", guard(m.remove(store.ContractGuard))) mux.Handle("DELETE /api/mcp-servers/{name}", guard(m.remove(store.ContractMCP))) mux.Handle("PUT /api/credentials/{name}", guard(http.HandlerFunc(m.putCredential))) mux.Handle("GET /api/credentials", guard(http.HandlerFunc(m.listCredentials))) @@ -307,6 +326,18 @@ func (m *Module) launch(ctx context.Context, a store.Accepted) error { m.log.InfoContext(ctx, "secret engine started", "engine", a.Name) return nil } + if a.Contract == store.ContractGuard { + g, err := m.host.StartGuard(ctx, spec) + if err != nil { + return m.fail(ctx, a.Name, err) + } + m.mu.Lock() + m.guards[a.Name] = g + delete(m.failed, a.Name) + m.mu.Unlock() + m.log.InfoContext(ctx, "guard started", "guard", a.Name) + return nil + } c, err := m.host.Start(ctx, spec) if err != nil { return m.fail(ctx, a.Name, err) @@ -325,13 +356,15 @@ func (m *Module) release(name string) { m.mu.Lock() _, running := m.running[name] _, engine := m.engines[name] + _, guard := m.guards[name] s, stop := m.servers[name], m.stops[name] delete(m.running, name) delete(m.engines, name) + delete(m.guards, name) delete(m.servers, name) delete(m.stops, name) m.mu.Unlock() - if running || engine { + if running || engine || guard { m.host.Stop(name) } if stop != nil { @@ -346,6 +379,7 @@ func (m *Module) fail(ctx context.Context, name string, err error) error { m.mu.Lock() delete(m.running, name) delete(m.engines, name) + delete(m.guards, name) m.failed[name] = err.Error() m.mu.Unlock() m.log.ErrorContext(ctx, "extension failed to start", "extension", name, "error", err) diff --git a/modules/judgement/extensions.go b/modules/judgement/extensions.go new file mode 100644 index 000000000..3d709b586 --- /dev/null +++ b/modules/judgement/extensions.go @@ -0,0 +1,73 @@ +package judgement + +import ( + "context" + "time" + + "github.com/google/uuid" + + "github.com/samcharles93/archie-core/modules/connectors" +) + +// GuardExtensions lists the guard extensions running now. +type GuardExtensions interface { + Guards() []*connectors.Guard +} + +// identified is a guard that says which package answered. +type identified interface { + Version() string + Digest() string +} + +// RunContext is the run an action belongs to, passed to guards that want it. +type RunContext struct { + RunID uuid.UUID + Key string +} + +type runKey struct{} + +func withRun(ctx context.Context, r RunContext) context.Context { + return context.WithValue(ctx, runKey{}, r) +} + +func runFrom(ctx context.Context) RunContext { + r, _ := ctx.Value(runKey{}).(RunContext) + return r +} + +// extensionGuard adapts a guard extension to Guard. +type extensionGuard struct { + g *connectors.Guard +} + +func (e extensionGuard) Name() string { return e.g.Name() } +func (e extensionGuard) Advisory() bool { return e.g.Advisory() } +func (e extensionGuard) Version() string { return e.g.Version() } +func (e extensionGuard) Digest() string { return e.g.Digest() } + +// Judge puts the action to the extension. The caller's context carries the +// deadline the host enforces. A ceiling outside the scale is left for judge to +// hold. +func (e extensionGuard) Judge(ctx context.Context, a Action) (Verdict, error) { + run := runFrom(ctx) + req := connectors.GuardRequest{ + Connector: a.Connector, Name: a.Name, Input: a.Input, Digest: a.Digest, + Target: a.Target, Effect: a.Effect, + RunID: run.RunID.String(), DecisionKey: run.Key, + At: time.Now(), + } + if d, ok := ctx.Deadline(); ok { + req.Deadline = time.Until(d) + } + ans, err := e.g.Judge(ctx, req) + if err != nil { + return Verdict{}, err + } + v := Verdict{Ceiling: Level(ans.Ceiling), BlindSpots: ans.BlindSpots} + for _, f := range ans.Findings { + v.Findings = append(v.Findings, Finding{Text: f.Text, Evidence: f.Evidence, Strength: f.Strength}) + } + return v, nil +} diff --git a/modules/judgement/extensions_test.go b/modules/judgement/extensions_test.go new file mode 100644 index 000000000..309033ad8 --- /dev/null +++ b/modules/judgement/extensions_test.go @@ -0,0 +1,134 @@ +package judgement + +import ( + "context" + "errors" + "testing" + "time" + + "google.golang.org/grpc" + + gpb "github.com/samcharles93/archie-core/internal/contracts/guard/v1" + "github.com/samcharles93/archie-core/modules/connectors" +) + +// fakeGuardClient answers Judge as a guard extension's client would. +type fakeGuardClient struct { + resp *gpb.JudgeResponse + err error + // hang blocks until the host's deadline ends the call. + hang bool +} + +func (*fakeGuardClient) Configure(context.Context, *gpb.ConfigureRequest, ...grpc.CallOption) (*gpb.ConfigureResponse, error) { + return &gpb.ConfigureResponse{}, nil +} + +func (*fakeGuardClient) Describe(context.Context, *gpb.DescribeRequest, ...grpc.CallOption) (*gpb.DescribeResponse, error) { + return &gpb.DescribeResponse{}, nil +} + +func (c *fakeGuardClient) Judge(ctx context.Context, _ *gpb.JudgeRequest, _ ...grpc.CallOption) (*gpb.JudgeResponse, error) { + if c.hang { + <-ctx.Done() + return nil, ctx.Err() + } + return c.resp, c.err +} + +type extensions []*connectors.Guard + +func (e extensions) Guards() []*connectors.Guard { return e } + +// TestGuardExtensionsDecideAtTheLowestCeiling guards the extension path of the +// weakest-link decision (spec section 5, R22): two guard extensions judging +// one action run it at the lower ceiling, a guard that errors, times out or +// answers without a ceiling holds it, an advisory verdict is recorded without +// setting the level, and every verdict names the package that answered. +func TestGuardExtensionsDecideAtTheLowestCeiling(t *testing.T) { + answer := func(c gpb.Ceiling) *gpb.JudgeResponse { + return &gpb.JudgeResponse{Ceiling: c, Findings: []*gpb.Finding{{Text: "seen", Evidence: "log", Strength: gpb.Strength_STRENGTH_STRONG}}} + } + guard := func(name string, advisory bool, c *fakeGuardClient) *connectors.Guard { + return connectors.NewGuard(name, "1.0.0", "digest-"+name, advisory, c) + } + tests := []struct { + name string + guards []*connectors.Guard + want Level + wantFailed string + }{ + { + name: "the lower of two ceilings wins", + guards: []*connectors.Guard{ + guard("hours", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ACT_AND_TELL)}), + guard("budget", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ESCALATE)}), + }, + want: Escalate, + }, + { + name: "a failing guard holds the action", + guards: []*connectors.Guard{ + guard("hours", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ACT_QUIETLY)}), + guard("broken", false, &fakeGuardClient{err: errors.New("unavailable")}), + }, + want: ProposeAndWait, wantFailed: "broken", + }, + { + name: "a guard that outlasts the deadline holds the action", + guards: []*connectors.Guard{ + guard("hours", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ACT_QUIETLY)}), + guard("slow", false, &fakeGuardClient{hang: true}), + }, + want: ProposeAndWait, wantFailed: "slow", + }, + { + name: "a guard answering without a ceiling holds the action", + guards: []*connectors.Guard{ + guard("hours", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ACT_QUIETLY)}), + guard("partial", false, &fakeGuardClient{resp: &gpb.JudgeResponse{}}), + }, + want: ProposeAndWait, wantFailed: "partial", + }, + { + name: "an advisory verdict sets no level", + guards: []*connectors.Guard{ + guard("hours", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ACT_QUIETLY)}), + guard("opinion", true, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_NEVER)}), + }, + want: ActQuietly, + }, + { + name: "a failing advisory guard sets no level", + guards: []*connectors.Guard{ + guard("hours", false, &fakeGuardClient{resp: answer(gpb.Ceiling_CEILING_ACT_AND_TELL)}), + guard("opinion", true, &fakeGuardClient{err: errors.New("unavailable")}), + }, + want: ActAndTell, wantFailed: "opinion", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + m := &Module{timeout: 50 * time.Millisecond} + m.UseExtensions(extensions(tt.guards)) + d := m.decide(t.Context(), Action{Connector: "c", Name: "delete"}) + if d.Level != tt.want { + t.Fatalf("level = %s, want %s (verdicts %+v)", d.Level, tt.want, d.Verdicts) + } + if len(d.Verdicts) != len(tt.guards) { + t.Fatalf("verdicts = %d, want one per guard", len(d.Verdicts)) + } + for i, v := range d.Verdicts { + if v.Guard != tt.guards[i].Name() || v.Digest != "digest-"+v.Guard || v.Version != "1.0.0" { + t.Fatalf("verdict %d = %+v, want the guard's name, version and package digest", i, v) + } + if (v.Failed != "") != (v.Guard == tt.wantFailed) { + t.Fatalf("verdict %q failed = %q, want failure only for %q", v.Guard, v.Failed, tt.wantFailed) + } + if v.Failed == "" && (len(v.Findings) != 1 || v.Findings[0].Strength != "strong" || v.Findings[0].Evidence != "log") { + t.Fatalf("verdict %q lost its findings: %+v", v.Guard, v.Findings) + } + } + }) + } +} diff --git a/modules/judgement/judgement.go b/modules/judgement/judgement.go index f4866958b..3f06c9db6 100644 --- a/modules/judgement/judgement.go +++ b/modules/judgement/judgement.go @@ -11,6 +11,7 @@ import ( "errors" "fmt" "log/slog" + "slices" "sync" "time" @@ -63,11 +64,18 @@ func (a Action) Class() Class { type Finding struct { Text string `json:"text"` Evidence string `json:"evidence,omitzero"` + // Strength is how much the evidence supports the finding: weak, moderate + // or strong. + Strength string `json:"strength,omitzero"` } // Verdict is one guard's judgement of one action. type Verdict struct { - Guard string `json:"guard"` + Guard string `json:"guard"` + // Version and Digest say which extension answered: its own release and + // the digest of the package that ran. Built-in guards have neither. + Version string `json:"version,omitzero"` + Digest string `json:"digest,omitzero"` Ceiling Level `json:"ceiling"` Findings []Finding `json:"findings,omitzero"` BlindSpots []string `json:"blind_spots,omitzero"` @@ -144,10 +152,18 @@ type Module struct { guards []Guard store recorder failed FailureRecorder - log *slog.Logger - now func() time.Time + // extensions are the guard extensions asked alongside the built-in guards. + extensions GuardExtensions + // timeout bounds one guard; zero means guardTimeout. + timeout time.Duration + log *slog.Logger + now func() time.Time } +// UseExtensions makes the module ask every running guard extension alongside +// its built-in guards, on each decision. +func (m *Module) UseExtensions(e GuardExtensions) { m.extensions = e } + // NewModule returns the judgement module for orgID, with its hard rules and // guards. An action of a class that fails is reported to failed. func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tools Tools, rules []HardRule, guards []Guard, failed FailureRecorder) *Module { @@ -169,7 +185,7 @@ func (m *Module) Assess(ctx context.Context, req Request) (Decision, error) { Connector: req.Connector, Name: req.Action, Input: req.Input, Digest: connectors.Digest(req.Action, req.Input), Target: res.Target, Effect: res.Effect, } - d := m.decide(ctx, a) + d := m.decide(withRun(ctx, RunContext{RunID: req.RunID, Key: req.Key}), a) d.ID, d.RunID, d.Key, d.At = uuid.New(), req.RunID, req.Key, m.now().UTC() return m.record(ctx, d) } @@ -182,10 +198,16 @@ func (m *Module) decide(ctx context.Context, a Action) Decision { return Decision{Action: a, Level: Never, RefusedBy: r.Name(), Reason: reason, Verdicts: []Verdict{}} } } - verdicts := make([]Verdict, len(m.guards)) + guards := slices.Clone(m.guards) + if m.extensions != nil { + for _, e := range m.extensions.Guards() { + guards = append(guards, extensionGuard{e}) + } + } + verdicts := make([]Verdict, len(guards)) var wg sync.WaitGroup - for i, g := range m.guards { - wg.Go(func() { verdicts[i] = judge(ctx, g, a) }) + for i, g := range guards { + wg.Go(func() { verdicts[i] = judge(ctx, g, a, m.guardTimeout()) }) } wg.Wait() ceilings := []Level{} @@ -203,11 +225,15 @@ func (m *Module) decide(ctx context.Context, a Action) Decision { // judge asks one guard, turning a failure, a timeout or a missing ceiling // into propose and wait. A panic is a failure too. -func judge(ctx context.Context, g Guard, a Action) (v Verdict) { - ctx, cancel := context.WithTimeout(ctx, guardTimeout) +func judge(ctx context.Context, g Guard, a Action, timeout time.Duration) (v Verdict) { + ctx, cancel := context.WithTimeout(ctx, timeout) defer cancel() failed := func(why string) Verdict { - return Verdict{Guard: g.Name(), Ceiling: ProposeAndWait, Advisory: g.Advisory(), Failed: why} + v := Verdict{Guard: g.Name(), Ceiling: ProposeAndWait, Advisory: g.Advisory(), Failed: why} + if e, ok := g.(identified); ok { + v.Version, v.Digest = e.Version(), e.Digest() + } + return v } defer func() { if r := recover(); r != nil { @@ -222,9 +248,19 @@ func judge(ctx context.Context, g Guard, a Action) (v Verdict) { return failed("returned no ceiling") } got.Guard, got.Advisory = g.Name(), g.Advisory() + if e, ok := g.(identified); ok { + got.Version, got.Digest = e.Version(), e.Digest() + } return got } +func (m *Module) guardTimeout() time.Duration { + if m.timeout > 0 { + return m.timeout + } + return guardTimeout +} + // 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) { diff --git a/proto/guard/v1/guard.proto b/proto/guard/v1/guard.proto new file mode 100644 index 000000000..84aeaf8c6 --- /dev/null +++ b/proto/guard/v1/guard.proto @@ -0,0 +1,113 @@ +syntax = "proto3"; + +package guard.v1; + +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +// GuardService is the surface a guard extension serves. A guard judges one +// concrete action and answers with a ceiling on the five-level scale. The host +// asks every running guard about every action and runs the action at the lowest +// ceiling. +service GuardService { + // Configure hands the guard its settings and resolved secrets, once, right + // after launch and before any Judge. + rpc Configure(ConfigureRequest) returns (ConfigureResponse); + // Describe names the guard and says whether its verdicts count. + rpc Describe(DescribeRequest) returns (DescribeResponse); + // Judge returns the guard's verdict on one action. The host enforces the + // request's deadline: a guard that errors, answers late or answers without + // a ceiling holds the action at propose and wait, unless it is advisory. + rpc Judge(JudgeRequest) returns (JudgeResponse); +} + +message ConfigureRequest { + map settings = 1; + map secrets = 2; +} +message ConfigureResponse {} + +message DescribeRequest {} +message DescribeResponse { + // contract is the contract version the guard speaks, "v1". + string contract = 1; + string name = 2; + // version is the guard's own release, recorded with each verdict. + string version = 3; + // advisory says the guard's verdicts are recorded and set no ceiling. + bool advisory = 4; +} + +enum Reversibility { + REVERSIBILITY_UNSPECIFIED = 0; + REVERSIBILITY_UNDONE_AUTOMATICALLY = 1; + REVERSIBILITY_RECOVERABLE = 2; + REVERSIBILITY_IRREVERSIBLE = 3; +} + +message Effect { + bool read_only = 1; + Reversibility reversibility = 2; + string summary = 3; +} + +message Target { + string kind = 1; + string id = 2; + string environment = 3; + bool disposable = 4; +} + +// Ceiling is the five-level scale, from the most autonomy to the least. +enum Ceiling { + CEILING_UNSPECIFIED = 0; + CEILING_ACT_QUIETLY = 1; + CEILING_ACT_AND_TELL = 2; + CEILING_PROPOSE_AND_WAIT = 3; + CEILING_ESCALATE = 4; + CEILING_NEVER = 5; +} + +// Strength is how much a finding's evidence supports it. +enum Strength { + STRENGTH_UNSPECIFIED = 0; + STRENGTH_WEAK = 1; + STRENGTH_MODERATE = 2; + STRENGTH_STRONG = 3; +} + +message RunContext { + string run_id = 1; + // decision_key identifies the attempt to run the action. + string decision_key = 2; +} + +message JudgeRequest { + string connector = 1; + string name = 2; + bytes input = 3; + // digest identifies the exact action: its name and input. + string digest = 4; + Target target = 5; + Effect effect = 6; + RunContext run = 7; + // deadline is how long the host waits for the verdict. + google.protobuf.Duration deadline = 8; + // at is the host's clock when the action was put to the guard. + google.protobuf.Timestamp at = 9; +} + +message Finding { + string text = 1; + // evidence is what the finding rests on, in plain words. + string evidence = 2; + Strength strength = 3; +} + +message JudgeResponse { + // ceiling must be set. A guard with no concern answers CEILING_ACT_QUIETLY. + Ceiling ceiling = 1; + repeated Finding findings = 2; + // blind_spots are what the guard could not see. + repeated string blind_spots = 3; +}