Documentation
¶
Overview ¶
Package toolcompat runs code written against the older interfaces (core.Scanner, core.Collector) as tools of the tool contract (pkg/tool), so it gets the contract's runtime without a rewrite: out-of-process execution in the task sandbox, admission against the policy, declared credentials only, checked and stamped output.
Stability: Beta (docs/STABILITY.md). The bridges are transitional: new code implements tool.Tool directly; the bridges are removed once every in-tree scanner is ported (docs/rfcs/sensor-sdk-v2.md D.12).
A bridged tool is compiled into the sensor like any tool: list it in adapter.Dispatch in main, so the re-executed child can serve it. In the child, Run calls the scanner (or collector), converts its raw output to CTIS with a parser, and emits the report through the runtime's emitter, which refuses any record type the manifest does not declare.
What crosses from the sensor into the child is Task.Local: the scan options a run uses and, with WithState, the scanner's exported fields as JSON. Secrets never travel that way: declare them as credentials in the manifest and set them in the child with WithPrepare (ctx.Secret); fields tagged json:"-" stay behind.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AsScanner ¶
func AsScanner(t tool.Tool, cfg ScannerConfig) core.Scanner
AsScanner returns t as a core.Scanner, so the command executor, the scheduler, the outbox and the heartbeat serve it like any scanner, while every task runs out of process through the host: a tool compiled into the sensor is re-executed (toolhost RunBuiltin), a tool with a run section (an adapter or exec-profile CLI the operator installed) runs as its own program (RunManifest). Its raw output is the checked CTIS report.
The scanner reports the tool's contract (core.ToolContractProvider) and its configuration schema (core.SettingsSchemaProvider), so the platform validates scan settings against the manifest; those settings become the task's configuration. A bridged legacy scanner (FromScanner) keeps its name, version, capabilities and installation check, and its scan options travel in Task.Local.
func RetestCapability ¶
RetestCapability is the capability a sensor reports for a tool that can retest: "retest:<tool>". The platform routes retest commands by it.
Types ¶
type Bridge ¶
type Bridge interface {
tool.Tool
// Legacy is the bridged scanner (core.Scanner) or collector
// (core.Collector), as the sensor configured it.
Legacy() any
}
Bridge is a tool built from a scanner or a collector.
type CollectorBridge ¶
type CollectorBridge interface {
Bridge
// Collector is the bridged collector.
Collector() core.Collector
// Local is the Task.Local of a collection with opts. Its APIKey is
// never part of it (WithAPIKeyCredential).
Local(opts *core.CollectOptions) (json.RawMessage, error)
}
CollectorBridge is a tool built from a core.Collector.
func FromCollector ¶
FromCollector returns c as a tool described by m (a connector: its network is the declared vendor hosts). Each task collects once and emits every report.
type Option ¶
type Option func(*options)
Option configures a bridge.
func WithAPIKeyCredential ¶
WithAPIKeyCredential sets CollectOptions.APIKey of a bridged collector from the declared credential name (ctx.Secret). The sensor's own APIKey is never sent to the child.
func WithParser ¶
WithParser converts the scanner's raw output with p. Without it the child picks a parser the way the command executor does: the SDK's SARIF and CTIS parsers.
func WithPrepare ¶
WithPrepare runs fn in the child before each run, with the scanner or collector the run uses: the place to set declared credentials (ctx.Secret) on it.
func WithState ¶
func WithState() Option
WithState sends the scanner's exported state (encoding/json of the scanner, which must be a pointer to a struct) to the child, which decodes it into a fresh value before the scan. Without it the child uses the scanner as its own main built it. Fields tagged json:"-" stay in the sensor; never put a secret in a field that is sent.
type Retester ¶
type Retester interface {
core.Scanner
Retests() bool
RunRetest(ctx context.Context, task tool.Task) (*toolhost.Outcome, error)
}
Retester is a scanner that also runs retest tasks of its tool (the sensor's retest command): Retests reports whether the manifest declares retest, RunRetest runs one retest task through the same host, admission and options as a scan.
type ScannerBridge ¶
type ScannerBridge interface {
Bridge
// Scanner is the bridged scanner.
Scanner() core.Scanner
// Local is the Task.Local of a scan with opts: what the child needs to
// run the scanner as the sensor configured it. Credentials are never
// part of it.
Local(opts *core.ScanOptions) (json.RawMessage, error)
}
ScannerBridge is a tool built from a core.Scanner.
func FromScanner ¶
FromScanner returns s as a tool described by m. Each task scans its targets (all at once when s is a core.MultiTargetScanner, else one by one), converts the raw output to CTIS and emits it; a target whose scan failed is reported failed, the others done.
m.Config, when set, is the schema the task's configuration is validated against; the child hands the configuration to the scanner as ScanOptions.Settings. FromScanner panics on an invalid manifest, or on WithState with a scanner that is not a pointer to a struct (a bridged tool with a broken definition must stop the sensor at start).
type ScannerConfig ¶
type ScannerConfig struct {
// Host runs the tasks (required): its Policy admits each one.
Host *toolhost.Host
// Credentials returns the credentials the operator stored for the
// tool (nil: none). Only those the manifest declares are delivered.
Credentials func() map[string]string
// Mode is the sensor mode the tasks run in (checked against the
// manifest's modes; "": not checked).
Mode tool.Mode
// Dir is the manifest's directory, for a tool that is its own program
// (run.argv relative to it).
Dir string
}
ScannerConfig configures AsScanner.
Source Files