@rawdash/connector-drata 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +142 -0
  2. package/dist/index.d.ts +569 -0
  3. package/dist/index.js +653 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +43 -0
package/README.md ADDED
@@ -0,0 +1,142 @@
1
+ <!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
2
+
3
+ # @rawdash/connector-drata
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@rawdash/connector-drata)](https://www.npmjs.com/package/@rawdash/connector-drata)
6
+ [![license](https://img.shields.io/npm/l/@rawdash/connector-drata)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
7
+
8
+ Sync controls, tests, personnel, and test findings from Drata for audit-ready %, failing-test count, training-completion, and open-finding compliance dashboards.
9
+
10
+ ## Install
11
+
12
+ ```sh
13
+ npm install @rawdash/connector-drata
14
+ ```
15
+
16
+ ## Authentication
17
+
18
+ Bearer-token auth with a Drata Public API key. Read access to the resources you sync is sufficient.
19
+
20
+ 1. Sign in to Drata as an admin and open Settings -> Integrations -> Public API.
21
+ 2. Create a new API key; grant it read access to the resources you intend to sync (controls, tests, personnel, findings).
22
+ 3. Copy the generated key. Drata only shows the key once.
23
+ 4. Store the key as a rawdash secret and reference it from the connector config as `apiKey: secret("DRATA_API_KEY")`.
24
+
25
+ ## Configuration
26
+
27
+ | Field | Type | Required | Description |
28
+ | ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
29
+ | `apiKey` | secret | Yes | Drata Public API key. Generated under Settings -> Integrations -> Public API. Treated as a bearer token. Stored as a secret. |
30
+ | `baseUrl` | string | No | Override the Drata Public API base URL. Defaults to "https://public-api.drata.com". Useful for sandbox / region-specific tenants. |
31
+ | `resources` | array | No | Which Drata resources to sync. Omit to sync all of them. The API key only needs read access to the resources listed here. |
32
+ | `findingsLookbackDays` | number | No | How many days of test findings to refresh on each full sync. Defaults to 90. Incremental syncs use the run watermark and ignore this field. |
33
+
34
+ ## Resources
35
+
36
+ - **`drata_control`** _(entity)_ - Drata controls keyed by id. Each control belongs to one or more frameworks (SOC 2, HIPAA, ISO 27001, etc.) and has a roll-up status of PASSING, FAILING, or NEEDS_ATTENTION.
37
+ - Endpoint: `GET /v1/controls`
38
+ - Cursor pagination via cursor / limit. Controls are a full-snapshot resource: a full sync rewrites the scope on first page.
39
+ - `name`: Human-readable control name.
40
+ - `status`: Roll-up status (PASSING, FAILING, NEEDS_ATTENTION, or DEACTIVATED).
41
+ - `framework`: Name of the first framework the control is mapped to (e.g. "SOC 2"). Use the framework dimension for distributions when a control maps to several frameworks.
42
+ - `frameworks`: Comma-separated list of every framework the control is mapped to.
43
+ - `lastEvaluated`: When Drata last evaluated the control (Unix ms).
44
+ - **`drata_test`** _(entity)_ - Drata tests keyed by id. A test is the smallest unit of evaluation in Drata and may be mapped to multiple controls.
45
+ - Endpoint: `GET /v1/tests`
46
+ - Cursor pagination via cursor / limit. Tests are a full-snapshot resource.
47
+ - `name`: Human-readable test name.
48
+ - `status`: Test status (OK, NEEDS_ATTENTION, DEACTIVATED, or IN_PROGRESS).
49
+ - `controlId`: First control id the test is mapped to (a test may be mapped to several controls).
50
+ - `controlCount`: Number of controls the test is mapped to.
51
+ - `evidenceCount`: Number of distinct evidence rows backing the test (counter maintained by Drata).
52
+ - `lastTested`: When Drata last ran the test (Unix ms).
53
+ - **`drata_personnel`** _(entity)_ - Drata personnel records keyed by id. Surfaces employment status, role, training completion, and training-completed timestamp for compliance-training dashboards.
54
+ - Endpoint: `GET /v1/personnel`
55
+ - Cursor pagination via cursor / limit. Personnel is a full-snapshot resource.
56
+ - `email`: Work email address.
57
+ - `name`: Full name ("firstName lastName").
58
+ - `role`: Reported role / job title.
59
+ - `employmentStatus`: Reported employment status (e.g. ACTIVE, ONBOARDING, OFFBOARDED).
60
+ - `trainingStatus`: Reported security-training status (e.g. COMPLETED, IN_PROGRESS, NOT_STARTED, OVERDUE).
61
+ - `trainingCompleted`: When the most recent training was marked completed (Unix ms).
62
+ - `startDate`: Reported employment start date (Unix ms).
63
+ - **`drata_test_finding`** _(event)_ - Test findings (one event per finding row), with severity, the test it came from, and resolved-at when applicable. Useful for open-finding counts and MTTR-to-resolution timeseries.
64
+ - Endpoint: `GET /v1/findings`
65
+ - Cursor pagination via cursor / limit. Full syncs walk back findingsLookbackDays days; incremental syncs use the sync `since` watermark.
66
+ - `findingId`: Drata finding id.
67
+ - `severity`: Finding severity (LOW, MEDIUM, HIGH, CRITICAL).
68
+ - `status`: Finding status (OPEN, RESOLVED, DEFERRED, WONT_FIX).
69
+ - `testId`: Id of the test that produced the finding.
70
+ - `controlId`: First control id the finding is mapped to (via its test).
71
+ - `resolvedAt`: Resolution timestamp (Unix ms) when resolved.
72
+
73
+ ## Example
74
+
75
+ ```ts
76
+ import {
77
+ defineConfig,
78
+ defineDashboard,
79
+ defineMetric,
80
+ secret,
81
+ } from '@rawdash/core';
82
+
83
+ const drata = {
84
+ name: 'drata',
85
+ connectorId: 'drata',
86
+ config: {
87
+ apiKey: secret('DRATA_API_KEY'),
88
+ },
89
+ };
90
+
91
+ export default defineConfig({
92
+ connectors: [drata],
93
+ dashboards: {
94
+ compliance: defineDashboard({
95
+ widgets: {
96
+ failing_controls: {
97
+ kind: 'stat',
98
+ title: 'Failing controls',
99
+ metric: defineMetric({
100
+ connector: drata,
101
+ shape: 'entity',
102
+ entityType: 'drata_control',
103
+ fn: 'count',
104
+ filter: [{ field: 'status', op: 'eq', value: 'FAILING' }],
105
+ }),
106
+ },
107
+ open_findings: {
108
+ kind: 'stat',
109
+ title: 'Open findings',
110
+ metric: defineMetric({
111
+ connector: drata,
112
+ shape: 'event',
113
+ name: 'drata_test_finding',
114
+ fn: 'count',
115
+ filter: [{ field: 'status', op: 'eq', value: 'OPEN' }],
116
+ }),
117
+ },
118
+ },
119
+ }),
120
+ },
121
+ });
122
+ ```
123
+
124
+ ## Rate limits
125
+
126
+ Drata enforces a per-tenant quota and responds with 429 + Retry-After when exceeded; the shared HTTP client honors Retry-After when scheduling the next request.
127
+
128
+ ## Limitations
129
+
130
+ - Only controls, tests, personnel, and test findings are synced. Frameworks, risks, vendors, audits, and document-evidence resources are out of scope.
131
+ - Controls, tests, and personnel are full-snapshot resources: every sync re-reads the whole list and rewrites the entity scope on the first page. Tenants with very large catalogs (10k+ controls/tests) should run the connector less often.
132
+ - Test findings before the configured lookback window (default 90 days) are not refreshed; they remain whatever the most recent sync that did see them wrote.
133
+
134
+ ## Links
135
+
136
+ - [Rawdash docs](https://rawdash.dev/docs/connectors)
137
+ - [Drata API docs](https://developers.drata.com/)
138
+ - [GitHub](https://github.com/rawdash/rawdash)
139
+
140
+ ## License
141
+
142
+ Apache-2.0