0
# Data Types and API Models
1
2
Comprehensive type definitions for API security data including endpoints, traces, alerts, attacks, and platform configuration. These types provide a strongly-typed interface for all Metlo platform interactions.
3
4
## Capabilities
5
6
### API Endpoint Types
7
8
#### API Endpoint
9
10
Core API endpoint representation with security metadata and risk assessment.
11
12
```typescript { .api }
13
interface ApiEndpoint {
14
/** Unique identifier for the endpoint */
15
uuid: string;
16
/** URL path pattern (may include parameters like /users/:id) */
17
path: string;
18
/** HTTP method for the endpoint */
19
method: RestMethod;
20
/** Host domain for the endpoint */
21
host: string;
22
/** Security risk score assessment */
23
riskScore: RiskScore;
24
/** Required resource permissions for access */
25
resourcePermissions: string[];
26
/** Whether authentication was detected on the endpoint */
27
isAuthenticatedDetected: boolean;
28
/** Whether authentication requirement was manually set */
29
isAuthenticatedUserSet: boolean;
30
/** Whether full trace capture is enabled for this endpoint */
31
fullTraceCaptureEnabled: boolean;
32
/** Whether this is a GraphQL endpoint */
33
isGraphQl: boolean;
34
/** Whether the endpoint is publicly accessible */
35
isPublic?: boolean;
36
/** Detected sensitive data classes in endpoint */
37
dataClasses?: string[];
38
/** When the endpoint was first detected */
39
firstDetected?: Date;
40
/** When the endpoint was last active */
41
lastActive?: Date;
42
/** Endpoint owner/team */
43
owner: string;
44
/** Associated OpenAPI specification name */
45
openapiSpecName: string;
46
/** Timestamp when endpoint was created */
47
createdAt: Date;
48
/** Timestamp when endpoint was last updated */
49
updatedAt: Date;
50
}
51
```
52
53
#### Detailed API Endpoint
54
55
Extended endpoint information including related security data and test configurations.
56
57
```typescript { .api }
58
interface ApiEndpointDetailed extends ApiEndpoint {
59
/** Associated OpenAPI specification */
60
openapiSpec: OpenApiSpec;
61
/** Security alerts for this endpoint */
62
alerts: Alert[];
63
/** Recent API traces for this endpoint */
64
traces: ApiTrace[];
65
/** Security tests configured for this endpoint */
66
tests: any[];
67
/** Detected data fields in requests/responses */
68
dataFields: DataField[];
69
/** Global trace capture setting */
70
globalFullTraceCapture?: boolean;
71
/** Whether authentication was manually configured */
72
userSet: boolean;
73
/** GraphQL schema definition */
74
graphQlSchema: string | null;
75
}
76
```
77
78
### API Trace Types
79
80
#### API Trace
81
82
Complete record of an API request and response with security analysis.
83
84
```typescript { .api }
85
interface ApiTrace {
86
/** Unique identifier for the trace */
87
uuid: string;
88
/** URL path of the request */
89
path: string;
90
/** HTTP method used */
91
method: RestMethod;
92
/** Request host */
93
host: string;
94
/** Request headers */
95
requestHeaders: PairObject[];
96
/** Request body content */
97
requestBody: string;
98
/** Response status code */
99
responseStatus: number;
100
/** Response headers */
101
responseHeaders: PairObject[];
102
/** Response body content */
103
responseBody: string;
104
/** Request parameters from URL */
105
requestParameters: PairObject[];
106
/** Traffic metadata */
107
meta: Meta;
108
/** Session authentication metadata */
109
sessionMeta: SessionMeta;
110
/** Whether sensitive data was redacted */
111
redacted: boolean;
112
/** Associated API endpoint UUID */
113
apiEndpointUuid: string;
114
/** Processed security analysis data */
115
processedTraceData?: ProcessedTraceData;
116
/** Original host before any transformations */
117
originalHost?: string;
118
/** Encryption configuration for sensitive data */
119
encryption?: Encryption;
120
/** Type of analysis performed */
121
analysisType?: AnalysisType;
122
/** GraphQL-specific request paths */
123
graphqlPaths?: string[];
124
/** When the trace was captured */
125
createdAt: Date;
126
}
127
```
128
129
#### Queued API Trace
130
131
API trace queued for processing (before UUID assignment).
132
133
```typescript { .api }
134
interface QueuedApiTrace {
135
/** URL path of the request */
136
path: string;
137
/** Request host */
138
host: string;
139
/** HTTP method used */
140
method: RestMethod;
141
/** Request parameters from URL */
142
requestParameters: PairObject[];
143
/** Request headers */
144
requestHeaders: PairObject[];
145
/** Request body content */
146
requestBody: string;
147
/** Response status code */
148
responseStatus: number;
149
/** Response headers */
150
responseHeaders: PairObject[];
151
/** Response body content */
152
responseBody: string;
153
/** Traffic metadata */
154
meta: Meta;
155
/** Session authentication metadata */
156
sessionMeta: SessionMeta;
157
/** Whether sensitive data was redacted */
158
redacted?: boolean;
159
/** Processed security analysis data */
160
processedTraceData?: ProcessedTraceData;
161
/** Original host before any transformations */
162
originalHost?: string;
163
/** Encryption configuration */
164
encryption?: Encryption;
165
/** Analysis type performed */
166
analysisType?: AnalysisType;
167
/** GraphQL-specific paths */
168
graphqlPaths?: string[];
169
/** When the trace was created */
170
createdAt: Date;
171
}
172
```
173
174
### Security Alert Types
175
176
#### Alert
177
178
Security alert with vulnerability details and resolution status.
179
180
```typescript { .api }
181
interface Alert {
182
/** Unique identifier for the alert */
183
uuid: string;
184
/** Type of security vulnerability detected */
185
type: AlertType;
186
/** Risk severity level */
187
riskScore: RiskScore;
188
/** Associated API endpoint UUID */
189
apiEndpointUuid: string;
190
/** Detailed endpoint information */
191
apiEndpoint: {
192
uuid: string;
193
method: RestMethod;
194
host: string;
195
path: string;
196
openapiSpecName: string;
197
openapiSpec: {
198
extension: SpecExtension;
199
minimizedSpecContext: Record<string, MinimizedSpecContext>;
200
};
201
};
202
/** Human-readable alert description */
203
description: string;
204
/** Current alert status */
205
status: Status;
206
/** Resolution message if resolved */
207
resolutionMessage: string;
208
/** Additional alert context data */
209
context: object;
210
/** When the alert was created */
211
createdAt: Date;
212
/** When the alert was last updated */
213
updatedAt: Date;
214
}
215
```
216
217
### Attack Detection Types
218
219
#### Attack
220
221
Detected security attack with metadata and resolution status.
222
223
```typescript { .api }
224
interface Attack {
225
/** Unique identifier for the attack */
226
uuid: string;
227
/** Risk severity level */
228
riskScore: RiskScore;
229
/** Type of attack detected */
230
attackType: AttackType;
231
/** Human-readable attack description */
232
description: string;
233
/** Attack-specific metadata */
234
metadata: AttackMeta;
235
/** When the attack started */
236
startTime: Date;
237
/** When the attack ended */
238
endTime: Date;
239
/** Unique session key for the attacker */
240
uniqueSessionKey: string;
241
/** Source IP address of the attack */
242
sourceIP: string;
243
/** Targeted API endpoint UUID */
244
apiEndpointUuid: string;
245
/** Targeted API endpoint details */
246
apiEndpoint: ApiEndpoint;
247
/** Target host */
248
host: string;
249
/** Whether the attack has been resolved */
250
resolved: boolean;
251
/** Whether the attack is snoozed */
252
snoozed: boolean;
253
/** Number of hours the attack is snoozed */
254
snoozeHours: number;
255
/** When the attack was detected */
256
createdAt: Date;
257
}
258
```
259
260
#### Attack Metadata
261
262
Additional metadata about detected attacks.
263
264
```typescript { .api }
265
interface AttackMeta {
266
/** Average requests per second during attack */
267
averageRPS?: number;
268
/** Current requests per second */
269
currentRPS?: number;
270
}
271
```
272
273
#### Attack Response
274
275
Response structure for attack queries with aggregation data.
276
277
```typescript { .api }
278
interface AttackResponse {
279
/** Count of attacks by type */
280
attackTypeCount: Record<AttackType, number>;
281
/** List of attacks */
282
attacks: Attack[];
283
/** Total number of attacks */
284
totalAttacks: number;
285
/** Total number of affected endpoints */
286
totalEndpoints: number;
287
/** Whether license allows attack detection features */
288
validLicense: boolean;
289
}
290
```
291
292
#### Attack Detail Response
293
294
Detailed attack information with associated traces.
295
296
```typescript { .api }
297
interface AttackDetailResponse {
298
/** Attack details */
299
attack: Attack;
300
/** API traces associated with the attack */
301
traces: ApiTrace[];
302
/** Whether license allows attack detection features */
303
validLicense: boolean;
304
}
305
```
306
307
### Data Field Types
308
309
#### Data Field
310
311
Information about detected sensitive data fields in API requests/responses.
312
313
```typescript { .api }
314
interface DataField {
315
/** Unique identifier for the data field */
316
uuid: string;
317
/** Classified data types (PII categories) */
318
dataClasses: string[];
319
/** JSON path to the data field */
320
dataPath: string;
321
/** Section of request/response containing the field */
322
dataSection: DataSection;
323
/** Data type classification */
324
dataType: DataType;
325
/** Data sensitivity tags */
326
dataTag: DataTag;
327
/** Fields marked as false positives */
328
falsePositives: string[];
329
/** Data classes identified by scanners */
330
scannerIdentified: string[];
331
/** Pattern matches for data classification */
332
matches: Record<string, string[]>;
333
/** Associated API endpoint UUID */
334
apiEndpointUuid: string;
335
/** HTTP status code where field was found */
336
statusCode: number;
337
/** Content type of the response */
338
contentType: string;
339
/** Whether the field can be null */
340
isNullable: boolean;
341
/** Business entity associated with the field */
342
entity: string;
343
/** When the field was first detected */
344
createdAt: Date;
345
/** When the field was last updated */
346
updatedAt: Date;
347
}
348
```
349
350
### Request/Response Types
351
352
#### Request
353
354
HTTP request structure with parsed components.
355
356
```typescript { .api }
357
interface Request {
358
/** Parsed URL components */
359
url: Url;
360
/** Request headers */
361
headers: PairObject[];
362
/** Request body content */
363
body: string;
364
/** HTTP method */
365
method: RestMethod;
366
}
367
```
368
369
#### Response
370
371
HTTP response structure.
372
373
```typescript { .api }
374
interface Response {
375
/** HTTP status code */
376
status: number;
377
/** Response headers */
378
headers: PairObject[];
379
/** Response body content */
380
body: string;
381
}
382
```
383
384
#### URL Structure
385
386
Parsed URL components.
387
388
```typescript { .api }
389
interface Url {
390
/** Host domain */
391
host: string;
392
/** URL path */
393
path: string;
394
/** Query parameters */
395
parameters: PairObject[];
396
}
397
```
398
399
### Metadata Types
400
401
#### Traffic Metadata
402
403
Network traffic metadata for trace analysis.
404
405
```typescript { .api }
406
interface Meta {
407
/** Whether traffic is incoming to the service */
408
incoming: boolean;
409
/** Source IP address */
410
source: string;
411
/** Source port number */
412
sourcePort: string;
413
/** Destination IP address */
414
destination: string;
415
/** Destination port number */
416
destinationPort: string;
417
/** Original source before any proxying */
418
originalSource?: string;
419
}
420
```
421
422
#### Session Metadata
423
424
Authentication and session information.
425
426
```typescript { .api }
427
interface SessionMeta {
428
/** Whether authentication was provided */
429
authenticationProvided: boolean;
430
/** Whether authentication was successful */
431
authenticationSuccessful: boolean;
432
/** Type of authentication used */
433
authType: AuthType;
434
/** Unique session identifier */
435
uniqueSessionKey?: string;
436
/** Authenticated user identifier */
437
user?: string;
438
}
439
```
440
441
### Configuration Types
442
443
#### Authentication Configuration
444
445
Configuration for authentication detection and handling.
446
447
```typescript { .api }
448
interface AuthenticationConfig {
449
/** Host this configuration applies to */
450
host: string;
451
/** Type of authentication */
452
authType: AuthType;
453
/** Header name for authentication (if header-based) */
454
headerKey: string;
455
/** JWT token path for user extraction */
456
jwtUserPath: string;
457
/** Cookie name for session authentication */
458
cookieName: string;
459
}
460
```
461
462
#### Metlo Configuration
463
464
Main platform configuration response.
465
466
```typescript { .api }
467
interface MetloConfigResp {
468
/** Configuration UUID */
469
uuid: string;
470
/** Configuration content as string */
471
configString: string;
472
/** Public key for data encryption */
473
encryptionPublicKey?: string;
474
}
475
```
476
477
#### Update Configuration Parameters
478
479
Parameters for updating Metlo configuration.
480
481
```typescript { .api }
482
interface UpdateMetloConfigParams {
483
/** New configuration content */
484
configString: string;
485
}
486
```
487
488
### Summary and Analytics Types
489
490
#### Platform Summary
491
492
High-level platform statistics and key metrics.
493
494
```typescript { .api }
495
interface Summary {
496
/** Number of high-risk alerts */
497
highRiskAlerts: number;
498
/** Number of new alerts */
499
newAlerts: number;
500
/** Total endpoints being tracked */
501
endpointsTracked: number;
502
/** Number of PII data fields detected */
503
piiDataFields: number;
504
/** Number of unique hosts */
505
hostCount: number;
506
/** PII data type distribution */
507
piiDataTypeCount: Map<string, number>;
508
/** Alert type distribution */
509
alertTypeCount: Map<AlertType, number>;
510
/** Most critical alerts */
511
topAlerts: Alert[];
512
/** Most important endpoints */
513
topEndpoints: ApiEndpointDetailed[];
514
/** API usage statistics */
515
usageStats: UsageStats;
516
/** Number of active connections */
517
numConnections: number;
518
}
519
```
520
521
#### Usage Statistics
522
523
API traffic usage and patterns.
524
525
```typescript { .api }
526
interface UsageStats {
527
/** Daily usage over time */
528
dailyUsage: { day: string; cnt: number }[];
529
/** Request count in last minute */
530
last1MinCnt: number;
531
}
532
```
533
534
#### Usage Data Point
535
536
Individual usage data point.
537
538
```typescript { .api }
539
interface Usage {
540
/** Date for the usage data */
541
date: Date;
542
/** Request count for that date */
543
count: number;
544
}
545
```
546
547
### Aggregation Types
548
549
#### PII Data Aggregation
550
551
Aggregated sensitive data statistics.
552
553
```typescript { .api }
554
interface PIIDataClassAggItem {
555
/** Data classification name */
556
dataClass: string;
557
/** Risk level of the data class */
558
risk: RiskScore;
559
/** Number of instances found */
560
count: number;
561
/** Number of endpoints with this data class */
562
numEndpoints: number;
563
/** Number of hosts with this data class */
564
numHosts: number;
565
}
566
567
interface SensitiveDataSummary {
568
/** PII data type distribution */
569
piiDataTypeCount: Map<string, number>;
570
/** Detailed PII data items */
571
piiItems: PIIDataClassAggItem[];
572
/** Total PII fields detected */
573
totalPIIFields: number;
574
/** Total endpoints with PII */
575
totalEndpoints: number;
576
}
577
```
578
579
#### Vulnerability Aggregation
580
581
Aggregated vulnerability statistics.
582
583
```typescript { .api }
584
interface VulnerabilityAggItem {
585
/** Vulnerability type */
586
type: AlertType;
587
/** Risk level */
588
risk: RiskScore;
589
/** Number of instances */
590
count: number;
591
/** Number of affected endpoints */
592
numEndpoints: number;
593
/** Number of affected hosts */
594
numHosts: number;
595
}
596
597
interface VulnerabilitySummary {
598
/** Vulnerability type distribution */
599
vulnerabilityTypeCount: Map<AlertType, number>;
600
/** Detailed vulnerability items */
601
vulnerabilityItems: VulnerabilityAggItem[];
602
/** Total vulnerabilities detected */
603
totalVulnerabilities: number;
604
/** Total endpoints with vulnerabilities */
605
totalEndpoints: number;
606
}
607
```
608
609
### Utility Types
610
611
#### Key-Value Pair
612
613
Generic name-value pair structure.
614
615
```typescript { .api }
616
interface PairObject {
617
/** Parameter/header name */
618
name: string;
619
/** Parameter/header value */
620
value: string;
621
}
622
```
623
624
#### JSON Value
625
626
Generic JSON value type for flexible data handling.
627
628
```typescript { .api }
629
type JSONValue =
630
| string
631
| number
632
| boolean
633
| { [x: string]: JSONValue }
634
| Array<JSONValue>;
635
```
636
637
#### Host Information
638
639
Host metadata and statistics.
640
641
```typescript { .api }
642
interface HostResponse {
643
/** Host domain name */
644
host: string;
645
/** Number of endpoints on this host */
646
numEndpoints: number;
647
/** Whether the host is publicly accessible */
648
isPublic: boolean;
649
}
650
```
651
652
#### Host Relationship Graph
653
654
Network topology and host relationships.
655
656
```typescript { .api }
657
interface HostGraph {
658
/** Host nodes with endpoint counts */
659
hosts: { [key: string]: { numEndpoints: number } };
660
/** Connections between hosts */
661
edges: {
662
srcHost: string;
663
dstHost: string;
664
numEndpoints: number;
665
}[];
666
}
667
```
668
669
### OpenAPI Specification Types
670
671
#### OpenAPI Specification
672
673
OpenAPI/Swagger specification metadata.
674
675
```typescript { .api }
676
interface OpenApiSpec {
677
/** Specification name */
678
name: string;
679
/** Specification content */
680
spec: string;
681
/** Whether specification was auto-generated */
682
isAutoGenerated: boolean;
683
/** File format extension */
684
extension: SpecExtension;
685
/** Associated hosts */
686
hosts: string[];
687
/** When specification was created */
688
createdAt: Date;
689
/** When specification was last updated */
690
updatedAt: Date;
691
/** When specification content was last updated */
692
specUpdatedAt: Date;
693
}
694
```
695
696
#### Minimized Spec Context
697
698
Context information for OpenAPI specification sections.
699
700
```typescript { .api }
701
interface MinimizedSpecContext {
702
/** Line number in specification */
703
lineNumber: number;
704
/** Minimized specification content */
705
minimizedSpec: string;
706
}
707
```