Quickstart

This walkthrough adds a connector called example in the vulnerabilities category. Replace vulnerabilities and example with the category and slug you want.

Prerequisites

Go 1.26+
Task 3.x
Docker 20.10+ (to build and run the image)

1. Create the module

The directory is <category>/<slug>.

mkdir -p vulnerabilities/example
cd vulnerabilities/example

Create go.mod requiring the SDK, then point it at the local copy with a replace:

module github.com/oasm-platform/oasm-connectors/vulnerabilities/example

go 1.26

require github.com/oasm-platform/oasm-connectors/sdk v0.0.0

replace github.com/oasm-platform/oasm-connectors/sdk => ../../sdk

GOWORK=off go mod tidy

2. Write `manifest.yaml`

name: Example
slug: example
version: 1.0.0
image: ghcr.io/oasm-platform/connector-example:1.0.0
author: 'you'
pricingTier: [free]
shortDescription: 'Example vulnerability scanner'
description: 'Scans a target for example findings.'
capabilities: [vulnerabilities]
inputsSchema:
  type: object
  required: [target]
  properties:
    target:
      type: string
      format: uri
      title: Scan target
      description: 'Target URL or hostname to scan.'
  additionalProperties: false
configSchema:
  type: object
  additionalProperties: false
  properties:
    severity:
      type: string
      enum: [info, low, medium, high, critical]
      title: Minimum severity
      default: high

See the manifest reference for every field.

3. Write the adapter

adapter.go — the only tool-specific code.

package main

import (
    "context"
    "fmt"
    "os"
    "strings"

    "github.com/oasm-platform/oasm-connectors/sdk/connector"
)

type ExampleAdapter struct{}

// Validate rejects inputs the tool cannot run.
func (a *ExampleAdapter) Validate(_ context.Context, inputs map[string]any) error {
    target, _ := inputs["target"].(string)
    if strings.TrimSpace(target) == "" {
        return fmt.Errorf("fatal: target is required")
    }
    return nil
}

// Execute runs the tool and streams findings to out.
func (a *ExampleAdapter) Execute(ctx context.Context, inputs map[string]any, out chan<- connector.Finding) error {
    target, _ := inputs["target"].(string)
    severity := os.Getenv("OASM_CONFIG") // parse in real connectors

    _ = severity
    for _, raw := range runTool(ctx, target) {
        f := connector.Finding{
            Name:     raw.Name,
            Severity: normalizeSeverity(raw.Severity),
            Host:     target,
        }
        select {
        case out <- f:
        case <-ctx.Done():
            return ctx.Err()
        }
    }
    return nil
}

func normalizeSeverity(s string) string {
    switch strings.ToLower(strings.TrimSpace(s)) {
    case "info", "low", "medium", "high", "critical":
        return strings.ToLower(strings.TrimSpace(s))
    default:
        return "info"
    }
}

See the Adapter reference and Finding reference.

4. Wire `main.go`

main.go only constructs the adapter and starts the runtime. Treat a cancelled context as a clean exit.

package main

import (
    "context"
    "log"

    sdkconn "github.com/oasm-platform/oasm-connectors/sdk/connector"
    "github.com/oasm-platform/oasm-connectors/sdk/runtime"
)

func main() {
    conn := sdkconn.New(&ExampleAdapter{})
    rt := runtime.New(conn)

    log.Println("example connector starting...")
    if err := rt.Run(context.Background()); err != nil && err != context.Canceled {
        log.Fatalf("connector failed: %v", err)
    }
    log.Println("example connector stopped")
}

Everything between runtime.New and Run — dialing, registration, the stream — is the SDK’s job. You do not configure it.

5. Write the `Dockerfile`

The build context is the repo root, so copy sdk/ and the connector directory explicitly. Drop both go.mod/go.sum first so dependency layers cache.

FROM golang:1.26-alpine AS builder
WORKDIR /src
COPY sdk/go.mod sdk/go.sum sdk/
COPY vulnerabilities/example/go.mod vulnerabilities/example/go.sum vulnerabilities/example/
RUN cd vulnerabilities/example && GOWORK=off go mod download
COPY sdk/ sdk/
COPY vulnerabilities/example/ vulnerabilities/example/
RUN cd vulnerabilities/example && CGO_ENABLED=0 GOWORK=off go build -trimpath -o /out/connector .

FROM alpine:3.20
COPY --from=builder /out/connector /usr/local/bin/connector
RUN adduser -D -u 10001 connector
USER 10001
ENTRYPOINT ["/usr/local/bin/connector"]

The image must not expose ports or require a shell.

6. Regenerate and test

task manifest   # regenerate manifest.json
task test       # per-module tests
task vet        # per-module go vet

Get started

Reference

Build & ship

Prerequisites

1. Create the module

2. Write `manifest.yaml`

3. Write the adapter

4. Wire `main.go`

5. Write the `Dockerfile`

6. Regenerate and test

Next steps

Build & test

Inputs & config

​Prerequisites

​1. Create the module

​2. Write manifest.yaml

​3. Write the adapter

​4. Wire main.go

​5. Write the Dockerfile

​6. Regenerate and test

​Next steps

Build & test

Inputs & config

Prerequisites

1. Create the module

2. Write `manifest.yaml`

3. Write the adapter

4. Wire `main.go`

5. Write the `Dockerfile`

6. Regenerate and test

Next steps