@cyvest/cyvest-js 3.1.0 → 4.0.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.
@@ -1,86 +1,48 @@
1
1
  // AUTO-GENERATED FROM cyvest.schema.json — DO NOT EDIT
2
2
 
3
3
  /**
4
- * Investigation start time (UTC).
4
+ * Optional human-readable investigation name.
5
5
  */
6
- export type StartedAt = string;
7
- /**
8
- * Global investigation score.
9
- */
10
- export type Score = number;
6
+ export type InvestigationName = string | null;
11
7
  /**
12
8
  * Security level classification for checks, observables, and threat intelligence.
13
9
  *
14
10
  * Levels are ordered from lowest (NONE) to highest (MALICIOUS) severity.
15
11
  */
16
12
  export type Level = "NONE" | "TRUSTED" | "INFO" | "SAFE" | "NOTABLE" | "SUSPICIOUS" | "MALICIOUS";
17
- /**
18
- * Whether the investigation is whitelisted.
19
- */
20
- export type Whitelisted = boolean;
21
- export type Identifier = string;
22
- export type Name = string;
23
13
  export type Justification = string | null;
24
14
  /**
25
15
  * List of whitelist entries applied to this investigation.
26
16
  */
27
17
  export type Whitelists = InvestigationWhitelist[];
28
- export type Type = string;
29
- export type Value = string;
30
- export type Internal = boolean;
31
- export type Whitelisted1 = boolean;
32
- export type Comment = string;
33
- export type Score1 = number;
18
+ export type Actor = string | null;
19
+ export type Reason = string | null;
20
+ export type Tool = string | null;
21
+ export type ObjectType = string | null;
22
+ export type ObjectKey = string | null;
23
+ /**
24
+ * Append-only investigation audit log.
25
+ */
26
+ export type EventLog = AuditEvent[];
34
27
  export type ThreatIntels = string[];
35
- export type TargetKey = string;
36
- export type RelationshipType = string;
37
28
  /**
38
29
  * Direction of a relationship between observables.
39
30
  */
40
31
  export type RelationshipDirection = "outbound" | "inbound" | "bidirectional";
41
32
  export type Relationships = Relationship[];
42
- export type Key = string;
43
33
  /**
44
- * Checks that generated this observable.
34
+ * Checks that currently link to this observable (navigation-only).
45
35
  */
46
- export type GeneratedByChecks = string[];
47
- export type CheckId = string;
48
- export type Scope = string;
49
- export type Description = string;
50
- export type Comment1 = string;
51
- export type Score2 = number;
52
- export type Observables1 = string[];
36
+ export type CheckLinks = string[];
53
37
  /**
54
- * Controls how a check reacts to linked observables.
38
+ * Controls how a Check↔Observable link propagates across merged investigations.
55
39
  */
56
- export type CheckScorePolicy = "auto" | "manual";
57
- export type Key1 = string;
58
- export type Source = string;
59
- export type ObservableKey = string;
60
- export type Comment2 = string;
61
- export type Score3 = number;
40
+ export type PropagationMode = "LOCAL_ONLY" | "GLOBAL";
41
+ export type ObservableLinks = ObservableLink[];
62
42
  export type Taxonomies = {
63
43
  [k: string]: unknown;
64
44
  }[];
65
- export type Key2 = string;
66
- export type Name1 = string;
67
- export type Context = string;
68
- export type Key3 = string;
69
- export type Path = string;
70
- export type Description1 = string;
71
45
  export type Checks1 = string[];
72
- export type Key4 = string;
73
- export type AggregatedScore = number;
74
- export type TotalObservables = number;
75
- export type InternalObservables = number;
76
- export type ExternalObservables = number;
77
- export type WhitelistedObservables = number;
78
- export type TotalChecks = number;
79
- export type AppliedChecks = number;
80
- export type TotalThreatIntel = number;
81
- export type TotalContainers = number;
82
- export type Checks2 = number;
83
- export type Applied = number;
84
46
  /**
85
47
  * Root observable type used during data extraction.
86
48
  */
@@ -101,11 +63,26 @@ export type ScoreMode = "max" | "sum";
101
63
  * schemas matching the actual model_dump() output.
102
64
  */
103
65
  export interface CyvestInvestigation {
104
- started_at: StartedAt;
105
- score: Score;
66
+ /**
67
+ * Stable investigation identity (ULID).
68
+ */
69
+ investigation_id: string;
70
+ investigation_name?: InvestigationName;
71
+ /**
72
+ * Investigation start time (UTC).
73
+ */
74
+ started_at: string;
75
+ /**
76
+ * Global investigation score.
77
+ */
78
+ score: number;
106
79
  level: Level;
107
- whitelisted: Whitelisted;
80
+ /**
81
+ * Whether the investigation is whitelisted.
82
+ */
83
+ whitelisted: boolean;
108
84
  whitelists: Whitelists;
85
+ event_log?: EventLog;
109
86
  observables: Observables;
110
87
  checks: Checks;
111
88
  checks_by_level: ChecksByLevel;
@@ -115,16 +92,38 @@ export interface CyvestInvestigation {
115
92
  stats: StatisticsSchema;
116
93
  stats_checks: StatsChecksSchema;
117
94
  data_extraction: DataExtractionSchema;
95
+ /**
96
+ * Global investigation score formatted as fixed-point x.xx.
97
+ */
98
+ score_display: string;
118
99
  }
119
100
  /**
120
101
  * Represents a whitelist entry on an investigation.
121
102
  */
122
103
  export interface InvestigationWhitelist {
123
- identifier: Identifier;
124
- name: Name;
104
+ identifier: string;
105
+ name: string;
125
106
  justification?: Justification;
126
107
  [k: string]: unknown;
127
108
  }
109
+ /**
110
+ * Centralized audit event for investigation-level changes.
111
+ */
112
+ export interface AuditEvent {
113
+ event_id: string;
114
+ timestamp: string;
115
+ event_type: string;
116
+ actor?: Actor;
117
+ reason?: Reason;
118
+ tool?: Tool;
119
+ object_type?: ObjectType;
120
+ object_key?: ObjectKey;
121
+ details?: Details;
122
+ [k: string]: unknown;
123
+ }
124
+ export interface Details {
125
+ [k: string]: unknown;
126
+ }
128
127
  /**
129
128
  * Observables keyed by their unique key.
130
129
  */
@@ -138,18 +137,19 @@ export interface Observables {
138
137
  * through relationships.
139
138
  */
140
139
  export interface Observable {
141
- type: Type;
142
- value: Value;
143
- internal: Internal;
144
- whitelisted: Whitelisted1;
145
- comment: Comment;
140
+ type: string;
141
+ value: string;
142
+ internal: boolean;
143
+ whitelisted: boolean;
144
+ comment: string;
146
145
  extra: Extra;
147
- score: Score1;
146
+ score: number;
148
147
  level: Level;
149
148
  threat_intels: ThreatIntels;
150
149
  relationships: Relationships;
151
- key: Key;
152
- generated_by_checks: GeneratedByChecks;
150
+ key: string;
151
+ check_links: CheckLinks;
152
+ score_display: string;
153
153
  [k: string]: unknown;
154
154
  }
155
155
  export interface Extra {
@@ -159,8 +159,8 @@ export interface Extra {
159
159
  * Represents a relationship between observables.
160
160
  */
161
161
  export interface Relationship {
162
- target_key: TargetKey;
163
- relationship_type: RelationshipType;
162
+ target_key: string;
163
+ relationship_type: string;
164
164
  direction: RelationshipDirection;
165
165
  [k: string]: unknown;
166
166
  }
@@ -177,21 +177,29 @@ export interface Checks {
177
177
  * and contributes to the overall investigation score.
178
178
  */
179
179
  export interface Check {
180
- check_id: CheckId;
181
- scope: Scope;
182
- description: Description;
183
- comment: Comment1;
180
+ check_id: string;
181
+ scope: string;
182
+ description: string;
183
+ comment: string;
184
184
  extra: Extra1;
185
- score: Score2;
185
+ score: number;
186
186
  level: Level;
187
- observables: Observables1;
188
- score_policy?: CheckScorePolicy;
189
- key: Key1;
187
+ origin_investigation_id: string;
188
+ observable_links: ObservableLinks;
189
+ key: string;
190
+ score_display: string;
190
191
  [k: string]: unknown;
191
192
  }
192
193
  export interface Extra1 {
193
194
  [k: string]: unknown;
194
195
  }
196
+ /**
197
+ * Edge metadata for a Check↔Observable association.
198
+ */
199
+ export interface ObservableLink {
200
+ observable_key: string;
201
+ propagation_mode?: PropagationMode;
202
+ }
195
203
  /**
196
204
  * Check keys organized by level name.
197
205
  */
@@ -211,14 +219,15 @@ export interface ThreatIntels1 {
211
219
  * like VirusTotal, URLScan.io, etc.
212
220
  */
213
221
  export interface ThreatIntel {
214
- source: Source;
215
- observable_key: ObservableKey;
216
- comment: Comment2;
222
+ source: string;
223
+ observable_key: string;
224
+ comment: string;
217
225
  extra: Extra2;
218
- score: Score3;
226
+ score: number;
219
227
  level: Level;
220
228
  taxonomies: Taxonomies;
221
- key: Key2;
229
+ key: string;
230
+ score_display: string;
222
231
  [k: string]: unknown;
223
232
  }
224
233
  export interface Extra2 {
@@ -237,10 +246,10 @@ export interface Enrichments {
237
246
  * context but doesn't directly contribute to scoring.
238
247
  */
239
248
  export interface Enrichment {
240
- name: Name1;
249
+ name: string;
241
250
  data: Data;
242
- context: Context;
243
- key: Key3;
251
+ context: string;
252
+ key: string;
244
253
  [k: string]: unknown;
245
254
  }
246
255
  export interface Data {
@@ -259,12 +268,12 @@ export interface Containers {
259
268
  * with aggregated scores and levels.
260
269
  */
261
270
  export interface Container {
262
- path: Path;
263
- description?: Description1;
271
+ path: string;
272
+ description?: string;
264
273
  checks: Checks1;
265
274
  sub_containers: SubContainers;
266
- key: Key4;
267
- aggregated_score: AggregatedScore;
275
+ key: string;
276
+ aggregated_score: number;
268
277
  aggregated_level: Level;
269
278
  }
270
279
  export interface SubContainers {
@@ -276,21 +285,21 @@ export interface SubContainers {
276
285
  * Mirrors the output of `InvestigationStats.get_summary()`.
277
286
  */
278
287
  export interface StatisticsSchema {
279
- total_observables: TotalObservables;
280
- internal_observables: InternalObservables;
281
- external_observables: ExternalObservables;
282
- whitelisted_observables: WhitelistedObservables;
288
+ total_observables: number;
289
+ internal_observables: number;
290
+ external_observables: number;
291
+ whitelisted_observables: number;
283
292
  observables_by_type?: ObservablesByType;
284
293
  observables_by_level?: ObservablesByLevel;
285
294
  observables_by_type_and_level?: ObservablesByTypeAndLevel;
286
- total_checks: TotalChecks;
287
- applied_checks: AppliedChecks;
295
+ total_checks: number;
296
+ applied_checks: number;
288
297
  checks_by_scope?: ChecksByScope;
289
298
  checks_by_level?: ChecksByLevel1;
290
- total_threat_intel: TotalThreatIntel;
299
+ total_threat_intel: number;
291
300
  threat_intel_by_source?: ThreatIntelBySource;
292
301
  threat_intel_by_level?: ThreatIntelByLevel;
293
- total_containers: TotalContainers;
302
+ total_containers: number;
294
303
  }
295
304
  export interface ObservablesByType {
296
305
  [k: string]: number;
@@ -319,8 +328,8 @@ export interface ThreatIntelByLevel {
319
328
  * Schema for check statistics summary.
320
329
  */
321
330
  export interface StatsChecksSchema {
322
- checks: Checks2;
323
- applied: Applied;
331
+ checks: number;
332
+ applied: number;
324
333
  }
325
334
  /**
326
335
  * Schema for data extraction metadata.
@@ -41,7 +41,11 @@ import {
41
41
  // Test fixture
42
42
  function createTestInvestigation(): CyvestInvestigation {
43
43
  return {
44
+ investigation_id: "01HXYZTESTINVESTIGATION",
45
+ investigation_name: "Test Investigation",
46
+ started_at: "2024-01-01T00:00:00Z",
44
47
  score: 7.5,
48
+ score_display: "7.50",
45
49
  level: "MALICIOUS",
46
50
  whitelisted: false,
47
51
  whitelists: [
@@ -59,8 +63,9 @@ function createTestInvestigation(): CyvestInvestigation {
59
63
  internal: true,
60
64
  whitelisted: false,
61
65
  comment: "",
62
- extra: null,
66
+ extra: {},
63
67
  score: 0,
68
+ score_display: "0.00",
64
69
  level: "INFO",
65
70
  relationships: [
66
71
  {
@@ -70,7 +75,7 @@ function createTestInvestigation(): CyvestInvestigation {
70
75
  },
71
76
  ],
72
77
  threat_intels: [],
73
- generated_by_checks: ["chk:ip_check:network"],
78
+ check_links: ["chk:ip_check:network"],
74
79
  },
75
80
  "obs:ipv4-addr:8.8.8.8": {
76
81
  key: "obs:ipv4-addr:8.8.8.8",
@@ -79,12 +84,13 @@ function createTestInvestigation(): CyvestInvestigation {
79
84
  internal: false,
80
85
  whitelisted: true,
81
86
  comment: "Google DNS",
82
- extra: null,
87
+ extra: {},
83
88
  score: -1,
89
+ score_display: "-1.00",
84
90
  level: "TRUSTED",
85
91
  relationships: [],
86
92
  threat_intels: [],
87
- generated_by_checks: [],
93
+ check_links: [],
88
94
  },
89
95
  "obs:domain-name:example.com": {
90
96
  key: "obs:domain-name:example.com",
@@ -93,12 +99,13 @@ function createTestInvestigation(): CyvestInvestigation {
93
99
  internal: false,
94
100
  whitelisted: false,
95
101
  comment: "",
96
- extra: null,
102
+ extra: {},
97
103
  score: 5,
104
+ score_display: "5.00",
98
105
  level: "MALICIOUS",
99
106
  relationships: [],
100
107
  threat_intels: ["ti:virustotal:obs:domain-name:example.com"],
101
- generated_by_checks: ["chk:domain_check:dns"],
108
+ check_links: ["chk:domain_check:dns"],
102
109
  },
103
110
  "obs:url:http://malware.com/bad": {
104
111
  key: "obs:url:http://malware.com/bad",
@@ -107,12 +114,13 @@ function createTestInvestigation(): CyvestInvestigation {
107
114
  internal: false,
108
115
  whitelisted: false,
109
116
  comment: "",
110
- extra: null,
117
+ extra: {},
111
118
  score: 7.5,
119
+ score_display: "7.50",
112
120
  level: "MALICIOUS",
113
121
  relationships: [],
114
122
  threat_intels: [],
115
- generated_by_checks: [],
123
+ check_links: [],
116
124
  },
117
125
  },
118
126
  checks: {
@@ -123,11 +131,16 @@ function createTestInvestigation(): CyvestInvestigation {
123
131
  scope: "network",
124
132
  description: "IP address check",
125
133
  comment: "",
126
- extra: null,
134
+ extra: {},
127
135
  score: 0,
136
+ score_display: "0.00",
128
137
  level: "INFO",
129
- score_policy: "auto",
130
- observables: ["obs:ipv4-addr:192.168.1.1"],
138
+ origin_investigation_id: "01HXYZTESTINVESTIGATION",
139
+ observable_links: [
140
+ {
141
+ observable_key: "obs:ipv4-addr:192.168.1.1",
142
+ },
143
+ ],
131
144
  },
132
145
  ],
133
146
  dns: [
@@ -137,11 +150,16 @@ function createTestInvestigation(): CyvestInvestigation {
137
150
  scope: "dns",
138
151
  description: "Domain reputation check",
139
152
  comment: "",
140
- extra: null,
153
+ extra: {},
141
154
  score: 5,
155
+ score_display: "5.00",
142
156
  level: "MALICIOUS",
143
- score_policy: "auto",
144
- observables: ["obs:domain-name:example.com"],
157
+ origin_investigation_id: "01HXYZTESTINVESTIGATION",
158
+ observable_links: [
159
+ {
160
+ observable_key: "obs:domain-name:example.com",
161
+ },
162
+ ],
145
163
  },
146
164
  {
147
165
  key: "chk:dns_lookup:dns",
@@ -149,11 +167,12 @@ function createTestInvestigation(): CyvestInvestigation {
149
167
  scope: "dns",
150
168
  description: "DNS lookup",
151
169
  comment: "",
152
- extra: null,
170
+ extra: {},
153
171
  score: 0,
172
+ score_display: "0.00",
154
173
  level: "INFO",
155
- score_policy: "manual",
156
- observables: [],
174
+ origin_investigation_id: "01HXYZTESTINVESTIGATION",
175
+ observable_links: [],
157
176
  },
158
177
  ],
159
178
  },
@@ -167,8 +186,9 @@ function createTestInvestigation(): CyvestInvestigation {
167
186
  source: "virustotal",
168
187
  observable_key: "obs:domain-name:example.com",
169
188
  comment: "",
170
- extra: null,
189
+ extra: {},
171
190
  score: 5,
191
+ score_display: "5.00",
172
192
  level: "MALICIOUS",
173
193
  taxonomies: [{ verdict: "malicious" }],
174
194
  },
@@ -20,7 +20,11 @@ import {
20
20
  // Test fixture with relationships
21
21
  function createGraphTestInvestigation(): CyvestInvestigation {
22
22
  return {
23
+ investigation_id: "01HXYZGRAPHINVESTIGATION",
24
+ investigation_name: "Graph Test Investigation",
25
+ started_at: "2024-01-01T00:00:00Z",
23
26
  score: 5,
27
+ score_display: "5.00",
24
28
  level: "MALICIOUS",
25
29
  whitelisted: false,
26
30
  whitelists: [],
@@ -32,8 +36,9 @@ function createGraphTestInvestigation(): CyvestInvestigation {
32
36
  internal: false,
33
37
  whitelisted: false,
34
38
  comment: "",
35
- extra: null,
39
+ extra: {},
36
40
  score: 0,
41
+ score_display: "0.00",
37
42
  level: "INFO",
38
43
  relationships: [
39
44
  {
@@ -48,7 +53,7 @@ function createGraphTestInvestigation(): CyvestInvestigation {
48
53
  },
49
54
  ],
50
55
  threat_intels: [],
51
- generated_by_checks: [],
56
+ check_links: [],
52
57
  },
53
58
  "obs:email-addr:sender@example.com": {
54
59
  key: "obs:email-addr:sender@example.com",
@@ -57,8 +62,9 @@ function createGraphTestInvestigation(): CyvestInvestigation {
57
62
  internal: false,
58
63
  whitelisted: false,
59
64
  comment: "",
60
- extra: null,
65
+ extra: {},
61
66
  score: 0,
67
+ score_display: "0.00",
62
68
  level: "INFO",
63
69
  relationships: [
64
70
  {
@@ -68,7 +74,7 @@ function createGraphTestInvestigation(): CyvestInvestigation {
68
74
  },
69
75
  ],
70
76
  threat_intels: [],
71
- generated_by_checks: [],
77
+ check_links: [],
72
78
  },
73
79
  "obs:ipv4-addr:192.168.1.1": {
74
80
  key: "obs:ipv4-addr:192.168.1.1",
@@ -77,12 +83,13 @@ function createGraphTestInvestigation(): CyvestInvestigation {
77
83
  internal: true,
78
84
  whitelisted: false,
79
85
  comment: "",
80
- extra: null,
86
+ extra: {},
81
87
  score: 0,
88
+ score_display: "0.00",
82
89
  level: "INFO",
83
90
  relationships: [],
84
91
  threat_intels: [],
85
- generated_by_checks: [],
92
+ check_links: [],
86
93
  },
87
94
  "obs:domain-name:example.com": {
88
95
  key: "obs:domain-name:example.com",
@@ -91,12 +98,13 @@ function createGraphTestInvestigation(): CyvestInvestigation {
91
98
  internal: false,
92
99
  whitelisted: false,
93
100
  comment: "",
94
- extra: null,
101
+ extra: {},
95
102
  score: 5,
103
+ score_display: "5.00",
96
104
  level: "MALICIOUS",
97
105
  relationships: [],
98
106
  threat_intels: [],
99
- generated_by_checks: [],
107
+ check_links: [],
100
108
  },
101
109
  "obs:file-hash:abc123": {
102
110
  key: "obs:file-hash:abc123",
@@ -105,12 +113,13 @@ function createGraphTestInvestigation(): CyvestInvestigation {
105
113
  internal: false,
106
114
  whitelisted: false,
107
115
  comment: "",
108
- extra: null,
116
+ extra: {},
109
117
  score: 3,
118
+ score_display: "3.00",
110
119
  level: "SUSPICIOUS",
111
120
  relationships: [],
112
121
  threat_intels: [],
113
- generated_by_checks: [],
122
+ check_links: [],
114
123
  },
115
124
  },
116
125
  checks: {},
@@ -0,0 +1,8 @@
1
+ import { defineConfig } from "vitest/config";
2
+
3
+ export default defineConfig({
4
+ test: {
5
+ include: ["tests/**/*.{test,spec}.{ts,js,tsx,jsx}"],
6
+ name: "cyvest-js",
7
+ },
8
+ });