@deliverd/sdk 0.15.0 → 0.17.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.
- package/README.md +5 -4
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +1728 -0
- package/dist/reports.d.ts +9 -3
- package/dist/reports.d.ts.map +1 -1
- package/dist/reports.js +14 -3
- package/dist/tasks.d.ts +35 -1
- package/dist/tasks.d.ts.map +1 -1
- package/dist/tasks.js +62 -0
- package/dist/types.d.ts +168 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +1 -1
- package/src/released.ts +1728 -0
- package/src/reports.ts +20 -3
- package/src/tasks.ts +74 -0
- package/src/types.ts +213 -0
package/src/reports.ts
CHANGED
|
@@ -10,6 +10,7 @@ import type {
|
|
|
10
10
|
ReportData,
|
|
11
11
|
ScheduleSummary,
|
|
12
12
|
SendResult,
|
|
13
|
+
ShareOptions,
|
|
13
14
|
UpdateReportInput,
|
|
14
15
|
EvidencePack,
|
|
15
16
|
} from "./types.js";
|
|
@@ -122,12 +123,28 @@ export class Reports {
|
|
|
122
123
|
});
|
|
123
124
|
}
|
|
124
125
|
|
|
125
|
-
/**
|
|
126
|
-
|
|
126
|
+
/**
|
|
127
|
+
* Grant people, teams or groups access. Filing is not access; this is.
|
|
128
|
+
*
|
|
129
|
+
* `{ capability: "comment" }` lets them comment as well as read; leave it
|
|
130
|
+
* out for view. A signal in third place, as before options existed, still
|
|
131
|
+
* works.
|
|
132
|
+
*/
|
|
133
|
+
async share(
|
|
134
|
+
idOrSlug: string,
|
|
135
|
+
audience: unknown,
|
|
136
|
+
options?: ShareOptions | AbortSignal,
|
|
137
|
+
signal?: AbortSignal
|
|
138
|
+
): Promise<unknown[]> {
|
|
139
|
+
if (options instanceof AbortSignal) {
|
|
140
|
+
signal = options;
|
|
141
|
+
options = undefined;
|
|
142
|
+
}
|
|
143
|
+
const capability = options?.capability;
|
|
127
144
|
const { granted } = await this.http.request<{ granted: unknown[] }>({
|
|
128
145
|
method: "POST",
|
|
129
146
|
path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
|
|
130
|
-
body: { audience },
|
|
147
|
+
body: capability ? { audience, capability } : { audience },
|
|
131
148
|
signal,
|
|
132
149
|
});
|
|
133
150
|
return granted;
|
package/src/tasks.ts
CHANGED
|
@@ -6,12 +6,16 @@ import type {
|
|
|
6
6
|
ApplySideTaskInput,
|
|
7
7
|
CancelTaskInput,
|
|
8
8
|
CompleteTaskInput,
|
|
9
|
+
ControlThresholds,
|
|
9
10
|
CreateSideTaskInput,
|
|
10
11
|
CreateTaskInput,
|
|
11
12
|
DecisionApproval,
|
|
13
|
+
Governance,
|
|
14
|
+
GovernanceGateCheck,
|
|
12
15
|
LinkTasksInput,
|
|
13
16
|
ListTasksInput,
|
|
14
17
|
RequestDecisionApprovalInput,
|
|
18
|
+
SubmitEvidenceInput,
|
|
15
19
|
TaskContext,
|
|
16
20
|
TaskData,
|
|
17
21
|
TaskFinding,
|
|
@@ -36,6 +40,12 @@ import type {
|
|
|
36
40
|
*
|
|
37
41
|
* Nothing here asks a person anything by itself. A decision is recorded as a
|
|
38
42
|
* suggestion, and `requestDecisionApproval()` is how one is put to somebody.
|
|
43
|
+
*
|
|
44
|
+
* A governed task (Compliance Mode, Business and Enterprise) also has
|
|
45
|
+
* controls, evidence and a gate: `submitEvidence()` records what a run
|
|
46
|
+
* measured, or a tool's own report, and `checkGovernanceGate()` says whether
|
|
47
|
+
* the work may proceed. Thresholds are a person's to set; an agent's key is
|
|
48
|
+
* refused, so whatever submits the results does not decide what passes.
|
|
39
49
|
*/
|
|
40
50
|
|
|
41
51
|
const enc = encodeURIComponent;
|
|
@@ -194,6 +204,26 @@ export class Task {
|
|
|
194
204
|
signal,
|
|
195
205
|
});
|
|
196
206
|
}
|
|
207
|
+
|
|
208
|
+
/** Its governance: controls, their thresholds and scores, evidence, readiness and the gate. */
|
|
209
|
+
governance(signal?: AbortSignal): Promise<Governance> {
|
|
210
|
+
return new Tasks(this.http).governance(this.data.id, signal);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** Record evidence for the controls it speaks to: a link, what a run measured, or a tool's own report. */
|
|
214
|
+
submitEvidence(input: SubmitEvidenceInput, signal?: AbortSignal): Promise<Governance> {
|
|
215
|
+
return new Tasks(this.http).submitEvidence(this.data.id, input, signal);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/** Whether the governed work may proceed. Ask before deploying, sending or acting on the result. */
|
|
219
|
+
checkGovernanceGate(options: { action?: string } = {}, signal?: AbortSignal): Promise<GovernanceGateCheck> {
|
|
220
|
+
return new Tasks(this.http).checkGovernanceGate(this.data.id, options, signal);
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/** Set what a control's scored evidence must meet, or clear it with `null`. A person's key only. */
|
|
224
|
+
setThresholds(control: string, thresholds: ControlThresholds | null, signal?: AbortSignal): Promise<Governance> {
|
|
225
|
+
return new Tasks(this.http).setThresholds(this.data.id, control, thresholds, signal);
|
|
226
|
+
}
|
|
197
227
|
}
|
|
198
228
|
|
|
199
229
|
export class Tasks {
|
|
@@ -309,4 +339,48 @@ export class Tasks {
|
|
|
309
339
|
link(id: string, input: LinkTasksInput, signal?: AbortSignal): Promise<TaskLinkResult> {
|
|
310
340
|
return this.http.request<TaskLinkResult>({ method: "POST", path: `/tasks/${enc(id)}/links`, body: input, signal });
|
|
311
341
|
}
|
|
342
|
+
|
|
343
|
+
/** A governed task's governance: controls, their thresholds and scores, evidence, readiness and the gate. */
|
|
344
|
+
governance(id: string, signal?: AbortSignal): Promise<Governance> {
|
|
345
|
+
return this.http.request<Governance>({ method: "GET", path: `/tasks/${enc(id)}/governance`, signal });
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* Record evidence for a governed task and the controls it speaks to. For an
|
|
350
|
+
* eval or red-team run, send what it measured as `results`, or the tool's
|
|
351
|
+
* own `report` and let the server read it. A control with thresholds is met
|
|
352
|
+
* only when its newest scored evidence meets them. Called on a side task,
|
|
353
|
+
* it belongs to the objective and remembers where it came from.
|
|
354
|
+
*/
|
|
355
|
+
submitEvidence(id: string, input: SubmitEvidenceInput, signal?: AbortSignal): Promise<Governance> {
|
|
356
|
+
return this.http.request<Governance>({ method: "POST", path: `/tasks/${enc(id)}/governance/evidence`, body: input, signal });
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
/**
|
|
360
|
+
* Whether governed work may proceed: `allowed`, what is missing, what else
|
|
361
|
+
* blocks it, and the `scores` of each control with thresholds. With
|
|
362
|
+
* `action` (Enterprise), also whether this agent may take that kind of action.
|
|
363
|
+
*/
|
|
364
|
+
checkGovernanceGate(id: string, options: { action?: string } = {}, signal?: AbortSignal): Promise<GovernanceGateCheck> {
|
|
365
|
+
return this.http.request<GovernanceGateCheck>({
|
|
366
|
+
method: "GET",
|
|
367
|
+
path: `/tasks/${enc(id)}/governance/gate`,
|
|
368
|
+
query: { action: options.action },
|
|
369
|
+
signal,
|
|
370
|
+
});
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* Set what a control's scored evidence must meet, or clear it with `null`.
|
|
375
|
+
* A person's key only: an agent's is refused (`not_permitted`), because
|
|
376
|
+
* whatever submits the results must not also decide what passes.
|
|
377
|
+
*/
|
|
378
|
+
setThresholds(id: string, control: string, thresholds: ControlThresholds | null, signal?: AbortSignal): Promise<Governance> {
|
|
379
|
+
return this.http.request<Governance>({
|
|
380
|
+
method: "PUT",
|
|
381
|
+
path: `/tasks/${enc(id)}/governance/controls/${enc(control)}/thresholds`,
|
|
382
|
+
body: { thresholds },
|
|
383
|
+
signal,
|
|
384
|
+
});
|
|
385
|
+
}
|
|
312
386
|
}
|
package/src/types.ts
CHANGED
|
@@ -612,6 +612,18 @@ export interface SendResult {
|
|
|
612
612
|
alreadyHadAccess: string[];
|
|
613
613
|
}
|
|
614
614
|
|
|
615
|
+
/**
|
|
616
|
+
* What a share lets its audience do. `"view"` is the default.
|
|
617
|
+
*
|
|
618
|
+
* "Can manage", which lets someone share the report on, is not here: it is a
|
|
619
|
+
* person's decision, made in the app, and the API refuses it from a key.
|
|
620
|
+
*/
|
|
621
|
+
export type ShareCapability = "view" | "comment";
|
|
622
|
+
|
|
623
|
+
export interface ShareOptions {
|
|
624
|
+
capability?: ShareCapability;
|
|
625
|
+
}
|
|
626
|
+
|
|
615
627
|
/* ── Schedules ───────────────────────────────────────────────────────────── */
|
|
616
628
|
|
|
617
629
|
/**
|
|
@@ -1510,6 +1522,207 @@ export interface GovernanceProfileInput {
|
|
|
1510
1522
|
jurisdictions?: string[];
|
|
1511
1523
|
}
|
|
1512
1524
|
|
|
1525
|
+
/*
|
|
1526
|
+
* Compliance Mode: a governed task's controls, the evidence that satisfies
|
|
1527
|
+
* them, and the gate. Evidence can carry what a run measured; a control with
|
|
1528
|
+
* thresholds (set by a person) is met only when the newest evidence with
|
|
1529
|
+
* results meets them.
|
|
1530
|
+
*/
|
|
1531
|
+
|
|
1532
|
+
/** What a piece of evidence is. */
|
|
1533
|
+
export type EvidenceType =
|
|
1534
|
+
| "assessment"
|
|
1535
|
+
| "test_result"
|
|
1536
|
+
| "approval"
|
|
1537
|
+
| "decision"
|
|
1538
|
+
| "policy"
|
|
1539
|
+
| "risk_assessment"
|
|
1540
|
+
| "security_review"
|
|
1541
|
+
| "privacy_review"
|
|
1542
|
+
| "data_assessment"
|
|
1543
|
+
| "model_evaluation"
|
|
1544
|
+
| "human_review"
|
|
1545
|
+
| "incident"
|
|
1546
|
+
| "mitigation"
|
|
1547
|
+
| "external_document"
|
|
1548
|
+
| "system_log"
|
|
1549
|
+
| "execution_receipt"
|
|
1550
|
+
| "red_team";
|
|
1551
|
+
|
|
1552
|
+
/** One thing an evaluation, test suite or red-team run measured. */
|
|
1553
|
+
export interface EvidenceResult {
|
|
1554
|
+
/** As the tool names it — `pass_rate`, `attack_success_rate` — so a threshold can name it too. */
|
|
1555
|
+
metric: string;
|
|
1556
|
+
value: number;
|
|
1557
|
+
/** The tool's own verdict on this result, where it gives one. */
|
|
1558
|
+
passed?: boolean;
|
|
1559
|
+
/** How serious a failure of this result is. */
|
|
1560
|
+
severity?: ApprovalRisk;
|
|
1561
|
+
/** A grouping the tool gives it: a red-team plugin, a risk category. */
|
|
1562
|
+
category?: string;
|
|
1563
|
+
dataset?: string;
|
|
1564
|
+
/** The trace or row it can be inspected at. https. */
|
|
1565
|
+
url?: string;
|
|
1566
|
+
}
|
|
1567
|
+
|
|
1568
|
+
/** The run a set of results came from. */
|
|
1569
|
+
export interface EvidenceRun {
|
|
1570
|
+
tool: string;
|
|
1571
|
+
runId?: string;
|
|
1572
|
+
name?: string;
|
|
1573
|
+
/** The run in the tool, for a reviewer to open. https. */
|
|
1574
|
+
url?: string;
|
|
1575
|
+
startedAt?: string;
|
|
1576
|
+
}
|
|
1577
|
+
|
|
1578
|
+
/** The tools whose own report the server reads. `deliverd` is a results file in `EvidenceResult` shape. */
|
|
1579
|
+
export type EvidenceReportFormat = "deliverd" | "promptfoo" | "inspect" | "garak" | "weave" | "braintrust" | "junit";
|
|
1580
|
+
|
|
1581
|
+
export interface SubmitEvidenceInput {
|
|
1582
|
+
type: EvidenceType;
|
|
1583
|
+
title: string;
|
|
1584
|
+
/** What it shows, for a reviewer. */
|
|
1585
|
+
description?: string;
|
|
1586
|
+
/** An https link to it. */
|
|
1587
|
+
url?: string;
|
|
1588
|
+
/** The controls it speaks to; one item may satisfy several. */
|
|
1589
|
+
controls?: string[];
|
|
1590
|
+
/** The finding in this task it rests on. */
|
|
1591
|
+
findingId?: string;
|
|
1592
|
+
/** What was measured. */
|
|
1593
|
+
results?: EvidenceResult[];
|
|
1594
|
+
run?: EvidenceRun;
|
|
1595
|
+
/** A tool's own report, as it wrote it, read by the server into results. Instead of `results`. Up to 4 MB. */
|
|
1596
|
+
report?: EvidenceReport;
|
|
1597
|
+
}
|
|
1598
|
+
|
|
1599
|
+
export interface EvidenceReport {
|
|
1600
|
+
format: EvidenceReportFormat;
|
|
1601
|
+
content: string;
|
|
1602
|
+
}
|
|
1603
|
+
|
|
1604
|
+
export interface ThresholdRule {
|
|
1605
|
+
metric: string;
|
|
1606
|
+
comparator: ">=" | ">" | "<=" | "<" | "==";
|
|
1607
|
+
value: number;
|
|
1608
|
+
}
|
|
1609
|
+
|
|
1610
|
+
/** What a control's scored evidence must meet. Set by a person; an agent's key is refused. */
|
|
1611
|
+
export interface ControlThresholds {
|
|
1612
|
+
rules: ThresholdRule[];
|
|
1613
|
+
/** Fail on any result the tool marked failed at this severity or above. */
|
|
1614
|
+
failOnSeverity: ApprovalRisk | null;
|
|
1615
|
+
}
|
|
1616
|
+
|
|
1617
|
+
/** What the newest scored evidence came to, against a control's thresholds. */
|
|
1618
|
+
export interface ControlScores {
|
|
1619
|
+
passed: boolean;
|
|
1620
|
+
reason: string;
|
|
1621
|
+
evidenceId: string;
|
|
1622
|
+
}
|
|
1623
|
+
|
|
1624
|
+
export interface GovernanceControl {
|
|
1625
|
+
key: string;
|
|
1626
|
+
title: string;
|
|
1627
|
+
family: string;
|
|
1628
|
+
/** How it is satisfied: by the profile, by evidence, or by an approval. */
|
|
1629
|
+
kind: "profile" | "evidence" | "approval";
|
|
1630
|
+
/** The organisation's own control rather than a common one. */
|
|
1631
|
+
custom: boolean;
|
|
1632
|
+
status: "outstanding" | "satisfied" | "waived";
|
|
1633
|
+
required: boolean;
|
|
1634
|
+
/** Pieces of evidence that count towards it. */
|
|
1635
|
+
evidence: number;
|
|
1636
|
+
thresholds: ControlThresholds | null;
|
|
1637
|
+
thresholdsSetBy: string | null;
|
|
1638
|
+
scores: ControlScores | null;
|
|
1639
|
+
/** The framework requirements that ask for it. */
|
|
1640
|
+
sources: GovernanceControlSource[];
|
|
1641
|
+
}
|
|
1642
|
+
|
|
1643
|
+
export interface GovernanceControlSource {
|
|
1644
|
+
framework: string;
|
|
1645
|
+
version: string;
|
|
1646
|
+
ref: string;
|
|
1647
|
+
}
|
|
1648
|
+
|
|
1649
|
+
export interface GovernanceEvidence {
|
|
1650
|
+
id: string;
|
|
1651
|
+
type: EvidenceType;
|
|
1652
|
+
title: string;
|
|
1653
|
+
description: string;
|
|
1654
|
+
url: string | null;
|
|
1655
|
+
controls: string[];
|
|
1656
|
+
results: EvidenceResult[] | null;
|
|
1657
|
+
run: EvidenceRun | null;
|
|
1658
|
+
createdByLabel: string;
|
|
1659
|
+
createdAt: string;
|
|
1660
|
+
}
|
|
1661
|
+
|
|
1662
|
+
export interface GovernanceReadiness {
|
|
1663
|
+
required: number;
|
|
1664
|
+
done: number;
|
|
1665
|
+
missing: string[];
|
|
1666
|
+
/** Controls satisfied or waived, of those required. Never a legal claim. */
|
|
1667
|
+
percent: number;
|
|
1668
|
+
}
|
|
1669
|
+
|
|
1670
|
+
export interface GovernanceBlocker {
|
|
1671
|
+
kind: string;
|
|
1672
|
+
message: string;
|
|
1673
|
+
id?: string;
|
|
1674
|
+
}
|
|
1675
|
+
|
|
1676
|
+
export interface GovernanceGateScore {
|
|
1677
|
+
control: string;
|
|
1678
|
+
passed: boolean;
|
|
1679
|
+
reason: string;
|
|
1680
|
+
evidenceId: string | null;
|
|
1681
|
+
}
|
|
1682
|
+
|
|
1683
|
+
/** Whether governed work may proceed. `allowed: false` names what stands in the way. */
|
|
1684
|
+
export interface GovernanceGateCheck {
|
|
1685
|
+
taskId: string;
|
|
1686
|
+
allowed: boolean;
|
|
1687
|
+
reason: string;
|
|
1688
|
+
missingControls: string[];
|
|
1689
|
+
blockers: GovernanceBlocker[];
|
|
1690
|
+
/** Each required control with thresholds, and why its newest run passed or failed. */
|
|
1691
|
+
scores: GovernanceGateScore[];
|
|
1692
|
+
readiness: GovernanceReadiness;
|
|
1693
|
+
}
|
|
1694
|
+
|
|
1695
|
+
export interface GovernanceFramework {
|
|
1696
|
+
key: string;
|
|
1697
|
+
name: string;
|
|
1698
|
+
version: string;
|
|
1699
|
+
applies: boolean;
|
|
1700
|
+
covered: number;
|
|
1701
|
+
applicable: number;
|
|
1702
|
+
}
|
|
1703
|
+
|
|
1704
|
+
/** A governed task's governance: its profile, controls, evidence, readiness and gate. */
|
|
1705
|
+
export interface Governance {
|
|
1706
|
+
taskId: string;
|
|
1707
|
+
title: string;
|
|
1708
|
+
url: string;
|
|
1709
|
+
profile: GovernanceProfileInput;
|
|
1710
|
+
controls: GovernanceControl[];
|
|
1711
|
+
evidence: GovernanceEvidence[];
|
|
1712
|
+
readiness: GovernanceReadiness;
|
|
1713
|
+
gate: GovernanceGate;
|
|
1714
|
+
frameworks: GovernanceFramework[];
|
|
1715
|
+
/** That this records governance and certifies nothing. */
|
|
1716
|
+
statement: string;
|
|
1717
|
+
}
|
|
1718
|
+
|
|
1719
|
+
export interface GovernanceGate {
|
|
1720
|
+
allowed: boolean;
|
|
1721
|
+
reason: string;
|
|
1722
|
+
missingControls: string[];
|
|
1723
|
+
blockers: GovernanceBlocker[];
|
|
1724
|
+
}
|
|
1725
|
+
|
|
1513
1726
|
export interface ListTasksInput {
|
|
1514
1727
|
/** A status, or `active` for anything not completed or cancelled. */
|
|
1515
1728
|
status?: TaskStatus | "active";
|