233 lines
7.6 KiB
Go
233 lines
7.6 KiB
Go
package connectors
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json/jsontext"
|
|
json "encoding/json/v2"
|
|
"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
|
|
// Diagnosis and Evidence are what the proposing agent concluded and read.
|
|
Diagnosis string
|
|
Evidence []GuardEvidence
|
|
}
|
|
|
|
// GuardEvidence is one tool result the agent read.
|
|
type GuardEvidence struct {
|
|
Source string
|
|
Text string
|
|
}
|
|
|
|
// 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
|
|
Judges []GuardJudge
|
|
}
|
|
|
|
// GuardJudge is what one model judge answered and what it was judged on.
|
|
// Answers is the judge service's answers as JSON.
|
|
type GuardJudge struct {
|
|
Model string
|
|
ResultID string
|
|
Answer string
|
|
Confidence float64
|
|
Reason string
|
|
Basis string
|
|
BasisDigest string
|
|
Answers []byte
|
|
Trusted bool
|
|
AdvisoryReason string
|
|
EvalDate string
|
|
// Request and Response are what the judge endpoint was sent and what it
|
|
// returned, both kept as the exact bodies for audit.
|
|
Request jsontext.Value
|
|
Response jsontext.Value
|
|
EndpointPath string
|
|
HTTPStatus int
|
|
LatencyMS int64
|
|
}
|
|
|
|
// Guard is a running guard extension.
|
|
type Guard struct {
|
|
name string
|
|
version string
|
|
digest string
|
|
advisory bool
|
|
values map[string]string
|
|
settings []Setting
|
|
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, values map[string]string, settings []Setting, client gpb.GuardServiceClient) *Guard {
|
|
return &Guard{
|
|
name: name, version: version, digest: digest, advisory: advisory,
|
|
values: values, settings: settings, 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 }
|
|
|
|
// SettingsSchema is what the guard declared an operator enters, including the
|
|
// judge it asks.
|
|
func (g *Guard) SettingsSchema() []Setting { return g.settings }
|
|
|
|
// Settings is what the guard was configured with. A secret is the reference
|
|
// the guard resolves, never its value.
|
|
func (g *Guard) Settings() map[string]string { return g.values }
|
|
|
|
// Judge asks the guard about one action. ctx bounds the wait.
|
|
func (g *Guard) Judge(ctx context.Context, r GuardRequest) (GuardAnswer, error) {
|
|
evidence := make([]*gpb.Evidence, 0, len(r.Evidence))
|
|
for _, e := range r.Evidence {
|
|
evidence = append(evidence, &gpb.Evidence{Source: e.Source, Text: e.Text})
|
|
}
|
|
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),
|
|
Diagnosis: r.Diagnosis, Evidence: evidence,
|
|
})
|
|
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())})
|
|
}
|
|
for _, j := range resp.GetJudges() {
|
|
a.Judges = append(a.Judges, GuardJudge{
|
|
Model: j.GetModel(), ResultID: j.GetResultId(), Answer: j.GetAnswer(), Confidence: j.GetConfidence(),
|
|
Reason: j.GetReason(), Basis: j.GetBasis(), BasisDigest: j.GetBasisDigest(), Answers: j.GetAnswers(),
|
|
Trusted: j.GetTrusted(), AdvisoryReason: j.GetAdvisoryReason(), EvalDate: j.GetEvalDate(),
|
|
Request: jsonValue(j.GetRequest()), Response: jsonValue(j.GetResponse()),
|
|
EndpointPath: j.GetEndpointPath(), HTTPStatus: int(j.GetHttpStatus()), LatencyMS: j.GetLatencyMs(),
|
|
})
|
|
}
|
|
return a, nil
|
|
}
|
|
|
|
// jsonValue keeps a recorded body verbatim when it is JSON, and quotes it when
|
|
// it is not, so the stored verdict always carries a valid JSON value.
|
|
func jsonValue(b []byte) jsontext.Value {
|
|
if len(b) == 0 {
|
|
return nil
|
|
}
|
|
v := jsontext.Value(b)
|
|
if v.IsValid() {
|
|
return v
|
|
}
|
|
quoted, err := json.Marshal(string(b))
|
|
if err != nil {
|
|
return nil
|
|
}
|
|
return quoted
|
|
}
|
|
|
|
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)
|
|
}
|
|
settings := guardSettings(desc.GetSettings())
|
|
if err := validateSettingsSchema(settings); err != nil {
|
|
h.procs.Stop(spec.Name)
|
|
return nil, fmt.Errorf("guard %q: %w", spec.Name, err)
|
|
}
|
|
return NewGuard(spec.Name, desc.GetVersion(), spec.SHA256, desc.GetAdvisory(), spec.Settings, settings, 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
|
|
}
|