E2 — Vanta Adapter: Test Runbook

Asset: Vanta Adapter (E2) Location: apps/evidence-collector/src/platforms/vanta.ts Owner: SnowOps (SO) Milestone: M4

---

Overview

The Vanta adapter implements EvidenceUpsertApi and pushes compliance evidence to Vanta via its REST API. It is consumed by selectEvidencePlatform("vanta") (E1 factory) and by E5 (scheduled evidence sync).

---

Part A — Offline: automated unit tests

cd apps/evidence-collector
npm ci
npm test -- --testPathPattern="platforms/vanta"

Expected: All tests pass. Tests cover: - listExisting mapping, empty results, auth header - create status mapping (PASS / FAIL / NOT_APPLICABLE), account_id, source_ref - update URL construction + id echo - Platform-level idempotency (create → update on second push) - Non-2xx error propagation

---

Part B — Offline: TypeScript type-check

cd apps/evidence-collector
npm run typecheck

Expected: No type errors.

---

Part C — Live: Vanta API integration (requires Vanta account)

Prerequisites: - Vanta workspace with API access enabled - VANTA_API_KEY and VANTA_ACCOUNT_ID set in the environment

cd apps/evidence-collector
npm run build
node -e "
import('./dist/platforms/factory.js').then(async ({ selectEvidencePlatform }) => {
  const platform = selectEvidencePlatform('vanta', process.env);
  const result = await platform.push({
    framework:  'soc2',
    controlId:  'CC6.1',
    title:      'E2 runbook smoke test',
    status:     'pass',
    observedAt: new Date().toISOString(),
    evidence:   { source: 'runbook-test', nonCompliantResources: 0 },
  });
  console.log('pushed:', JSON.stringify(result));
});
"

Expected: JSON output with { framework, controlId, externalId, updated }. Verify the test result appears in the Vanta dashboard under your integration.

---

Sign-Off Block

Step	Executed by	Date	Result
Part A (unit tests)			⬜
Part B (typecheck)			⬜
Part C (live Vanta)			⬜

Signed off: _____ Date: ___

---

Failure Modes

Failure	Cause	Remediation
Vanta list tests failed: 401	Invalid or expired VANTA_API_KEY	Rotate API token in Vanta Settings → Integrations
platform vanta requires VANTA_ACCOUNT_ID	Missing env var	Set VANTA_ACCOUNT_ID
Vanta create test failed: 404	Account ID not found	Verify account ID in Vanta workspace settings
Network timeout	Vanta API unreachable	Check outbound HTTPS; retry