Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-18865-sandbox-github-read-relay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Sandbox Jobs can now make authenticated GitHub reads through a hive-hosted read relay instead of hitting GitHub's 60-requests-per-hour anonymous cap (so `uv lock --upgrade` resolves git dependencies without falling back to full clones). Opt in with `agent_sandbox.job.github_read_proxy` (`enabled`, `listen_addr` and `endpoint`, optional `no_proxy`); default off, with no default bind: `listen_addr` is required when enabled, and `endpoint` must be `https://` because the listener serves TLS only, with a certificate from hive's proxy CA for the endpoint host. Pair it with a NetworkPolicy (example in the docs). The relay attaches a read-only, repo-scoped App token (the existing `shared-uid-read` tier) to `GET`/`HEAD` for `api.github.com`, `codeload.github.com` and `raw.githubusercontent.com` and to git fetch on `github.com`, refuses every write, GraphQL and push discovery with a 403, tunnels every other host untouched, and never puts a GitHub credential in the Job: the Job holds only a per-kick relay key that is revoked when the kick ends. See [Sandbox isolation](src/docs/sandbox-isolation.md) ([#18865](https://github.com/hivecommons/hive/issues/18865)).
8 changes: 8 additions & 0 deletions src/cmd/hive/agent_runtime_sidecar.go
Original file line number Diff line number Diff line change
Expand Up @@ -339,6 +339,14 @@ func (h *sidecarHost) SetKnowledgeAdviser(crux.KnowledgeAdviser) {
h.inProcessOnly("SetKnowledgeAdviser")
}

// SetSandboxGitHubReadRelay is in-process-only (#18865): the relay holds the
// read credential and Enroll is a Go call into hive's proxy, so neither
// crosses into a sidecar runtime. A sidecar runtime's Job kicks run without
// the relay and read GitHub as they did before.
func (h *sidecarHost) SetSandboxGitHubReadRelay(crux.SandboxGitHubReadRelay, []string) {
h.inProcessOnly("SetSandboxGitHubReadRelay")
}

// SetInferenceRoute and ClearInferenceRoute are cruxhost.InferenceRouter:
// the callback's end of SetInferenceCallbacks. A route that arrives before
// boot has installed the closures is dropped and logged; the runtime's
Expand Down
1 change: 1 addition & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -4518,6 +4518,7 @@ func (b *boot) bootProxyWith(deps bootProxyDeps) {
)

deps.startProxy(b.githubProxy, b.logger)
b.wireSandboxGitHubReadRelay()
// Jev decision endpoint (hivecommons/hive#8939). Always bound so a
// jev_mode toggle in the dashboard takes effect on the agent's next
// call; every predicate reads the LIVE config, and an agent whose
Expand Down
93 changes: 93 additions & 0 deletions src/cmd/hive/sandbox_read_relay_boot.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
package main

import (
"context"
"crypto/tls"
"errors"
"net"
"os"
"time"

"github.com/hivecommons/hive/crux"
"github.com/hivecommons/hive/crux/proxy"
)

// sandboxReadTokenTimeout bounds one read-token mint for the sandbox read
// relay.
const sandboxReadTokenTimeout = 20 * time.Second

// systemRootBundles are the PEM trust bundles hive looks for, first match
// wins. The relay hands one to each Job with the hive CA appended, so a Job
// that sets SSL_CERT_FILE still trusts the real internet.
var systemRootBundles = []string{
"/etc/ssl/certs/ca-certificates.crt",
"/etc/pki/tls/certs/ca-bundle.crt",
"/etc/ssl/cert.pem",
}

func readSystemRootsPEM() []byte {
for _, p := range systemRootBundles {
if data, err := os.ReadFile(p); err == nil && len(data) > 0 {
return data
}
}
return nil
}

// wireSandboxGitHubReadRelay starts the sandbox GitHub read relay when
// agent_sandbox.job.github_read_proxy.enabled is true (#18865). Default off.
// Any failure here is logged and leaves Jobs on their existing network path;
// it never stops boot.
func (b *boot) wireSandboxGitHubReadRelay() {
cfg := b.cfg.AgentSandbox.Job
if b.githubProxy == nil || cfg == nil || cfg.GitHubReadProxy == nil || !cfg.GitHubReadProxy.Enabled {
return
}
rp := cfg.GitHubReadProxy
if err := rp.Validate(); err != nil {
b.logger.Error("sandbox GitHub read relay not started", "error", err.Error())
return
}
if b.agentMgr == nil {
b.logger.Error("sandbox GitHub read relay not started: no agent manager")
return
}
relay, err := proxy.NewSandboxReadRelay(b.githubProxy, proxy.SandboxReadRelayOptions{
Endpoint: rp.Endpoint,
Token: b.sandboxReadToken,
RootsPEM: readSystemRootsPEM(),
})
if err != nil {
b.logger.Error("sandbox GitHub read relay not started", "error", err.Error())
return
}
ln, err := net.Listen("tcp", rp.Listen())
if err != nil {
b.logger.Error("sandbox GitHub read relay not started: cannot listen", "addr", rp.Listen(), "error", err.Error())
return
}
// TLS only: the per-kick key is carried in Proxy-Authorization, so a
// plain-HTTP connection is never served. The certificate comes from the
// hive proxy CA for the endpoint's host.
tlsLn := tls.NewListener(ln, relay.TLSConfig())
go func() {
// Serve only returns when the listener fails, always with an error.
b.logger.Error("sandbox GitHub read relay stopped", "error", relay.Serve(tlsLn).Error())
}()
b.agentMgr.SetSandboxGitHubReadRelay(relay, rp.NoProxy)
b.logger.Info("sandbox GitHub read relay enabled (TLS): Job GitHub reads use a read-only, repo-scoped token held by hive; writes are refused", "listen", rp.Listen(), "endpoint", rp.Endpoint)
}

// sandboxReadToken mints the READ identity the relay attaches: the
// shared-uid-read tier (metadata, contents, actions, checks, pull requests and
// issues, all read), narrowed to the project's repositories. It is never the
// write-capable credential.
func (b *boot) sandboxReadToken() (string, error) {
auth := b.appAuth

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Build break. b.agentMgr is hostedRuntime (crux.Runtime + crux.Host). SetSandboxGitHubReadRelay exists only on *agent.Manager; it is not in crux.Host (src/crux/host_wiring.go) and the PR doesn't touch that file, sidecarHost, or the cruxtest fakes. CI build-go/build-and-test/golangci-lint are red. Add the method to crux.Host and implement it on every Host (sidecarHost: forward or no-op with a warning, since sidecar-mode Job kicks run out of process).

if auth == nil {
return "", errors.New("no GitHub App auth to mint a read token")
}
ctx, cancel := context.WithTimeout(context.Background(), sandboxReadTokenTimeout)
defer cancel()
return auth.ScopedTokenForRepos(ctx, crux.SharedUIDReadTokenTier, b.cfg.Project.Repos)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This token is scoped to all b.cfg.Project.Repos and cached for 45 minutes, then attached to every Job's reads. A Job working on one repo can read every other project repo, private ones included. If that is intended, say so in sandbox-isolation.md. If not, mint per-kick tokens for the repos the kick needs.

}
36 changes: 36 additions & 0 deletions src/cmd/hive/sandbox_read_relay_boot_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
package main

import (
"testing"

"github.com/hivecommons/hive/pkg/config"
)

// The sandbox GitHub read relay is default off (#18865): with no block, or a
// disabled one, boot wires nothing and binds nothing.
func TestWireSandboxGitHubReadRelayDefaultOff(t *testing.T) {
withJob := func(job *config.SandboxJobConfig) *config.Config {
c := &config.Config{}
c.AgentSandbox = config.AgentSandboxConfig{Job: job}
return c
}
cfgs := []*config.Config{
{},
withJob(&config.SandboxJobConfig{}),
withJob(&config.SandboxJobConfig{GitHubReadProxy: &config.SandboxGitHubReadProxy{Enabled: false, Endpoint: "http://h:1"}}),
}
for i, cfg := range cfgs {
b := &boot{cfg: cfg, logger: quietLogger()}
b.wireSandboxGitHubReadRelay() // nil proxy and nil manager: must be a silent no-op
if b.agentMgr != nil {
t.Fatalf("case %d wired a manager", i)
}
}
}

func TestSandboxReadTokenNeedsAppAuth(t *testing.T) {
b := &boot{cfg: &config.Config{}, logger: quietLogger()}
if tok, err := b.sandboxReadToken(); err == nil || tok != "" {
t.Fatalf("token = %q, err = %v; want an error and no token", tok, err)
}
}
16 changes: 1 addition & 15 deletions src/crux/agent/manager.go
Original file line number Diff line number Diff line change
Expand Up @@ -812,6 +812,7 @@ type Manager struct {
sandboxPRClient PRCreator
sandboxMutation effects.Boundary
sandboxAuditCallback atomic.Pointer[func(agent, action, detail string)]
sandboxReadRelay sandboxReadRelayState

// terminal is the nil-safe pane/tmux boundary. Nil means use the real tmux
// implementation, preserving zero-value Manager behavior in tests.
Expand All @@ -836,21 +837,6 @@ type Manager struct {
buildInfo func() (version, commit string)
}

// SetACMMLevel updates the cached ACMM level used by agentMode() when
// launching agents. Call this whenever the ACMM level changes.
func (m *Manager) SetACMMLevel(level int) {
m.mu.Lock()
defer m.mu.Unlock()
m.project.ACMMLevel = level
m.removeAgentsBelowACMMGateLocked(level)
}

func (m *Manager) GetACMMLevel() int {
m.mu.RLock()
defer m.mu.RUnlock()
return m.project.ACMMLevel
}

func NewManager(agents map[string]config.AgentConfig, logger *slog.Logger, project ProjectContext) *Manager {
return NewManagerWithOptions(agents, logger, project)
}
Expand Down
16 changes: 16 additions & 0 deletions src/crux/agent/manager_acmm_level.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
package agent

// SetACMMLevel updates the cached ACMM level used by agentMode() when
// launching agents. Call this whenever the ACMM level changes.
func (m *Manager) SetACMMLevel(level int) {
m.mu.Lock()
defer m.mu.Unlock()
m.project.ACMMLevel = level
m.removeAgentsBelowACMMGateLocked(level)
}

func (m *Manager) GetACMMLevel() int {
m.mu.RLock()
defer m.mu.RUnlock()
return m.project.ACMMLevel
}
4 changes: 4 additions & 0 deletions src/crux/agent/manager_sandbox.go
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,10 @@ func (m *Manager) runSandboxKick(ctx context.Context, name, runtime string, spec
Mutation: mutationBoundary,
Logger: m.logger,
}
if in := m.sandboxReadRelay.cur.Load(); in != nil {
exec.GitHubReadRelay = in.relay
exec.GitHubReadRelayNoProxy = in.noProxy
}
res, err := exec.Run(ctx, spec)
ended := time.Now()
// The run record is written to disk after m.mu is released (defers run
Expand Down
10 changes: 9 additions & 1 deletion src/crux/agent/sandbox_executor.go
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,12 @@ type SandboxExecutor struct {
Logger *slog.Logger
Now func() time.Time
Mutation effects.Boundary
// GitHubReadRelay, when set, routes a Job-runtime kick's GitHub reads
// through hive's read relay (#18865). Nil leaves the Job on its own
// network path, exactly as before.
GitHubReadRelay SandboxGitHubReadRelay
// GitHubReadRelayNoProxy is extra NO_PROXY entries for relayed Jobs.
GitHubReadRelayNoProxy []string
}

func (e *SandboxExecutor) Run(ctx context.Context, spec SandboxKickSpec) (SandboxKickResult, error) {
Expand Down Expand Up @@ -252,6 +258,8 @@ func (e *SandboxExecutor) Run(ctx context.Context, spec SandboxKickSpec) (Sandbo
e.Logger.Warn("sandbox review spool: could not mark the kick ended", "agent", spec.Agent, "error", err)
}
}()
relayEnv, releaseRelay := e.enrollGitHubReadRelay(spec, workspace)
defer releaseRelay()
runCtx, cancel := context.WithTimeout(ctx, spec.Timeout)
defer cancel()
sres, runErr := e.launcher().Run(runCtx, sandbox.LaunchSpec{
Expand All @@ -261,7 +269,7 @@ func (e *SandboxExecutor) Run(ctx context.Context, spec SandboxKickSpec) (Sandbo
WorkspaceMount: sandbox.DefaultWorkspaceMount,
WorkDir: sandbox.DefaultWorkspaceMount,
Command: command,
Env: spool.sandboxEnv(),
Env: mergeSandboxEnv(spool.sandboxEnv(), relayEnv),
EnvAllowlist: spec.EnvAllowlist,
NetworkMode: spec.NetworkMode,
ClineProvider: provider,
Expand Down
136 changes: 136 additions & 0 deletions src/crux/agent/sandbox_github_read_relay.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
package agent

import (
"log/slog"
"os"
"path"
"path/filepath"
"strings"
"sync/atomic"

"github.com/hivecommons/hive/crux"
"github.com/hivecommons/hive/crux/config"
"github.com/hivecommons/hive/crux/sandbox"
)

// SandboxGitHubReadRelay is the relay a sandbox Job sends its GitHub reads
// through (#18865); see crux.SandboxGitHubReadRelay.
type SandboxGitHubReadRelay = crux.SandboxGitHubReadRelay

// sandboxReadRelayState is the Manager's relay wiring; the zero value is off.
// The relay and its extra NO_PROXY hosts are stored as one value so a reader
// never sees one from a previous install paired with the other.
type sandboxReadRelayState struct {
cur atomic.Pointer[sandboxReadRelayInstall]
}

type sandboxReadRelayInstall struct {
relay SandboxGitHubReadRelay
noProxy []string
}

// SetSandboxGitHubReadRelay installs (or, with nil, removes) the relay that
// carries sandbox Job GitHub reads (#18865). noProxy adds hosts Jobs reach
// directly.
func (m *Manager) SetSandboxGitHubReadRelay(relay SandboxGitHubReadRelay, noProxy []string) {
if relay == nil {
m.sandboxReadRelay.cur.Store(nil)
return
}
m.sandboxReadRelay.cur.Store(&sandboxReadRelayInstall{relay: relay, noProxy: append([]string(nil), noProxy...)})
}

const (
// sandboxReadCARelPath is where the trust bundle is written in the kick's
// workspace; the Job sees it under sandbox.DefaultWorkspaceMount.
sandboxReadCARelPath = ".hive/github-read-ca.pem"
sandboxReadCAFileMode = 0o644
sandboxReadCADirMode = 0o755
// sandboxReadBaseNoProxy keeps cluster-local traffic off the relay.
sandboxReadBaseNoProxy = "localhost,127.0.0.1,::1,.svc,.cluster.local"
)

// sandboxReadEnv is the environment that points a Job's HTTPS clients at the
// relay and at the CA bundle. It carries only the proxy URL (relay key) and a
// file path: no GitHub credential exists on this path, and
// TestSandboxReadEnvCarriesNoGitHubToken pins that.
func sandboxReadEnv(proxyURL, caPath string, extraNoProxy []string) map[string]string {
noProxy := sandboxReadBaseNoProxy
for _, h := range extraNoProxy {
if h = strings.TrimSpace(h); h != "" {
noProxy += "," + h
}
}
return map[string]string{
"HTTPS_PROXY": proxyURL,
"https_proxy": proxyURL,
"NO_PROXY": noProxy,
"no_proxy": noProxy,
"SSL_CERT_FILE": caPath,
"GIT_SSL_CAINFO": caPath,
"REQUESTS_CA_BUNDLE": caPath,
"CURL_CA_BUNDLE": caPath,
"NODE_EXTRA_CA_CERTS": caPath,
// libcurl (so git) verifies an https PROXY against its own CA setting,
// separate from the one for the origin server: GIT_SSL_CAINFO alone
// does not cover it. Git reads this entry from the environment.
"GIT_CONFIG_COUNT": "1",
"GIT_CONFIG_KEY_0": "http.proxySSLCAInfo",
"GIT_CONFIG_VALUE_0": caPath,
}
}

// mergeSandboxEnv returns base overlaid with extra; neither input is mutated.
// GIT_CONFIG_* entries in extra are dropped when base already defines
// GIT_CONFIG_COUNT, so the relay never rewrites a git config the Job has set.
func mergeSandboxEnv(base, extra map[string]string) map[string]string {
if len(extra) == 0 {
return base
}
out := make(map[string]string, len(base)+len(extra))
for k, v := range base {
out[k] = v
}
_, baseGitConfig := base["GIT_CONFIG_COUNT"]
for k, v := range extra {
if baseGitConfig && strings.HasPrefix(k, "GIT_CONFIG_") {
continue
}
out[k] = v
}
return out
}

// enrollGitHubReadRelay routes this kick's Job through the read relay. It is
// best effort by design: the relay only improves rate limits, so any failure
// is logged and the kick runs as it did before, never failing the work. The
// returned release must be called when the kick ends; it is never nil.
func (e *SandboxExecutor) enrollGitHubReadRelay(spec SandboxKickSpec, workspace string) (map[string]string, func()) {
noop := func() {}
if e.GitHubReadRelay == nil || spec.Runtime != config.SandboxRuntimeJob {
return nil, noop
}
proxyURL, bundle, release, err := e.GitHubReadRelay.Enroll(spec.Agent)
if err != nil {
e.warnReadRelay(spec.Agent, "enroll", err)
return nil, noop
}
caHost := filepath.Join(workspace, filepath.FromSlash(sandboxReadCARelPath))
writeErr := os.MkdirAll(filepath.Dir(caHost), sandboxReadCADirMode)
if writeErr == nil {
writeErr = os.WriteFile(caHost, bundle, sandboxReadCAFileMode)
}
if err = writeErr; err != nil {
release()
e.warnReadRelay(spec.Agent, "write CA bundle", err)
return nil, noop
}
caJob := path.Join(sandbox.DefaultWorkspaceMount, sandboxReadCARelPath)
return sandboxReadEnv(proxyURL, caJob, e.GitHubReadRelayNoProxy), release
}

func (e *SandboxExecutor) warnReadRelay(agentName, step string, err error) {
if e.Logger != nil {
e.Logger.Warn("sandbox GitHub read relay unavailable; this kick's Job reads GitHub anonymously", slog.String("agent", agentName), slog.String("step", step), slog.String("error", err.Error()))
}
}
Loading
Loading