Connectors to GRC, privacy, vulnerability and ticket tools

connectors sends MainSDK's evidence and findings to the tools your security and privacy teams already use: GRC, privacy requests, SBOM and VEX, and tickets.

A connector is a driver behind one contract, connector@1. It reads its credential from secrets, writes one audit line per call, and is never in the request path.

connectors:
  grc:     { driver: servicenow-irm, instance: https://acme.service-now.com, auth: secret:SN_TOKEN }
  privacy: { driver: transcend, auth: secret:TRANSCEND_KEY }
  vulns:   { driver: dependency-track, url: https://dt.acme.internal, auth: secret:DT_KEY }
  tickets: { driver: github }

import { connectorsFrom, pushAssure } from "mainsdk/connectors";

const connectors = connectorsFrom(config.connectors, { http, secrets, log });
await pushAssure(connectors.grc, run);   // one control result per failure, evidence attached

connectors:
  driver: servicenow-irm

Quick start

connectors:
  grc:     { driver: servicenow-irm, instance: https://acme.service-now.com, auth: secret:SN_TOKEN }
  privacy: { driver: transcend, auth: secret:TRANSCEND_KEY }
  vulns:   { driver: dependency-track, url: https://dt.acme.internal, auth: secret:DT_KEY }
  tickets: { driver: github }

import { app } from "mainsdk";
import {
  connectorsFrom,
  httpOver,
  pushAssure,
  type AssureRun,
  type ConnectorsConfig,
} from "mainsdk/connectors";

const a = app();
export const connectors = connectorsFrom(a.config.connectors as ConnectorsConfig, {
  http: httpOver(fetch),
  secrets: (name) => a.secrets.get(name),
  log: (entry) => a.log.info("connector call", { ...entry }),
});

export async function push(run: AssureRun) {
  if (connectors.grc) await pushAssure(connectors.grc, run); // one control result per failure, evidence attached
}

mainsdk connectors test      # dry run against each configured connector

Configuration

Each of grc, privacy, vulns and tickets takes the settings of its driver.

What you get

Always:

• Credentials come from secrets, and every call writes one audit line with no credential in it.
• A connector is never in the request path.
• A privacy request is complete only after every driver confirms, with the signed erasure record attached.

Examples

Tickets that close themselves

import type { AssureRun, Connector } from "mainsdk/connectors";
import { syncTickets } from "mainsdk/connectors";

export function closeFixed(tickets: Connector, run: AssureRun, failedLastTime: string[]) {
  return syncTickets(tickets, run, { owner: "web-team", previous: failedLastTime });
}

Run twice, it opens each issue once. A control that passes now gets a comment and its issue is closed.

A privacy request across drivers

import type { Connector, PrivacyStep } from "mainsdk/connectors";
import { processPrivacy } from "mainsdk/connectors";

export function erase(
  privacy: Connector,
  steps: PrivacyStep[], // one per driver: db, email, analytics
  sign: (record: { request: string; type: string; subject: string; drivers: string[] }) => Promise<string>,
) {
  return processPrivacy(privacy, { steps, sign });
}

Errors and checks

mainsdk check has a connectors gate: a literal auth is MAIN-SECRET-0002 with its file, line and column, and an unknown driver is MAIN-CONNECTOR-0001. Each code's cause and fix is in check codes.

Swapping drivers

Change driver and its address; the calls and the audit line stay the same. A new driver must pass the connector@1 conformance suite before it is listed.

Testing

@mainsdk/testing has runConnectorConformance, nine cases every driver must pass: it declares connector@1 and a kind, pushes evidence and findings (repeatably), receives well-formed requests, syncs status with nothing to send, writes nothing on ping, logs every call, takes its credential from secrets, and fails a refused call with a MainError that names the call. Point a connector at a mock behind the HTTP port to test your own flow. See Test your app.

Security and privacy

• A literal token in main.yaml fails mainsdk check with the line it is on.
• The audit line holds the operation, method, path and status, never the credential or the body.
• Running connectors from a developer's machine or CI is free; scheduled pushes from MainSDK Cloud follow the plan rules.

Next

• Connect your tools: the steps, end to end.
• Secrets
• Privacy