Files

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
}