tool

type Builder struct {
	// contains filtered or unexported fields
}

type ByteSize int64

type Class string

type Context interface {
	context.Context

	// Log is a structured logger. Values are redacted (Secret prints
	// [REDACTED]) and the runtime bounds the rate and size of what it
	// keeps.
	Log() *slog.Logger
	// Progress reports done of total units (throttled by the runtime).
	Progress(done, total int, msg string)
	// Emit is the record channel. Each record is checked when it is
	// emitted.
	Emit() Emitter
	// TargetDone reports that the tool finished a target.
	TargetDone(t Target)
	// TargetError reports that a target failed (its scan coverage); err
	// is categorized like a Run error.
	TargetError(t Target, err error)
	// TargetSkipped reports that the tool did not work on a target.
	TargetSkipped(t Target, reason string)
	// Artifact creates a size-capped artifact (a raw log, a screenshot),
	// delivered separately from the records.
	Artifact(name, mediaType string) (io.WriteCloser, error)
	// Workdir is the task's private directory, removed after the task.
	Workdir() string
	// Secret returns a credential the manifest declares and the operator
	// stored; anything else is ErrUndeclaredCredential.
	Secret(name string) (Secret, error)
	// HTTP is a client that reaches only what the manifest's network
	// permission allows: the task's targets (NetTargets), the vendor
	// hosts (NetVendor) or nothing (NetNone); it never reaches cloud
	// metadata endpoints. It is defense in depth: the sandbox backend's
	// network class is the boundary.
	HTTP() *http.Client
}

type CredentialReq struct {
	// Name is how the tool asks for it (Context.Secret).
	Name        string `json:"name"`
	Kind        string `json:"kind"`
	Required    bool   `json:"required,omitempty"`
	Description string `json:"description,omitempty"`
}

type Duration time.Duration

type Emit struct {
	// contains filtered or unexported fields
}

type Emitter interface {
	// Asset emits an asset.
	Asset(a ctis.Asset) error
	// Finding emits a finding of target t. A finding without an asset
	// reference is filed on t's asset.
	Finding(t Target, f ctis.Finding) error
	// Dependency emits a dependency (SBOM component) found on t.
	Dependency(t Target, d ctis.Dependency) error
	// Report emits every record of a report (the output of a converter),
	// plus its tool, metadata and properties (ReportInfo).
	Report(r *ctis.Report) error
}

type Error struct {
	Class ErrorClass
	// Retryable defaults from Class; a tool may only turn it off.
	Retryable  bool
	RetryAfter time.Duration
	// Detail is a short, human description. The runtime redacts it and
	// caps it at MaxErrorDetail bytes before it leaves the sensor.
	Detail string
	// Err is the cause, for local logs only; it is never sent.
	Err error
}

type ErrorClass string

type Filesystem string

type Fixture struct {
	Name   string `json:"name"`
	Task   string `json:"task"`
	Expect string `json:"expect"`
}

type Handler func(ctx Context, job *Job, emit Emit) error

type Input struct {
	Name      string `json:"name"`
	MediaType string `json:"media_type"`
	// Path is relative to the task's directory.
	Path   string `json:"path"`
	Size   int64  `json:"size,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
}

type Issue struct {
	RuleID      string
	Title       string
	Severity    ctis.Severity
	Description string
	// Evidence is the proof (a response excerpt, a banner); never a
	// secret value.
	Evidence string
	// CVE is the vulnerability's CVE id (Vulnerability only).
	CVE string
}

type Job struct {
	Task
	// contains filtered or unexported fields
}

type Manifest struct {
	// APIVersion is APIVersion ("" in Go code means APIVersion).
	APIVersion string `json:"apiVersion"`
	// Name is unique per sensor: ^[a-z][a-z0-9-]{1,62}$.
	Name string `json:"name"`
	// Version is the semantic version of the tool adapter (not of the
	// engine it runs).
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
	Class       Class  `json:"class"`
	// Modes the tool runs in; empty means both.
	Modes []Mode `json:"modes,omitempty"`
	Tier  Tier   `json:"tier"`
	// Capabilities are the platform's capability ids the tool provides
	// ("web.probe", "vuln.templates", ...).
	Capabilities []string `json:"capabilities,omitempty"`
	// Consumes are CTIS asset types, "file:<media type>" for parsers, or
	// "finding:<type>" for enrichers.
	Consumes []string `json:"consumes,omitempty"`
	// Produces are "asset:<type>", "finding:<type>" or "dependency". A
	// record of any other kind is refused (ErrUndeclaredOutput).
	Produces []string `json:"produces"`
	// Config is the tool's configuration schema: the closed JSON Schema
	// subset of api RFC-038 (pkg/core settings schemas), with no secret
	// fields (secrets are credentials, never configuration). nil: no
	// configuration (New derives one from the config type when it has
	// fields).
	Config      json.RawMessage `json:"config,omitempty"`
	Permissions Permissions     `json:"permissions"`
	Resources   Resources       `json:"resources"`
	// Selftest are fixtures: a task and the CTIS it must produce.
	Selftest []Fixture `json:"selftest,omitempty"`
	// Retest says the tool can check again what it reported (a retest
	// task, see Retester). Target-scan tools only.
	Retest bool `json:"retest,omitempty"`
	// Protocol is the range of adapter protocol versions the tool speaks.
	Protocol Range `json:"protocol"`
	// Run says how to start a tool that is not compiled into the sensor.
	Run *RunSpec `json:"run,omitempty"`
}

type ManifestError struct {
	Path    string
	Message string
}

type ManifestErrors []ManifestError

type Mode string

type Network string

type NoConfig struct{}

type OutputSpec struct {
	// Format is OutputCTIS, OutputSARIF or OutputJSONLCTIS.
	Format string `json:"format"`
	// From is "stdout" or "file" (the {{task.output}} path).
	From string `json:"from"`
}

type Param struct {
	// contains filtered or unexported fields
}

type Permissions struct {
	// Network defaults by class: none for parsers and enrichers, targets
	// for target scans, vendor for connectors.
	Network Network `json:"network,omitempty"`
	// VendorHosts are the hosts a vendor-network tool may reach
	// ("api.example.com", "api.example.com:8443", or "${config.<key>}" for
	// a string configuration key holding a URL or host).
	VendorHosts []string   `json:"vendor_hosts,omitempty"`
	Filesystem  Filesystem `json:"filesystem,omitempty"`
	// Credentials the tool may receive. Only these are ever delivered,
	// and only when the sensor's operator stored them.
	Credentials []CredentialReq `json:"credentials,omitempty"`
	// LinuxCaps the tool needs (NET_RAW for SYN scans); granted only when
	// the local policy allows.
	LinuxCaps []string `json:"linux_caps,omitempty"`
}

type Range struct {
	Min int `json:"min,omitempty"`
	Max int `json:"max,omitempty"`
}

type Repo struct {
	URL           string `json:"url,omitempty"`
	Branch        string `json:"branch,omitempty"`
	Commit        string `json:"commit,omitempty"`
	DefaultBranch bool   `json:"default_branch,omitempty"`
	PullRequest   int    `json:"pull_request,omitempty"`
}

type ReportInfo struct {
	Tool       *ctis.Tool          `json:"tool,omitempty"`
	Metadata   *ReportInfoMetadata `json:"metadata,omitempty"`
	Properties ctis.Properties     `json:"properties,omitempty"`
}

type ReportInfoMetadata struct {
	ID           string           `json:"id,omitempty"`
	DurationMs   int              `json:"duration_ms,omitempty"`
	SourceRef    string           `json:"source_ref,omitempty"`
	SourceType   string           `json:"source_type,omitempty"`
	CoverageType string           `json:"coverage_type,omitempty"`
	Branch       *ctis.BranchInfo `json:"branch,omitempty"`
	Scope        *ctis.Scope      `json:"scope,omitempty"`
	Properties   ctis.Properties  `json:"properties,omitempty"`
}

type Resources struct {
	CPU            float64  `json:"cpu,omitempty"`
	Memory         ByteSize `json:"memory,omitempty"`
	Timeout        Duration `json:"timeout,omitempty"`
	IdleTimeout    Duration `json:"idle_timeout,omitempty"`
	MaxOutputBytes ByteSize `json:"max_output_bytes,omitempty"`
	MaxRecords     int      `json:"max_records,omitempty"`
	// Cost is the slot cost for the sensor's capacity model.
	Cost int `json:"cost,omitempty"`
}

type RetestContext interface {
	Context
	// Verdict reports the verdict on item. The first verdict of an item
	// counts; a verdict on an item not in the task is ignored. detail is
	// cut to MaxErrorDetail and redacted.
	Verdict(item RetestItem, v Verdict, detail string)
}

type RetestItem struct {
	// Ref is the platform's opaque id of the item, echoed in its verdict.
	Ref string `json:"ref"`
	// Target is the ref of the task target the item is on.
	Target string `json:"target"`
	// Kind is RetestFinding or RetestAsset.
	Kind string `json:"kind"`
	// RuleID is the check that reported the finding (a template id, a rule
	// id).
	RuleID string `json:"rule_id,omitempty"`
	// Fingerprint is the finding's fingerprint as the platform keeps it.
	Fingerprint string `json:"fingerprint,omitempty"`
	// Attrs are typed hints from the platform.
	Attrs map[string]string `json:"attrs,omitempty"`
}

type RetestVerdict struct {
	Ref     string  `json:"ref"`
	Verdict Verdict `json:"verdict"`
	Detail  string  `json:"detail,omitempty"`
}

type Retester interface {
	Retest(ctx RetestContext, task Task) error
}

type RunSpec struct {
	// Profile is ProfileAdapter (default) or ProfileExec.
	Profile string `json:"profile,omitempty"`
	// Argv is the program and its arguments. Never a shell. Placeholders
	// are a closed set: {{config.<key>}} (a scalar key of the config
	// schema), {{target.value}}, {{target.host}}, {{target.port}},
	// {{target.url}}, {{task.targets_file}}, {{task.targets_json}},
	// {{task.config_file}}, {{task.output}}, {{task.workdir}}.
	Argv []string `json:"argv"`
	// Output is where an exec-profile tool writes its results.
	Output *OutputSpec `json:"output,omitempty"`
	// ExitCodes maps an exec-profile tool's exit codes to outcomes
	// ("ok", "partial") or error classes; default: 0 ok, else tool_error.
	ExitCodes map[string]string `json:"exit_codes,omitempty"`
}

type Scope struct {
	Includes []string `json:"includes,omitempty"`
	Excludes []string `json:"excludes,omitempty"`
}

type Secret struct {
	// contains filtered or unexported fields
}

type Status string

type Target struct {
	// Ref is an opaque reference that links records to the platform's
	// asset.
	Ref string `json:"ref"`
	// Type is a CTIS asset type ("http_service", "domain", "repository").
	Type string `json:"type,omitempty"`
	// Value is the target itself ("https://a.example:8443", "10.0.4.7",
	// "/src").
	Value string `json:"value"`
	// Attrs are typed hints from the platform (port, scheme, tech, ...).
	Attrs map[string]string `json:"attrs,omitempty"`
}

type TargetState string

type Task struct {
	ID       string    `json:"id"`
	Attempt  int       `json:"attempt,omitempty"`
	Deadline time.Time `json:"deadline,omitzero"`
	Targets  []Target  `json:"targets,omitempty"`
	// Config is the effective configuration (defaults applied).
	Config json.RawMessage `json:"config,omitempty"`
	// Inputs are files placed in the task's directory (parsers).
	Inputs []Input `json:"inputs,omitempty"`
	// Repo is the repository of a runner-mode (CI) task.
	Repo *Repo `json:"repo,omitempty"`
	// Scope is the job's scope, read-only, for tools that expand targets.
	// Expanded targets are emitted as assets, never scanned in the same
	// task.
	Scope Scope `json:"scope,omitzero"`
	// Local is configuration the sensor itself supplies for a tool compiled
	// into it (operator settings, managed content paths): never from the
	// platform, never for an adapter shipped on its own.
	Local json.RawMessage `json:"local,omitempty"`
	// Retest, when not empty, makes the task a retest: the items to check
	// again, each on one of Targets (see Retester).
	Retest []RetestItem `json:"retest,omitempty"`
}

type Tier string

type Tool interface {
	// Manifest describes the tool. It is static: the runtime reads it
	// before any tool code runs.
	Manifest() Manifest
	// Run does the work of one task.
	Run(ctx Context, task Task) error
}

type Validator interface {
	Validate(ctx context.Context, task Task) error
}

type Value struct {
	// contains filtered or unexported fields
}

type Verdict string