Documentation
¶
Index ¶
- Constants
- func BoolDefault(b *bool, def bool) bool
- func ForgeKeyList() string
- func IsAbsPath(s string) bool
- func IsRelPath(s string) bool
- func IsURL(s string) bool
- func LoadWithBase(ctx context.Context, path string, opts ComposeOpts) (*Harness, []Dependency, error)
- func MatchingAllowedPrefixInList(rawURL string, allowlist []string) string
- func ParseIntegrityHash(rawURL string) (cleanURL, hash string, hasHash bool)
- func ValidForgePlatform(platform string) bool
- type APIServer
- type AgentInfo
- type ComposeOpts
- type Dependency
- type Diagnostic
- type DiagnosticSeverity
- type EscalationConfig
- type ForgeConfig
- type Harness
- func (h *Harness) EffectiveMaxRuntimeFetches() int
- func (h *Harness) FailModeClosed() bool
- func (h *Harness) HasURLReferences() bool
- func (h *Harness) HasURLSkills() bool
- func (h *Harness) Lint() []Diagnostic
- func (h *Harness) MatchesAllowedPrefix(rawURL string) bool
- func (h *Harness) MatchingAllowedPrefix(rawURL string) string
- func (h *Harness) ResolveForge(platform string) error
- 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 LoadOpts
- type ProviderDef
- type SandboxHooks
- type SecurityConfig
- type TirithConfig
- type ToolAllowlistConfig
- type TraceConfig
- type ValidationLoop
Constants ¶
const MaxBaseDepth = 5
MaxBaseDepth is the maximum depth of base chain inheritance. This prevents runaway recursion from circular or pathologically deep chains.
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 ForgeKeyList ¶ added in v0.18.0
func ForgeKeyList() string
ForgeKeyList returns a comma-separated list of valid forge platform keys.
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 LoadWithBase ¶ added in v0.18.0
func LoadWithBase(ctx context.Context, path string, opts ComposeOpts) (*Harness, []Dependency, error)
LoadWithBase loads a harness with base composition and forge resolution. If the harness has a `base` field, the base chain is recursively loaded and merged before forge resolution. Returns the merged harness and a list of dependencies for any URL bases that were fetched.
Pipeline:
- LoadRaw(path) — preserves forge map
- If base absent: ResolveForge → Validate → return
- If base present: loadBaseChain recursively, then mergeBaseIntoChild
- ResolveForge once on final merged result
- Validate
When base is absent, this behaves identically to LoadWithOpts.
func MatchingAllowedPrefixInList ¶ added in v0.18.0
MatchingAllowedPrefixInList checks if a URL matches any prefix in the given allowlist. Returns the matching prefix or "" if none match. Standalone version of MatchingAllowedPrefix.
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.
func ValidForgePlatform ¶ added in v0.18.0
ValidForgePlatform reports whether platform is a recognized forge key.
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 AgentInfo ¶ added in v0.18.0
type AgentInfo struct {
Role string // from the harness role: field
Slug string // from the harness slug: field
Filename string // e.g. "triage.yaml"
Path string // absolute path to the harness file
}
AgentInfo holds the identity of an agent discovered from a harness file.
func DiscoverAgents ¶ added in v0.18.0
DiscoverAgents scans dir for harness YAML files and returns agent identity (role, slug) from each. Files where both role and slug are empty are skipped. Parse errors on individual files are collected into a multi-error; valid files are still returned alongside the error.
Results are sorted by Role, then by Filename for deterministic output. Only top-level role/slug fields are read — base chains are not resolved. This is correct because generated wrappers set role/slug at the top level.
func DiscoverRemoteAgents ¶ added in v0.18.0
func DiscoverRemoteAgents(ctx context.Context, client forge.Client, owner, repo, ref string) ([]AgentInfo, error)
DiscoverRemoteAgents discovers agent identity (role, slug) from harness files in a remote config repo via the forge API. It is the remote counterpart of DiscoverAgents, which reads from the local filesystem.
Files where both role and slug are empty are skipped. Per-file errors (parse failures, GetFileContentAtRef failures) are collected into a multi-error; valid files are still returned alongside the error.
Results are sorted by Role, then by Filename for deterministic output. Returns (nil, nil) when the harness/ directory does not exist.
type ComposeOpts ¶ added in v0.18.0
type ComposeOpts struct {
// WorkspaceRoot is the root directory for cache paths (typically the repo root).
WorkspaceRoot string
// FetchPolicy controls SSRF protection, offline mode, and size limits.
FetchPolicy fetch.FetchPolicy
// TraceID is a correlation ID for audit log entries.
TraceID string
// AuditLogPath is the path to the fetch audit log (JSONL).
// If empty, audit logging is skipped.
AuditLogPath string
// ForgePlatform is the platform to resolve after base merging (e.g., "github").
// If empty, ResolveForge is a no-op.
ForgePlatform string
// OrgAllowlist is the org-level allowed_remote_resources from config.yaml.
// Base URLs must match a prefix in this list.
OrgAllowlist []string
// contains filtered or unexported fields
}
ComposeOpts controls base composition behavior.
type Dependency ¶ added in v0.18.0
type Dependency struct {
Field string
URL string
LocalPath string
SHA256 string
FetchedAt time.Time
CacheHit bool
Type string // "file" for base harnesses
Warning string // non-fatal warning about this dependency (e.g., partial skill fetch)
}
Dependency records a single URL that was resolved to a local cache path. This mirrors resolve.Dependency but lives here to avoid circular imports.
type Diagnostic ¶ added in v0.18.0
type Diagnostic struct {
Severity DiagnosticSeverity
Field string
Message string
}
Diagnostic represents a non-fatal issue found by Lint.
func (Diagnostic) String ¶ added in v0.18.0
func (d Diagnostic) String() string
type DiagnosticSeverity ¶ added in v0.18.0
type DiagnosticSeverity int
DiagnosticSeverity indicates whether a diagnostic is a warning or an error.
const ( SeverityWarning DiagnosticSeverity = iota SeverityError )
func (DiagnosticSeverity) String ¶ added in v0.18.0
func (s DiagnosticSeverity) String() string
String returns a human-readable description of the diagnostic severity.
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 ForgeConfig ¶ added in v0.17.0
type ForgeConfig struct {
PreScript string `yaml:"pre_script,omitempty"`
PostScript string `yaml:"post_script,omitempty"`
Skills []string `yaml:"skills,omitempty"`
ValidationLoop *ValidationLoop `yaml:"validation_loop,omitempty"`
RunnerEnv map[string]string `yaml:"runner_env,omitempty"`
}
ForgeConfig holds platform-specific harness configuration. This is purely declarative YAML config — it selects which scripts, skills, and env vars to use per platform. It is distinct from the forge.Client interface (internal/forge/), which is the runtime abstraction for forge API operations.
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"`
Role string `yaml:"role,omitempty"`
Slug string `yaml:"slug,omitempty"`
Base string `yaml:"base,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"`
AllowRuntimeFetch bool `yaml:"allow_runtime_fetch,omitempty"` // opt-in to runtime skill fetching (default: false)
MaxRuntimeFetches *int `yaml:"max_runtime_fetches,omitempty"` // per-run fetch cap; nil = default (10), valid range 1-1000
Forge map[string]*ForgeConfig `yaml:"forge,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 LoadRaw ¶ added in v0.18.0
LoadRaw reads and unmarshals a harness YAML file without calling Validate or ResolveForge. Used by base composition to load base harnesses without consuming their forge maps before merging, and by the lock command to discover forge keys without resolving them.
func LoadWithOpts ¶ added in v0.18.0
LoadWithOpts reads a harness YAML file and applies forge resolution before validation. The pipeline is: Unmarshal → validateForge → ResolveForge → Validate. validateForge runs first to reject malformed forge maps before ResolveForge consumes (nils out) the map. When ForgePlatform is empty, ResolveForge is a no-op but validateForge still runs.
func (*Harness) EffectiveMaxRuntimeFetches ¶ added in v0.18.0
EffectiveMaxRuntimeFetches returns the configured max runtime fetches, or defaultMaxRuntimeFetches (10) when the field is omitted.
func (*Harness) FailModeClosed ¶ added in v0.0.3
FailModeClosed returns true if the security fail mode is "closed" (default).
func (*Harness) HasURLReferences ¶ added in v0.14.0
HasURLReferences reports whether any declarative field (agent, policy, skills) contains a URL. Used to skip remote resource validation and resolution when the harness references only local paths.
func (*Harness) HasURLSkills ¶ added in v0.17.0
HasURLSkills reports whether any skill field contains a URL. Used to determine whether a forge client is needed for resolution.
func (*Harness) Lint ¶ added in v0.18.0
func (h *Harness) Lint() []Diagnostic
Lint returns non-fatal diagnostics for the harness. Call only after a successful Validate — Lint does not re-check structural validity, and its results are meaningless on an invalid harness. Returns nil when no diagnostics are found.
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) MatchingAllowedPrefix ¶ added in v0.13.0
MatchingAllowedPrefix returns the first AllowedRemoteResources entry that matches rawURL, or "" if none match. It applies the same normalization as MatchesAllowedPrefix.
func (*Harness) ResolveForge ¶ added in v0.17.0
ResolveForge merges forge-specific overrides into the harness in place. After merging, h.Forge is set to nil (consumed). If platform is empty or h.Forge is nil, this is a no-op. If platform is not present in h.Forge, an error is returned.
Pipeline ordering: LoadWithOpts calls validateForge → ResolveForge → Validate. validateForge must run first because ResolveForge consumes h.Forge (sets it to nil). After ResolveForge, Validate's validateForge call sees nil and is a no-op, which is correct because the forge map was already validated before merging.
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.
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. Callers must invoke ResolveRelativeTo first (to make paths absolute), then resolve.ResolveHarness (to replace any URL references with local cache paths). The IsURL guard inside is defense-in-depth in case the ordering is violated.
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 LoadOpts ¶ added in v0.18.0
type LoadOpts struct {
ForgePlatform string
}
LoadOpts configures forge-aware harness loading.
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.