harness

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BoolDefault added in v0.0.3 

func BoolDefault(b *bool, def bool) bool

BoolDefault returns the value of a *bool, or the default if nil.

Types

type APIServer 

type APIServer struct {
	Name   string            `yaml:"name"`
	Script string            `yaml:"script"`
	Port   int               `yaml:"port"`
	Env    map[string]string `yaml:"env,omitempty"`
}

APIServer describes a host-side REST proxy server.

type EscalationConfig added in v0.0.3 

type EscalationConfig struct {
	OnCritical  string `yaml:"on_critical,omitempty"`  // "halt" or "review". Default: "halt"
	ReviewLabel string `yaml:"review_label,omitempty"` // Default: "requires-manual-review"
}

EscalationConfig controls what happens when critical findings are detected.

type Harness 

type Harness struct {
	Agent          string            `yaml:"agent"`
	Description    string            `yaml:"description,omitempty"`
	Image          string            `yaml:"image,omitempty"`
	Policy         string            `yaml:"policy,omitempty"`
	Skills         []string          `yaml:"skills,omitempty"`
	Providers      []string          `yaml:"providers,omitempty"`
	HostFiles      []HostFile        `yaml:"host_files,omitempty"`
	APIServers     []APIServer       `yaml:"api_servers,omitempty"`
	Model          string            `yaml:"model,omitempty"`
	PreScript      string            `yaml:"pre_script,omitempty"`
	PostScript     string            `yaml:"post_script,omitempty"`
	AgentInput     string            `yaml:"agent_input,omitempty"`
	ValidationLoop *ValidationLoop   `yaml:"validation_loop,omitempty"`
	RunnerEnv      map[string]string `yaml:"runner_env,omitempty"`
	TimeoutMinutes int               `yaml:"timeout_minutes,omitempty"`
	Security       *SecurityConfig   `yaml:"security,omitempty"`
}

Harness is the per-agent configuration that the runner reads to provision a sandbox and launch one agent. It follows the ADR-0017 schema.

func Load 

func Load(path string) (*Harness, error)

Load reads a harness YAML file from path, unmarshals it, and validates it.

func (*Harness) FailModeClosed added in v0.0.3 

func (h *Harness) FailModeClosed() bool

FailModeClosed returns true if the security fail mode is "closed" (default).

func (*Harness) ResolveRelativeTo 

func (h *Harness) ResolveRelativeTo(baseDir string) error

ResolveRelativeTo resolves all relative paths in the harness against baseDir. Relative paths that resolve outside baseDir are rejected to prevent directory traversal (e.g. ../../etc/shadow). Absolute paths and ${VAR} paths are allowed.

func (*Harness) Scripts added in v0.0.4 

func (h *Harness) Scripts() []string

Scripts returns all script paths configured in the harness.

func (*Harness) SecurityEnabled added in v0.0.3 

func (h *Harness) SecurityEnabled() bool

SecurityEnabled returns true if security scanning is enabled (default: true).

func (*Harness) Validate 

func (h *Harness) Validate() error

Validate checks that required fields are present.

func (*Harness) ValidateFilesExist 

func (h *Harness) ValidateFilesExist() error

ValidateFilesExist checks that all file paths referenced by the harness exist on disk. Call after ResolveRelativeTo so paths are absolute. Pre/post scripts run on the host and must be file paths (no inline args).

func (*Harness) ValidateRunnerEnv 

func (h *Harness) ValidateRunnerEnv() error

ValidateRunnerEnv checks that all ${VAR} references in RunnerEnv and HostFiles.Src expand to non-empty values in the host environment.

func (*Harness) ValidateRunnerEnvWith added in v0.0.4 

func (h *Harness) ValidateRunnerEnvWith(expander func(string) string) error

ValidateRunnerEnvWith checks that all ${VAR} references in RunnerEnv and HostFiles.Src expand to non-empty values using the provided expander function.

type HostFile 

type HostFile struct {
	Src      string `yaml:"src"`                // host path (may use ${VAR} expansion)
	Dest     string `yaml:"dest"`               // destination path inside the sandbox
	Expand   bool   `yaml:"expand,omitempty"`   // expand ${VAR} in file content before copying
	Optional bool   `yaml:"optional,omitempty"` // skip if src path is missing or expands to empty
}

HostFile describes a file on the host that must be copied into the sandbox during bootstrap. Src may contain ${VAR} references that are expanded from the host environment at bootstrap time. Use this for any file that must exist inside the sandbox (e.g. GCP service account JSON, CA certificates).

When Expand is true, the file content is read and ${VAR} references in the content are expanded from the host environment before copying to the sandbox. Use this for env files that contain variable references which must be resolved on the host (because the sandbox does not have those variables set).

type HostScanners added in v0.0.3 

type HostScanners struct {
	UnicodeNormalizer *bool           `yaml:"unicode_normalizer,omitempty"` // default: true
	ContextInjection  *bool           `yaml:"context_injection,omitempty"`  // default: true
	SSRFValidator     *bool           `yaml:"ssrf_validator,omitempty"`     // default: true
	SecretRedactor    *bool           `yaml:"secret_redactor,omitempty"`    // default: true
	LLMGuard          *LLMGuardConfig `yaml:"llm_guard,omitempty"`
}

HostScanners configures which scanners run on the host before sandbox creation (Path A: GHA workflow pre-step) or inside the sandbox before the agent starts (Path B: fullsend scan context).

type LLMGuardConfig added in v0.0.3 

type LLMGuardConfig struct {
	Enabled   *bool   `yaml:"enabled,omitempty"`    // default: true
	Threshold float64 `yaml:"threshold,omitempty"`  // default: 0.92
	MatchType string  `yaml:"match_type,omitempty"` // "sentence" or "full". Default: "sentence"
}

LLMGuardConfig configures the LLM Guard ML-based prompt injection scanner. Runs in Path A (GHA workflow pre-step) and Path B (sandbox) when the base sandbox image includes the pre-installed LLM Guard and DeBERTa-v3 model.

type ProviderDef 

type ProviderDef struct {
	Name        string            `yaml:"name"`
	Type        string            `yaml:"type"`
	Credentials map[string]string `yaml:"credentials"`      // KEY: VALUE or KEY: ${HOST_VAR}
	Config      map[string]string `yaml:"config,omitempty"` // e.g. OPENAI_BASE_URL
}

ProviderDef is a declarative definition of an OpenShell provider. Files in the experiment's providers/ directory are loaded as ProviderDefs and reconciled against the gateway before sandbox creation.

func LoadProviderDefs 

func LoadProviderDefs(dir string) ([]ProviderDef, error)

LoadProviderDefs reads all YAML files from a providers/ directory and returns the parsed definitions. Returns nil (no error) if the directory does not exist.

type SandboxHooks added in v0.0.3 

type SandboxHooks struct {
	Tirith                  *TirithConfig        `yaml:"tirith,omitempty"`
	SSRFPreTool             *bool                `yaml:"ssrf_pretool,omitempty"`              // default: true
	SecretRedactPostTool    *bool                `yaml:"secret_redact_posttool,omitempty"`    // default: true
	UnicodePostTool         *bool                `yaml:"unicode_posttool,omitempty"`          // default: true
	ContextSuppressPostTool *bool                `yaml:"context_suppress_posttool,omitempty"` // default: true
	CanaryPreTool           *bool                `yaml:"canary_pretool,omitempty"`            // default: true
	CanaryPostTool          *bool                `yaml:"canary_posttool,omitempty"`           // default: true
	ToolAllowlistPreTool    *ToolAllowlistConfig `yaml:"tool_allowlist_pretool,omitempty"`
}

SandboxHooks configures Claude Code PreToolUse/PostToolUse hooks that run inside the sandbox during agent execution.

type SecurityConfig added in v0.0.3 

type SecurityConfig struct {
	Enabled      *bool             `yaml:"enabled,omitempty"`   // nil = true (secure by default)
	FailMode     string            `yaml:"fail_mode,omitempty"` // "closed" or "open". Default: "closed"
	HostScanners *HostScanners     `yaml:"host_scanners,omitempty"`
	SandboxHooks *SandboxHooks     `yaml:"sandbox_hooks,omitempty"`
	Escalation   *EscalationConfig `yaml:"escalation,omitempty"`
	Trace        *TraceConfig      `yaml:"trace,omitempty"`
}

SecurityConfig configures security scanning for the agent run. Secure by default: omitting this block enables all scanners with fail_mode: closed.

type TirithConfig added in v0.0.3 

type TirithConfig struct {
	Enabled *bool  `yaml:"enabled,omitempty"` // default: true
	FailOn  string `yaml:"fail_on,omitempty"` // "critical", "high", "medium". Default: "high"
}

TirithConfig configures the Tirith Rust CLI scanner for terminal security.

type ToolAllowlistConfig added in v0.5.0 

type ToolAllowlistConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"` // default: false (opt-in)
}

ToolAllowlistConfig configures the tool call allowlist PreToolUse hook. Disabled by default — requires FULLSEND_TOOL_ALLOWLIST env var to define the allowed tool set per agent role.

type TraceConfig added in v0.0.3 

type TraceConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"` // default: true
}

TraceConfig controls trace ID generation for security finding correlation.

type ValidationLoop 

type ValidationLoop struct {
	Script        string `yaml:"script"`
	MaxIterations int    `yaml:"max_iterations"`
	FeedbackMode  string `yaml:"feedback_mode,omitempty"`
}

ValidationLoop configures a deterministic validation step after the agent exits.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.