tool

type ArgForm int

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

type ByteSize int64

type Class string

type ContentPack struct {
	// Digest is the pack's content address ("sha256:<hex>").
	Digest string `json:"digest"`
	// Source is where the pack came from (platform, tenant).
	Source string `json:"source,omitempty"`
	// Path is where the sensor keeps it, read-only for the task. Set by
	// the sensor's content cache, never taken from a job.
	Path string `json:"path,omitempty"`
}

type ContentSlot struct {
	// Slot names the slot in the tool ("templates").
	Slot string `json:"slot"`
	// Kind is what the content is: a known kind (nuclei-templates,
	// semgrep-rules, yara-rules, vuln-db, wordlist, signatures) or a
	// tool's own, namespaced (x-acme/rules). Packs bind to tools by kind.
	Kind string `json:"kind"`
	// Format is dir (default), file or archive.
	Format string `json:"format,omitempty"`
	// Default is bundled (the platform's managed pack of this kind is
	// used unless a step says otherwise) or none.
	Default string `json:"default,omitempty"`
	// Modes are the compositions the tool supports: default, custom and
	// merge (default: all three).
	Modes []string `json:"modes,omitempty"`
	// Selectors are the filters the tool understands: tags, ids,
	// severities, paths.
	Selectors []string `json:"selectors,omitempty"`
	// MaxBytes bounds a pack of this slot (0: the sensor's limit).
	MaxBytes int64 `json:"max_bytes,omitempty"`
}

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. On a sensor that confines the
	// task's network it goes through the task's forwarder (EgressProxy).
	// Requests carry the User-Agent "openctem-<tool>/<version>" unless the
	// tool sets its own. A tool that speaks TCP itself uses Dial.
	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 Deprecation struct {
	Since      string `json:"since"`
	ReplacedBy string `json:"replaced_by,omitempty"`
	Message    string `json:"message,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
	// Endpoint emits a method and path a web origin serves (CTIS 1.6).
	// A URL in it never carries a query value or credentials.
	Endpoint(e ctis.Endpoint) 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 Engine struct {
	Name    string `json:"name"`
	License string `json:"license,omitempty"`
	// MinVersion: an older probed engine reports the tool as outdated.
	MinVersion string `json:"min_version,omitempty"`
	// VersionProbe is the argv that prints the engine's version (no
	// shell, no placeholders).
	VersionProbe []string `json:"version_probe,omitempty"`
}

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 Features struct {
	// Retest: the tool can check again what it reported (see Retester).
	Retest bool `json:"retest,omitempty"`
	// Cancel: the tool stops promptly on a cancel message.
	Cancel bool `json:"cancel,omitempty"`
	// WebScope: the tool keeps every request inside the job's web scope
	// (Task.WebScope): it maps the scope onto its own flags, or requests
	// only through Context.HTTP, which enforces it. A job with a web scope
	// is refused for a networked tool that does not declare it.
	WebScope bool `json:"web_scope,omitempty"`
	// Streaming is reserved: feeding records to the next stage while the
	// task runs is not part of protocol v1.
	Streaming bool `json:"streaming,omitempty"`
}

type Filesystem string

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

type HTTPSpec struct {
	// UserAgent replaces the default "openctem-<tool>/<version>".
	UserAgent string `json:"user_agent,omitempty"`
	// Headers are added to every request that does not set them.
	Headers map[string]string `json:"headers,omitempty"`
	// Timeout bounds one request (1s to 10m; default 5m).
	Timeout Duration `json:"timeout,omitempty"`
	// TLS adjusts TLS toward the targets.
	TLS *TLSSpec `json:"tls,omitempty"`
}

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

type Implementation struct {
	// Capability is the capability reference with its major
	// ("scan.ports@1").
	Capability string `json:"capability"`
	// Params maps the capability's standard params this tool accepts to
	// its own config keys. A standard param not listed is one the tool
	// does not take: a workflow node that sets it cannot run this tool.
	Params map[string]ParamMapping `json:"params,omitempty"`
	// OutputShape names which of the capability's accepted output shapes
	// the tool emits, when the capability has several.
	OutputShape string `json:"output_shape,omitempty"`
}

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 InputSpec struct {
	// Batch is BatchOne (default) or BatchList.
	Batch string `json:"batch,omitempty"`
	// MaxTargets bounds a list task (BatchList only).
	MaxTargets int `json:"max_targets,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"`
	// Publisher is who publishes the tool: the signer of a certified
	// tool, or free text (shown as text, never trusted).
	Publisher string `json:"publisher,omitempty"`
	// License is the SPDX license expression of the adapter (the wrapped
	// engine's is engine.license).
	License string `json:"license,omitempty"`
	// Engine is the program the tool wraps; its version is probed.
	Engine *Engine `json:"engine,omitempty"`
	// Presentation is how the platform shows the tool.
	Presentation *Presentation `json:"presentation,omitempty"`
	Class        Class         `json:"class"`
	// Modes the tool runs in; empty means both.
	Modes []Mode `json:"modes,omitempty"`
	// Tier is the tier the tool asks for. It cannot be below the tier
	// floor of a capability it implements; the platform assigns the
	// effective tier and may raise it (MinimumTier).
	Tier Tier `json:"tier"`
	// Implements are the capabilities of the OpenCTEM capability taxonomy
	// the tool implements ("scan.ports@1"), with its param mapping.
	Implements []Implementation `json:"implements,omitempty"`
	// Capabilities is the older free-form capability list. Deprecated:
	// use Implements. With Implements set it may only repeat its ids.
	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"`
	// Input is how the tool takes its targets (default: one per task).
	Input *InputSpec `json:"input,omitempty"`
	// 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"`
	// Safety is what the tool does to its targets beyond reading them.
	Safety *Safety `json:"safety,omitempty"`
	// Features are the optional protocol features the tool supports.
	Features *Features `json:"features,omitempty"`
	// HTTP is how the tool's requests to its targets look (user agent,
	// headers, timeout, TLS): applied by ctx.HTTP(), named in exec argv
	// ({{http.user_agent}}) and readable by an adapter from its manifest.
	HTTP *HTTPSpec `json:"http,omitempty"`

	// Content are the kinds of content the tool reads (templates, rules,
	// wordlists): the task gets the resolved packs (api RFC-061).
	Content []ContentSlot `json:"content,omitempty"`
	// 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. Deprecated spelling of
	// features.retest.
	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"`
	// SDK is the oldest SDK that understands every key this manifest uses.
	SDK *SDKRequirement `json:"sdk,omitempty"`
	// Deprecated marks a tool being replaced.
	Deprecated *Deprecation `json:"deprecated,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, OutputJSONLCTIS, OutputJSON or
	// OutputJSONL (with Mapping), or a named format of ctis/importer
	// (ImporterFormats: "nuclei", "trivy", "cyclonedx", ...).
	Format string `json:"format"`
	// From is "stdout" or "file" (the {{task.output}} path).
	From string `json:"from"`
	// Mapping is the mapping file (relative to the manifest's directory)
	// that turns json or jsonl output into CTIS: the declarative mapping
	// language of ctis/importer/mapping, in JSON or YAML.
	Mapping string `json:"mapping,omitempty"`
	// MappingDigest is the mapping's digest, set when the manifest file is
	// loaded (LoadManifestFile); the manifest digest covers it, and the
	// runtime refuses a mapping file that no longer matches it.
	MappingDigest string `json:"mapping_digest,omitempty"`
}

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

type ParamMapping struct {
	// Key is the top-level config key; empty means the param's own name.
	Key string `json:"key,omitempty"`
	// Values narrows an enum param (or the items of a list param) to the
	// values the tool supports. A value outside makes the tool ineligible
	// for that node; it is never silently dropped.
	Values []string `json:"values,omitempty"`
	// Min and Max narrow an integer param.
	Min *int `json:"min,omitempty"`
	Max *int `json:"max,omitempty"`
}

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"`
	// Proxy is ProxyHonours or ProxyIgnores; unset is unknown, which the
	// platform treats as ignores where a zone requires a proxy.
	Proxy string `json:"proxy,omitempty"`
}

type Presentation struct {
	DisplayName string `json:"display_name,omitempty"`
	Category    string `json:"category,omitempty"`
	Icon        string `json:"icon,omitempty"`
	DocsURL     string `json:"docs_url,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)
	// Report is Verdict with the attempt's evidence and the digest of the
	// check that ran. Evidence over MaxVerdictEvidence items or invalid
	// makes the verdict Unverifiable.
	Report(item RetestItem, r VerdictReport)
}

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"`
	// Evidence is what the attempt saw (at most MaxVerdictEvidence items),
	// sensitive values marked (ctis.MarkSensitive), never masked.
	Evidence []ctis.EvidenceItem `json:"evidence,omitempty"`
	// TemplateDigest identifies the exact check that ran (a template's
	// digest), so the platform can tell a fix from a changed check.
	TemplateDigest string `json:"template_digest,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) and its forms {{config.<key>?}} (left out when not set),
	// {{config.<key>...}} (an array key: one argument per item, or
	// comma-joined inside a larger argument) and {{config.<key>?:-flag}}
	// (a boolean key: the flag when true; see ConfigArg), {{target.value}},
	// {{target.host}}, {{target.port}}, {{target.url}},
	// {{task.targets_file}}, {{task.targets_json}}, {{task.config_file}},
	// {{task.web_scope_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 SDKRequirement struct {
	Min string `json:"min,omitempty"`
}

type Safety struct {
	// RateParam is the integer config key that bounds requests or packets
	// per second; the runtime caps it by the sensor's local policy.
	RateParam string `json:"rate_param,omitempty"`
	// SideEffects the tool may cause. Any entry makes the tool intrusive
	// (tier T2).
	SideEffects []string `json:"side_effects,omitempty"`
	// ExpandsTargets: the tool discovers new targets. They go to the
	// platform as assets; the tool never scans them in the same task.
	ExpandsTargets bool `json:"expands_targets,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 TLSSpec struct {
	// InsecureSkipVerify accepts any certificate (scanning a target with a
	// self-signed or expired one). Refused for a vendor-network tool:
	// credentials travel to vendor hosts.
	InsecureSkipVerify bool `json:"insecure_skip_verify,omitempty"`
	// MinVersion is "1.0", "1.1", "1.2" or "1.3" (default: Go's).
	MinVersion string `json:"min_version,omitempty"`
}

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"`
	// Capability is the capability the task runs ("scan.ports@1"), one the
	// tool implements. The runtime checks the output against its contract.
	Capability string `json:"capability,omitempty"`
	// Params are the capability's standard params as the workflow set
	// them. The runtime maps them onto the tool's config keys
	// (Manifest.ApplyParams) before the tool starts; the tool reads only
	// Config and never receives Params.
	Params map[string]json.RawMessage `json:"params,omitempty"`
	// MaxTier is the highest tier the job allows (the ceiling of the
	// platform grant). A tool whose MinimumTier is higher is refused.
	MaxTier Tier `json:"max_tier,omitempty"`
	// WebScope, when set, is the hosts, paths and methods a web tool may
	// request (webscope.Scope). Context.HTTP refuses every request outside
	// it; a tool that makes its own requests declares features.web_scope
	// and keeps to it.
	WebScope *webscope.Scope `json:"web_scope,omitempty"`
	// Limits are the port, protocol and path limits of the targets (from
	// the job's verified signed statement; scopelimit). The tool host
	// enforces them outside the tool: the task's egress forwarder refuses
	// a connection to a limited host on another port and an HTTP request
	// outside its path prefixes. A task with limits runs only on a sandbox
	// that confines its network.
	Limits []scopelimit.Limit `json:"limits,omitempty"`
	// HTTP is the effective http settings of the task: the manifest's,
	// with what the sensor's local policy decides (a forced User-Agent).
	// Set by the runtime, never taken from a job; ctx.HTTP() applies it.
	HTTP *HTTPSpec `json:"http,omitempty"`
	// OrgHTTP is the organization's HTTP policy from the job. The tool host
	// merges it into HTTP (after the local policy) and clears it; a tool
	// never acts on it.
	OrgHTTP *core.OrgHTTPPolicy `json:"-"`
	// Content are the task's content packs per slot the manifest
	// declares, resolved by the sensor to read-only paths (ContentPaths).
	Content []TaskContent `json:"content,omitempty"`
}

type TaskContent struct {
	Slot string `json:"slot"`
	// Mode is default, custom or merge.
	Mode string `json:"mode,omitempty"`
	// Packs are the packs, in order (a merge: custom after default).
	Packs []ContentPack `json:"packs,omitempty"`
	// Selectors filter the content (tags, ids, severities, paths).
	Selectors map[string][]string `json:"selectors,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

type VerdictReport struct {
	Verdict        Verdict
	Detail         string
	Evidence       []ctis.EvidenceItem
	TemplateDigest string
}