sdk-go

OpenCTEM SDK

Go SDK for building sensors, tools and integrations for the OpenCTEM platform. Product documentation: https://docs.openctem.io.

Overview

OpenCTEM SDK provides Go packages for:

• pkg/sensorkit: the sensor runtime in one call (identity, connection, heartbeat, commands, durable outbox, per-task tool sandbox, local policy, preflight checks and the config report)
• pkg/client: the platform protocol client
• pkg/ctis: the CTIS result types
• pkg/httpsec: SSRF-safe HTTP clients
• pkg/conformance: a fake platform and the sensor conformance suite
• cmd/openctem: openctem tool init|validate|run|test|diff|describe, to scaffold a tool from a capability and check it with the conformance kit (docs/tools/cli.md)

The scanner wrappers (Semgrep, CodeQL, Trivy, Betterleaks, Nuclei and the recon tools) live in the sensor (github.com/openctemio/sensor), not in the SDK. What each package promises is in docs/STABILITY.md; where the SDK is going is in docs/rfcs/sensor-sdk-v2.md.

Installation

go get github.com/openctemio/sdk-go

Upgrading from v0.6 (agent → sensor)

v0.7.0 renames the agent vocabulary to sensor (core.BaseAgent → core.BaseSensor, client.WithAgentID → client.WithSensorID, …). Upgrade your module with the codemod, which rewrites only SDK identifiers, type-safely, then moves you to the new SDK:

go run github.com/openctemio/sdk-go/cmd/sensor-migrate@v0.7.0 -dry-run   # review
go run github.com/openctemio/sdk-go/cmd/sensor-migrate@v0.7.0            # apply

The SDK migrates a sensor's saved credentials by itself. The old setting names (AGENT_ID, AGENT_NAME, AGENT_ALLOW_PRIVATE_TARGETS, API_URL, API_KEY, REGION, PLATFORM_KEY_AUTORENEW, OPENCTEM_SDK_ALLOW_PRIVATE_TARGETS) are no longer read: a sensor refuses to start (exit 2) while one is set and names its replacement. Current SDK releases speak sensor protocol v3 (gRPC over mutual TLS, or HTTPS) and fall back to v2 on a platform without v3; protocol v1 is retired, so they need an OpenCTEM platform from 2026-10 on. See CHANGELOG.md for the full list.

Quick Start

Push a report

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/openctemio/sdk-go/pkg/client"
	"github.com/openctemio/sdk-go/pkg/ctis"
)

func main() {
	c := client.New(&client.Config{
		BaseURL: "https://openctem.example.com", // the API base URL, not the web UI
		APIKey:  os.Getenv("SENSOR_API_KEY"),           // a sensor key from Settings > Sensors
	})
	defer c.Close()

	report := ctis.NewReport()
	report.Tool = &ctis.Tool{Name: "my-scanner", Version: "1.0.0"}
	report.Findings = append(report.Findings, ctis.Finding{
		ID:       "finding-001",
		Type:     ctis.FindingTypeVulnerability,
		Title:    "SQL Injection",
		Severity: ctis.SeverityHigh,
		Location: &ctis.FindingLocation{Path: "src/db.go", StartLine: 42},
	})

	res, err := c.PushFindings(context.Background(), report)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", res)
}

Build a sensor in 30 lines

pkg/sensorkit is the whole sensor runtime in one call. A sensor implements its tools; the kit reads the settings, connects (sensor protocol v2, features negotiated on hello), reports the tools on every heartbeat, waits while the key is rejected, follows the heartbeat doorbell, claims commands into resource-sized slots, delivers results through the durable outbox, renews the API key and drains on SIGTERM.

package main

import (
	"context"
	"time"

	"github.com/openctemio/sdk-go/pkg/core"
	"github.com/openctemio/sdk-go/pkg/sensorkit"
)

var version = "dev"

func main() {
	tool := core.NewBaseScanner(&core.BaseScannerConfig{ // your tool's binary
		Name: "mytool", Binary: "mytool", Capabilities: []string{"sast"},
		DefaultArgs: []string{"scan", "--sarif", "{target}"}, Timeout: 30 * time.Minute,
	})
	kit, err := sensorkit.New(sensorkit.Options{Name: "my-sensor", Version: version})
	sensorkit.Exit(err)    // a clear message and exit code for a bad setting
	kit.AddScanner(tool)   // reported (installed? version?), dispatched, scheduled
	sensorkit.Exit(kit.Run(context.Background())) // blocks; SIGINT/SIGTERM drain
}

Run it with SENSOR_API_URL. Without SENSOR_API_KEY the sensor pairs on first start (an administrator approves it under Sensors > Pair a sensor); with SENSOR_API_KEY (a sensor key from Settings > Sensors) it uses that key. examples/minimal-sensor is a complete one with an in-process tool.

Keep the state directory. A key renewal retires the key the sensor was started with; the renewed key is saved in sensor-credentials.json in the state directory (0600) and used on the next start instead of SENSOR_API_KEY. In a container, mount one data volume at /var/lib/openctem (-v my-sensor-data:/var/lib/openctem; it holds state/, outbox/ and content/, which the kit creates 0700 when missing): without one the kit does not renew, because a recreated container would come back with the retired key. A volume on /var/lib/openctem/state itself works too: a directory counts as persistent when its nearest mount is a real volume. When an administrator regenerates the key and SENSOR_API_KEY is set to the new one, the new key wins. Every heartbeat also carries the process's instance_id, so the platform flags one key running in two places.

Plug your own parts in: kit.AddCollector, kit.AddParser (your tool's output format), kit.HandleCommand("type", executor), kit.UseCommandMiddleware(mw, "type") (wrap every command), Options.Content (managed scanner content on the heartbeat), Options.ScanTargetPolicy, Options.AssetResolver, kit.Tools() (more tools or capabilities). The resolvers (ResolveMaxJobs, ResolveOutbox, ResolveProtocol, CheckCredentials, MigrateSettings) are exported for a sensor with its own flags or configuration file. pkg/core stays available for anything the kit does not cover; the sections below describe it.

Writing a sensor: you implement executors; the SDK owns queue, slots, leases and reporting

The platform's queue is authoritative (api RFC-030). A sensor only says what it can run; core.CommandPoller does the rest:

poller := core.NewCommandPoller(apiClient, executor, &core.CommandPollerConfig{PollInterval: 30 * time.Second})
poller.SetResourceManager(resource.NewManager(resource.ManagerConfig{
	Cap:       0, // no operator cap: slots follow the resources (up to 64)
	Tools:     []string{"nuclei", "trivy"},
	StateFile: "/var/lib/openctem/tool-costs.json",
	Prober:    &resource.Prober{WorkDir: "/var/lib/openctem"},
}))
poller.SetDoorbell(doorbell)
sensor.SetLoadReporter(poller) // heartbeat: load, resources, capacity, queue, running
go poller.Start(ctx)

An executor that starts processes itself calls core.RecordProcessState(ctx, cmd.ProcessState) after Wait so its CPU time and peak memory teach the cost history (the SDK's exec helpers already do).

Tools: register them, the SDK reports them

The platform does not need to know a sensor's tools: the sensor registers what it runs when it starts, and every heartbeat reports it (api RFC-029 §4.3.1). The platform dispatches by that report, and its administrator can only narrow it.

s := core.NewBaseSensor(cfg, apiClient)
s.AddScanner(myScanner)                 // registered: probed with IsInstalled
executor.SetToolRegistry(s.Tools())     // the executor's scanners and collectors too
s.Tools().Register(core.ToolSpec{       // any other tool, with an optional probe
	Name: "zap", Version: "2.15.0", Capabilities: []string{"dast"},
	Probe: func(ctx context.Context) (bool, string, error) { return zapVersion(ctx) },
	Cost:  &resource.ToolCostHint{Cores: 2, MemBytes: 2 << 30, SecondsPerTarget: 60},
})
s.Tools().AddCapabilities("validate")   // served whatever the tools
s.Tools().Limit(strings.Split(os.Getenv("MY_TOOLS"), ",")...) // optional operator allowlist

• A tool whose probe fails is reported as not installed and gets no jobs. Installed tools report their version.
• Probes are cached for 10 minutes (SetProbeTTL, Refresh).
• Feed the slot sizer the same list: resource.ManagerConfig{Tools: s.Tools().Names(), CostHints: s.Tools().CostHints()}.
• SetCapabilityReporter replaces the registry with your own reporter.

Write a tool

A tool is a manifest plus a run function (pkg/tool); the sensor runs it out of process, admits its targets against the local policy and checks every record it emits. A simple tool is declared with the builder:

var Dotenv = tool.Define("dotenv", "1.0.0").
	Targets("http_service").
	Produces("finding:misconfiguration").
	Params(tool.StringParam("path").Label("Path").Default("/.env").Pattern("^/")).
	Handle(func(ctx tool.Context, job *tool.Job, emit tool.Emit) error {
		for _, t := range job.Targets() {
			// probe t.URL(job.Param("path").String()) with ctx.HTTP()
			_ = emit.Misconfiguration(t, tool.Issue{RuleID: "dotenv-exposed", Title: ".env is readable", Severity: "high"})
			ctx.TargetDone(t)
		}
		return nil
	}).
	MustBuild()

Add it to a sensor with kit.AddTool(Dotenv) (and adapter.Dispatch(Dotenv) at the top of main) and test it with testkit.Run. The design: docs/rfcs/sensor-sdk-v2.md.

A tool outside the sensor binary is a directory with its tool.yaml descriptor and program, scaffolded and checked with the openctem tool CLI (docs/tools/cli.md) and installed in a directory listed in SENSOR_ADAPTER_DIRS. Either way:

• The descriptor's config is the tool's settings schema, in the closed subset of JSON Schema defined by github.com/openctemio/ctis/settings (Params of the builder write it). The platform validates administrators' values with the same package, sends them inside the signed job (settings_layers), and the sensor resolves them against the schema before every task.
• The sensor manifest reports each tool's contract with its full descriptor (core.ToolContract, tool.Manifest.Contract). A tool reported with a valid contract joins the organization's tool catalog on the platform, with no platform change.
• The platform assigns tier and trust: a tool it does not know as built into the released sensor runs as unverified, T2.

The full guide: Writing a tool.

Packages

What the SDK promises, what is stable, what is moving to the sensor, and how it grows without breaking sensors: docs/STABILITY.md.

Examples

See examples/ for complete examples:

• A tool in Python with no SDK, and how to check it with the conformance kit (python-adapter, docs/adapter-protocol.md)
• A complete sensor on pkg/sensorkit (minimal-sensor)
• A custom scanner, adapter, connector and provider (custom-scanner, custom-adapter, custom-connector, custom-provider)
• An integration test against a platform (integration-test)
• CI scanning that reports to OpenCTEM lives in openctemio/ci (GitHub Action, GitLab templates, openctem-ci)

Building

# Run tests
make test        # or: go test ./...

# Lint
make lint

Documentation

• Product documentation: https://docs.openctem.io
• docs/ARCHITECTURE.md: how the SDK's parts fit together
• docs/SECURITY.md: the SDK's security controls
• docs/SETTINGS.md: every sensor setting the SDK reads
• docs/STABILITY.md: stability tiers and versioning
• docs/tools/cli.md: the openctem tool CLI

Contributing

Contributions are welcome: see CONTRIBUTING.md.

Security

Report vulnerabilities privately: see SECURITY.md.

Related Projects

• openctemio/openctem - the platform: API (api/) and web console (web/), formerly openctemio/api and openctemio/ui
• openctemio/sensor - the OpenCTEM sensor (binary openctemio-sensor, image ghcr.io/openctemio/sensor)

License

GNU General Public License v3.0; see LICENSE.