Documentation
¶
Index ¶
- func BoolDefault(b *bool, def bool) bool
- func IsAbsPath(s string) bool
- func IsRelPath(s string) bool
- func IsURL(s string) bool
- func ParseIntegrityHash(rawURL string) (cleanURL, hash string, hasHash bool)
- type APIServer
- type EscalationConfig
- type Harness
- func (h *Harness) FailModeClosed() bool
- func (h *Harness) MatchesAllowedPrefix(rawURL string) bool
- func (h *Harness) ResolveRelativeTo(baseDir string) error
- func (h *Harness) Scripts() []string
- func (h *Harness) SecurityEnabled() bool
- func (h *Harness) Validate() error
- func (h *Harness) ValidateAllowedRemoteResources(orgAllowlist []string) error
- func (h *Harness) ValidateFilesExist() error
- func (h *Harness) ValidateResourceTypes() error
- func (h *Harness) ValidateRunnerEnv() error
- func (h *Harness) ValidateRunnerEnvWith(lookup func(string) (string, bool)) error
- type HostFile
- type HostScanners
- type LLMGuardConfig
- type ProviderDef
- type SandboxHooks
- type SecurityConfig
- type TirithConfig
- type ToolAllowlistConfig
- type TraceConfig
- type ValidationLoop
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BoolDefault ¶ added in v0.0.3
BoolDefault returns the value of a *bool, or the default if nil.
func IsRelPath ¶ added in v0.11.0
IsRelPath returns true if s is a non-empty relative file path (not a URL and not absolute).
func IsURL ¶ added in v0.11.0
IsURL returns true if s is a valid HTTPS URL suitable for remote resource references.
func ParseIntegrityHash ¶ added in v0.11.0
ParseIntegrityHash extracts the SHA256 hash from a URL fragment (#sha256=...). Returns the URL without the fragment, the hash value, and whether a valid hash was found. The hash is normalized to lowercase; both "sha256=ABC..." and "sha256=abc..." are accepted.
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"`
Doc string `yaml:"doc,omitempty"` // source-repo-only; not resolved at runtime, used by lint-agent-docs
Description string `yaml:"description,omitempty"`
Image string `yaml:"image,omitempty"`
Policy string `yaml:"policy,omitempty"`
Skills []string `yaml:"skills,omitempty"`
Plugins []string `yaml:"plugins,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"`
SandboxTimeoutSeconds int `yaml:"sandbox_timeout_seconds,omitempty"`
Security *SecurityConfig `yaml:"security,omitempty"`
AllowedRemoteResources []string `yaml:"allowed_remote_resources,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 (*Harness) FailModeClosed ¶ added in v0.0.3
FailModeClosed returns true if the security fail mode is "closed" (default).
func (*Harness) MatchesAllowedPrefix ¶ added in v0.12.0
MatchesAllowedPrefix reports whether rawURL starts with any entry in AllowedRemoteResources (case-insensitive). The URL path is percent-decoded and normalized (resolving ".." and "." segments) before prefix matching to prevent path-traversal bypasses via both literal and encoded dot segments. Returns false if the URL contains "%25" (double-encoded percent sign) or cannot be parsed.
func (*Harness) ResolveRelativeTo ¶
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. TODO(PR 7): skip URL-valued fields (agent, policy, skills[]) via IsURL().
func (*Harness) Scripts ¶ added in v0.0.4
Scripts returns all script paths configured in the harness.
func (*Harness) SecurityEnabled ¶ added in v0.0.3
SecurityEnabled returns true if security scanning is enabled (default: true).
func (*Harness) ValidateAllowedRemoteResources ¶ added in v0.12.0
ValidateAllowedRemoteResources checks that each entry in AllowedRemoteResources is a valid HTTPS URL ending with "/" and is covered by at least one entry in the org-level allowlist. Org allowlist entries are also validated: each must be a valid HTTPS URL ending with "/" and must not contain double-encoded sequences.
func (*Harness) ValidateFilesExist ¶
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) ValidateResourceTypes ¶ added in v0.12.0
ValidateResourceTypes checks that executable fields (pre_script, post_script, validation_loop.script, host_files[].src, api_servers[].script) are local paths and not URLs, and that declarative fields (agent, policy, skills[]) that are URLs include an integrity hash (#sha256=...).
func (*Harness) ValidateRunnerEnv ¶
ValidateRunnerEnv checks that all ${VAR} references in RunnerEnv and HostFiles.Src are defined in the host environment.
func (*Harness) ValidateRunnerEnvWith ¶ added in v0.0.4
ValidateRunnerEnvWith checks that all ${VAR} references in RunnerEnv and HostFiles.Src are defined in the host environment using the provided lookup function. Variables set to an empty string are allowed; only truly unset variables produce an error.
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.