Documentation
¶
Overview ¶
Package abi is the OSCTF plugin ABI surface SHARED by the host and by plugin authors: the go-plugin handshake, the ABI version, the dispense keys, and the gRPC transport bridge to the generated stubs (pluginpb).
It is deliberately a LEAF: it imports go-plugin, grpc, and pluginpb, and nothing else. The host loader (internal/plugin) and the public SDK (plugin/sdk) both build on it, so a plugin author links the ABI without linking the loader — and therefore without inheriting the platform's server-side dependencies (the database driver, the metrics stack). Keep it that way: an import added here is an import every plugin in existence inherits.
See docs/v0.3/02-plugin-abi.md and 03-plugin-loader.md.
Index ¶
Constants ¶
const ( KeyAuth = "auth" KeyScoring = "scoring" KeyNotification = "notification" KeyChallengeType = "challenge_type" )
Dispense keys — one per plugin type. A plugin serves exactly the one its manifest `type` declares; the host dispenses that key and receives the matching gRPC client.
const ABIMajor = 1
ABIMajor is the go-plugin ProtocolVersion — the ABI MAJOR, bumped ONLY on a breaking change. A plugin built against a different major is refused by go-plugin before any call; the loader logs "ABI major mismatch" and skips it (no crash, no partial init).
const ABIMinor = 1
ABIMinor is the host's ABI minor. 1.1 added Identity.email_verified, which the auth return path requires before binding a login to an existing account by email; a plugin on 1.0 simply leaves it false and fails closed. Minor is forward-compatible: the host may call a plugin advertising an OLDER minor (it won't invoke methods/fields the plugin lacks), and a plugin advertising a NEWER minor is accepted (the host uses only what it knows). Carried per-plugin in the manifest and the Info RPC.
const ABIString = "1.1"
ABIString is the host's advertised "major.minor".
const PluginConfigEnv = "OSCTF_PLUGIN_CONFIG"
PluginConfigEnv is the single environment variable the host sets on the PLUGIN process carrying its resolved config as a JSON object. It is the SHARED definition: the host writes it (see internal/plugin) and the public SDK's Config() reads it, so the two sides cannot drift — the pairing is one source of truth, not two strings that must agree. One var (not per-key) so a plugin never reconstructs the host's OSCTF_PLUGIN_<NAME>_<KEY> override names — it just asks for a key.
Variables ¶
var Handshake = goplugin.HandshakeConfig{ ProtocolVersion: ABIMajor, MagicCookieKey: "OSCTF_PLUGIN", MagicCookieValue: "osctf-plugin-v1", }
Handshake gates every plugin connection. The magic cookie guards against launching a non-OSCTF binary; ProtocolVersion is the ABI major (a mismatch is refused pre-call).
Functions ¶
func HostPluginSet ¶
HostPluginSet is the set the host offers when dialing a plugin. Each entry's Impl is nil on the host side; Dispense returns the generated gRPC client. The SDK builds the mirror set with Impls set (the plugin author's implementation).
Types ¶
type AuthGRPCPlugin ¶
type AuthGRPCPlugin struct {
goplugin.NetRPCUnsupportedPlugin
Impl pluginpb.AuthServer
}
AuthGRPCPlugin bridges the Auth service.
func (*AuthGRPCPlugin) GRPCClient ¶
func (p *AuthGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)
func (*AuthGRPCPlugin) GRPCServer ¶
func (p *AuthGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error
type ChallengeTypeGRPCPlugin ¶
type ChallengeTypeGRPCPlugin struct {
goplugin.NetRPCUnsupportedPlugin
Impl pluginpb.ChallengeTypeServer
}
ChallengeTypeGRPCPlugin bridges the ChallengeType service.
func (*ChallengeTypeGRPCPlugin) GRPCClient ¶
func (p *ChallengeTypeGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)
func (*ChallengeTypeGRPCPlugin) GRPCServer ¶
func (p *ChallengeTypeGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error
type NotificationGRPCPlugin ¶
type NotificationGRPCPlugin struct {
goplugin.NetRPCUnsupportedPlugin
Impl pluginpb.NotificationServer
}
NotificationGRPCPlugin bridges the Notification service.
func (*NotificationGRPCPlugin) GRPCClient ¶
func (p *NotificationGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)
func (*NotificationGRPCPlugin) GRPCServer ¶
func (p *NotificationGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error
type ScoringGRPCPlugin ¶
type ScoringGRPCPlugin struct {
goplugin.NetRPCUnsupportedPlugin
Impl pluginpb.ScoringServer
}
ScoringGRPCPlugin bridges the Scoring service.
func (*ScoringGRPCPlugin) GRPCClient ¶
func (p *ScoringGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)
func (*ScoringGRPCPlugin) GRPCServer ¶
func (p *ScoringGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error