> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.io/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.

> [!NOTE]
>
> 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.

## The two things you write

> **manifest.yaml**
>
> Declares the connector. Validated at build time — unknown fields and duplicate slugs fail the build.

> **Adapter**
>
> One Go type with two methods, `Validate` and `Execute`. This is the only code every connector must write.

## 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.

## 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`.

> [!NOTE]
>
> A dependency added for one connector lands only in that connector's `go.mod`. Never promote a tool-specific dependency into the SDK.

## Next steps

> **[Quickstart](/connectors/quickstart)**
>
> Build a minimal connector end to end.

> **[Adapter reference](/connectors/adapter)**
>
> The `Validate` and `Execute` methods in detail.

> **[manifest.yaml reference](/connectors/manifest)**
>
> Every field the manifest accepts.

> **[Inputs & config](/connectors/inputs-and-config)**
>
> How per-run inputs and the config profile reach your adapter.


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