Vanta

The Vanta integration pushes HarborGuard's current vulnerability findings into Vanta on a 15-minute schedule. Each sync is a state-of-world replace scoped to a single Vanta source: findings still open in HarborGuard appear in Vanta, findings that have been remediated, suppressed, or filtered out disappear from Vanta automatically — there is no manual reconciliation.

What you'll need

Item	Where to find it	Used for
Vanta Private API token	Vanta → Integrations → Private API → generate token	Authenticates HarborGuard against Vanta's API. Treat like a password.
Integration ID	Vanta → your integration's settings (the connector you created for HarborGuard)	Identifies which Vanta connector instance receives the findings
Source ID	Same panel as Integration ID — the source slot under the connector	Scope of the state-of-world replace (see below)

The token must be a Private API token, not the public API key used for read-only embeds.

Connecting

In Vanta, create (or reuse) a private connector for HarborGuard and copy its Integration ID and Source ID.
In HarborGuard, go to Settings → Integrations → Vanta.
Paste the Private API Token, Integration ID, and Source ID.
Leave Enabled checked.
Click Save. The token is encrypted before storage and the plaintext is cleared from the form.
Click Test Connection to verify the token authenticates. A green toast means Vanta accepted the credentials; a red toast surfaces the API's error message verbatim.
(Optional) Click Sync Now to enqueue an immediate sync rather than waiting for the next 15-minute sweep.

Configuration fields

Field	Required	Notes
Private API Token	Yes (first connect)	Leave blank on re-save to keep the existing token. The masked form (`••••<last4>`) is shown in the status panel.
Integration ID	Yes	Vanta's connector identifier; mismatched IDs cause the API to reject the payload at parse time.
Source ID	Yes	The replace scope. Findings in Vanta whose source matches this ID but which are not present in the payload are deleted. Different HarborGuard orgs pushing to the same Source ID will overwrite each other — use one source per HarborGuard org.
Enabled	Yes (default on)	Uncheck to pause sync without deleting the credentials. The integration row remains visible in Settings and audit log; no API calls are made until re-enabled.

How sync works

The cron worker runs every 15 minutes and walks every org with Vanta enabled.
For each org, HarborGuard collects the latest completed scan per image tag, materialises every open (non-resolved) vulnerability, and maps each to a Vanta vulnerability record.
The full set is uploaded in one call against your Source ID. Vanta uses that ID as the replace scope: anything previously pushed under that source but missing from this payload is removed.
The sync result (item count, duration, success/failure, and up to 50 error messages) is written back to the integration's status panel.

After a successful sync, the Vanta Integration card shows:

Status: Connected
Token: masked (••••xxxx)
Last sync: localised timestamp
Last result: Success / Failed with <n> items in <ms> ms

Permissions

Connecting, editing, disconnecting: organization owner or admin only.
Other roles see the card in read-only mode.
The events integration.vanta.connected, integration.vanta.updated, integration.vanta.sync_started, integration.vanta.sync_completed, and integration.vanta.sync_failed are all written to the audit log.

Disabling vs disconnecting

Uncheck Enabled → Save: pauses sync. Token and IDs remain encrypted in storage. Re-enable at any time without re-entering credentials. Useful for audit freezes or maintenance windows.
Disconnect: deletes the encrypted token, Integration ID, and Source ID. The next time you connect, you'll be prompted for all three again. Vanta keeps whatever it last received until you push an empty source from somewhere — disconnecting in HarborGuard does not clear findings on the Vanta side.

Troubleshooting

Symptom	Likely cause
`Test Connection` returns `401 Unauthorized`	Token is for the wrong tenant, was revoked in Vanta, or was generated as a read-only token instead of a Private API token.
`Test Connection` works but `Sync Now` fails with `404`	Integration ID or Source ID does not match the connector the token is scoped to. Re-copy them from the Vanta connector settings panel.
Sync succeeds with `itemsSynced: 0`	No completed scans yet, all images filtered out by suppression/triage rules, or every finding is in a closed state. Trigger a scan and re-sync.
Findings appear in Vanta but get deleted on the next sync	Multiple HarborGuard orgs or environments are pushing to the same Source ID. Each environment must have its own Source ID in Vanta.
`integration_sync_failed` notification keeps firing	Check the `Errors` list in the status panel — that's the verbatim Vanta API response. Persistent failures should be addressed by either fixing credentials or unchecking Enabled until ready.