Documentation
¶
Overview ¶
Package runtime provides bootstrap infrastructure for the sentinel-gate run command. It handles runtime API key generation, bootstrap directory creation, environment variable preparation, and registration of runtime keys with the SentinelGate server.
Index ¶
- Constants
- func BuildEnvVars(env *BootstrapEnv, cfg BootstrapConfig) []string
- func Cleanup(env *BootstrapEnv) error
- func CleanupClaudeHooks(setup *ClaudeHookSetup) error
- func CleanupGeminiHooks(setup *GeminiHookSetup) error
- func DetectFramework(command string, args []string) string
- func DetectPythonSitePackages(pythonCmd string) []string
- func GenerateRuntimeAPIKey() (plaintext string, sha256Hash string, err error)
- func IsBunBinary(command string) bool
- func IsGeminiCLI(command string) bool
- func IsPythonCommand(command string) bool
- func MergeEnv(parentEnv, bootstrapVars []string) []string
- func RegisterAgent(serverAddr string, reg AgentRegistration) error
- func RegisterRuntimeKey(serverAddr, agentID string) (cleartextKey string, result *registrationResult, err error)
- func RevokeRuntimeKey(serverAddr string, identityID string) error
- func UnregisterAgent(serverAddr, agentID string) error
- func WriteNodeBootstrap(dir string) error
- func WritePythonBootstrap(dir string) error
- type AgentRegistration
- type BootstrapConfig
- type BootstrapEnv
- type ClaudeHookConfig
- type ClaudeHookSetup
- type FailMode
- type GeminiHookConfig
- type GeminiHookSetup
Constants ¶
const DefaultFailMode = FailModeOpen
DefaultFailMode is the default fail mode when none is specified.
Variables ¶
This section is empty.
Functions ¶
func BuildEnvVars ¶
func BuildEnvVars(env *BootstrapEnv, cfg BootstrapConfig) []string
BuildEnvVars returns the environment variables that should be set on the child process for SentinelGate runtime protection. The returned slice contains KEY=VALUE strings suitable for exec.Cmd.Env.
Variables set:
- SENTINELGATE_SERVER_ADDR: SentinelGate server address
- SENTINELGATE_API_KEY: Runtime API key (plaintext)
- SENTINELGATE_AGENT_ID: Unique agent process ID
- SENTINELGATE_CACHE_TTL: LRU cache TTL in seconds
- SENTINELGATE_FAIL_MODE: Fail mode ("open" or "closed")
- SENTINELGATE_FRAMEWORK: Detected AI framework name (may be empty)
- PYTHONPATH: Prepended with Python bootstrap dir
- NODE_OPTIONS: Appended with --require for Node.js hook
Always set (Layer 2 outbound control):
- HTTP_PROXY: Routes HTTP traffic through SentinelGate
- HTTPS_PROXY: Routes HTTPS traffic through SentinelGate (CONNECT tunnel)
- NO_PROXY: Excludes localhost from proxying (prevents loops)
When CACertPath is set (TLS inspection CA available):
- REQUESTS_CA_BUNDLE: Python requests library CA trust
- SSL_CERT_FILE: Python httpx / general SSL CA trust
- NODE_EXTRA_CA_CERTS: Node.js CA trust
func Cleanup ¶
func Cleanup(env *BootstrapEnv) error
Cleanup removes the bootstrap temporary directory and all its contents.
func CleanupClaudeHooks ¶
func CleanupClaudeHooks(setup *ClaudeHookSetup) error
CleanupClaudeHooks decrements the reference count and restores the original settings.json only when the last instance exits.
func CleanupGeminiHooks ¶
func CleanupGeminiHooks(setup *GeminiHookSetup) error
CleanupGeminiHooks decrements the reference count and restores the original settings.json only when the last instance exits.
func DetectFramework ¶
DetectFramework attempts to identify the AI framework being used by examining the command and its arguments. This is a best-effort detection that runs on the Go side before the child process starts. The in-process bootstraps (Python/Node.js) perform more accurate detection via package imports.
Supported frameworks:
- "langchain" — LangChain / LangServe
- "crewai" — CrewAI
- "autogen" — AutoGen
- "openai-agents-sdk" — OpenAI Agents SDK / Swarm
Returns an empty string if no framework is detected.
func DetectPythonSitePackages ¶
DetectPythonSitePackages runs the given Python interpreter to discover its site-packages directories. This ensures that pip-installed packages remain importable when sentinel-gate injects PYTHONPATH for the bootstrap hooks.
Returns an empty slice (no error) if detection fails — the child process will still work if site-packages happens to be on sys.path already.
func GenerateRuntimeAPIKey ¶
GenerateRuntimeAPIKey generates a per-process API key for runtime bootstrap. It returns the plaintext key (for setting as env var) and its SHA-256 hash (for registering with the auth store).
Key format: sg_runtime_ + 32 random hex characters (e.g., sg_runtime_a1b2c3d4...).
func IsBunBinary ¶
IsBunBinary checks if the given command resolves to a Bun-compiled binary by searching for the "Bun.env" signature in the executable file. Returns false if the command cannot be resolved or read.
func IsGeminiCLI ¶
IsGeminiCLI checks if the given command is the Gemini CLI binary. It checks the command name (with or without path) for "gemini".
func IsPythonCommand ¶
IsPythonCommand returns true if the given command looks like a Python interpreter.
func MergeEnv ¶
MergeEnv merges bootstrap env vars into the parent environment. Bootstrap vars override any existing vars with the same name.
func RegisterAgent ¶
func RegisterAgent(serverAddr string, reg AgentRegistration) error
RegisterAgent registers a running agent process with the SentinelGate server via POST /admin/api/agents/register. This makes the agent visible in the admin UI.
func RegisterRuntimeKey ¶
func RegisterRuntimeKey(serverAddr, agentID string) (cleartextKey string, result *registrationResult, err error)
RegisterRuntimeKey registers a runtime identity and API key with the SentinelGate server via its admin API. It creates a runtime identity and generates a server-side API key.
Returns the server-generated cleartext key (to use as SENTINELGATE_API_KEY) and the identity ID (for cleanup on exit). If registration fails, returns an error and the caller should fall back to the locally-generated key.
func RevokeRuntimeKey ¶
RevokeRuntimeKey revokes the runtime identity and its keys by deleting the identity via the admin API. This is called on cleanup when the child process exits.
func UnregisterAgent ¶
UnregisterAgent removes a running agent from the SentinelGate server registry via DELETE /admin/api/agents/{id}. Called on cleanup when the child process exits.
func WriteNodeBootstrap ¶
WriteNodeBootstrap writes the embedded sentinelgate-hook.js to the given directory. The directory must already exist.
func WritePythonBootstrap ¶
WritePythonBootstrap writes the embedded sitecustomize.py to the given directory. The directory must already exist.
Types ¶
type AgentRegistration ¶
type AgentRegistration struct {
ID string `json:"id"`
Command string `json:"command"`
Args []string `json:"args"`
Framework string `json:"framework,omitempty"`
FailMode string `json:"fail_mode"`
PID int `json:"pid,omitempty"`
}
AgentRegistration holds the data needed to register an agent with the server.
type BootstrapConfig ¶
type BootstrapConfig struct {
// ServerAddr is the SentinelGate server address (e.g., "http://localhost:8080").
ServerAddr string
// APIKey is the plaintext runtime API key for the child process.
APIKey string
// AgentID is the unique identifier for this agent process (UUID).
AgentID string
// CacheTTL is the LRU cache TTL for recently-allowed patterns.
CacheTTL time.Duration
// FailMode controls behavior when the SentinelGate server is unreachable.
// Valid values: "open" (allow, default) or "closed" (deny).
FailMode string
// Framework is the detected AI framework name (e.g., "langchain", "crewai").
// May be empty if no framework was detected.
Framework string
// CACertPath is the path to the SentinelGate TLS inspection CA certificate.
// When non-empty, BuildEnvVars injects CA cert trust environment variables
// so child processes accept the MITM certificate for HTTPS content inspection.
// HTTP_PROXY/HTTPS_PROXY are always set regardless of CACertPath.
CACertPath string
// SkipNodeOptions skips setting NODE_OPTIONS when true. Used for:
// - Bun binaries (e.g. Claude Code) that use PreToolUse hooks instead
// - Gemini CLI which uses MCP-level protection (tools.exclude + MCP proxy)
SkipNodeOptions bool
// PythonSitePackages contains site-packages directories detected from
// the target Python interpreter. These are appended to PYTHONPATH so
// that pip-installed packages remain importable after bootstrap injection.
PythonSitePackages []string
// BootstrapDir overrides the temp directory (for testing). If empty,
// a temp directory is created automatically.
BootstrapDir string
}
BootstrapConfig holds the configuration needed to prepare the bootstrap environment.
type BootstrapEnv ¶
type BootstrapEnv struct {
// Dir is the root bootstrap temp directory.
Dir string
// PythonDir is the directory containing sitecustomize.py.
PythonDir string
// NodeDir is the directory containing the Node.js require hook.
NodeDir string
}
BootstrapEnv holds the paths created by PrepareBootstrap.
func PrepareBootstrap ¶
func PrepareBootstrap(cfg BootstrapConfig) (*BootstrapEnv, error)
PrepareBootstrap creates a temporary bootstrap directory with subdirectories for Python and Node.js instrumentation hooks. It writes the embedded Python sitecustomize.py and Node.js sentinelgate-hook.js to their respective subdirectories.
type ClaudeHookConfig ¶
type ClaudeHookConfig struct {
// SentinelGateExe is the absolute path to the sentinel-gate binary.
SentinelGateExe string
}
ClaudeHookConfig holds the configuration for setting up Claude Code hooks.
type ClaudeHookSetup ¶
type ClaudeHookSetup struct {
// SettingsPath is the absolute path to ~/.claude/settings.json.
SettingsPath string
// RefcountPath is the path to the refcount file (.sentinelgate-hook-refcount).
RefcountPath string
// BackupPath is the path to the backup file (.sentinelgate-settings-backup).
BackupPath string
}
ClaudeHookSetup holds the state needed to clean up Claude Code hooks on exit.
func SetupClaudeHooks ¶
func SetupClaudeHooks(cfg ClaudeHookConfig) (*ClaudeHookSetup, error)
SetupClaudeHooks configures Claude Code PreToolUse hooks by writing to ~/.claude/settings.json (user-level settings). Uses reference counting to safely support multiple concurrent sentinel-gate run instances.
First instance: saves original settings as backup, writes hook. Subsequent instances: increments refcount only (hook already in place).
type FailMode ¶
type FailMode string
FailMode represents the behavior when the SentinelGate server is unreachable.
type GeminiHookConfig ¶
type GeminiHookConfig struct {
// ServerAddr is the SentinelGate server address (e.g., "http://localhost:8080").
ServerAddr string
// APIKey is the runtime API key for authenticating MCP requests.
APIKey string
}
GeminiHookConfig holds the configuration for setting up Gemini CLI hooks.
type GeminiHookSetup ¶
type GeminiHookSetup struct {
// SettingsPath is the absolute path to ~/.gemini/settings.json.
SettingsPath string
// RefcountPath is the path to the refcount file (.sentinelgate-hook-refcount).
RefcountPath string
// BackupPath is the path to the backup file (.sentinelgate-settings-backup).
BackupPath string
}
GeminiHookSetup holds the state needed to clean up Gemini CLI hooks on exit.
func SetupGeminiHooks ¶
func SetupGeminiHooks(cfg GeminiHookConfig) (*GeminiHookSetup, error)
SetupGeminiHooks configures Gemini CLI to route file operations through SentinelGate by modifying ~/.gemini/settings.json. Uses reference counting to safely support multiple concurrent sentinel-gate run instances.
First instance: saves original settings as backup, writes MCP config + tool exclusions. Subsequent instances: increments refcount only (config already in place).
Source Files