> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Package an external security tool behind a uniform contract so OASM can schedule it and collect findings

A **connector** packages one external security tool behind a uniform contract. It has exactly two parts:

* A declarative **`manifest.yaml`** describing the tool: name, capabilities, and the JSON schemas for the inputs and config the operator supplies.
* A Go **Adapter** that adapts the tool's output into the platform's canonical [`Finding`](/connectors/finding) stream.

The same skeleton serves every kind of tool — an in-process library, a CLI wrapper, or a remote API client — because nothing outside the adapter knows which one it is.

<Info>
  This guide covers only the **integration surface** you write: the manifest, the adapter, and the inputs/config plumbing. The SDK owns everything between your adapter and the platform — dialing, registration, the stream, container reuse, and cancellation — so you never touch it.
</Info>

## The two things you write

<CardGroup cols={2}>
  <Card title="manifest.yaml" icon="file-code">
    Declares the connector. Validated at build time — unknown fields and duplicate slugs fail the build.
  </Card>

  <Card title="Adapter" icon="plug">
    One Go type with two methods, `Validate` and `Execute`. This is the only code every connector must write.
  </Card>
</CardGroup>

## SDK packages

Import the SDK from `github.com/oasm-platform/oasm-connectors/sdk`. You only need three packages.

| Package | Import path | What it gives you |
| - | - | - |
| `connector` | `sdk/connector` | The `Adapter` interface, `Finding` type, and `New(adapter)` wrapper. |
| `runtime` | `sdk/runtime` | `New(connector)` and `Run(ctx)` to launch the connector. |
| `env` | `sdk/env` | `LoadInputs()` for `INPUT_*` defaults. |

<Warning>
  Never import `sdk/runtime`, `sdk/transport`, or `sdk/proto` internals into your adapter. The adapter package must stay tool-specific and nothing else.
</Warning>

## Repository layout

Connectors live in a multi-module Go monorepo. Each connector is an independent module that consumes the SDK through a local `replace` directive.

```text theme={null}
.
├── sdk/                      the connector SDK (imported by every connector)
├── <category>/<slug>/        one module per connector
│   ├── manifest.yaml         the connector contract (required)
│   ├── logo.png              optional icon, inlined into manifest.json
│   ├── Dockerfile            build context is the repo root
│   ├── main.go               wiring only
│   └── adapter.go            the tool-specific code
├── manifest.json             generated — never hand-edit
├── go.work                   unifies every module for root-level tooling
└── Taskfile.yml              task runner entry points
```

The category directory groups connectors in the catalog and matches the connector's `capabilities` entry — `vulnerabilities`, `ports_scanner`, or `url_discovery`.

<Info>
  A dependency added for one connector lands only in that connector's `go.mod`. Never promote a tool-specific dependency into the SDK.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/connectors/quickstart">
    Build a minimal connector end to end.
  </Card>

  <Card title="Adapter reference" icon="code" href="/connectors/adapter">
    The `Validate` and `Execute` methods in detail.
  </Card>

  <Card title="manifest.yaml reference" icon="file-code" href="/connectors/manifest">
    Every field the manifest accepts.
  </Card>

  <Card title="Inputs & config" icon="sliders" href="/connectors/inputs-and-config">
    How per-run inputs and the config profile reach your adapter.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.