trisulrp 3.1.13 → 3.1.14

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,3 +1,7 @@
1
+ /// trp.proto - Trisul Remote Protocol .proto file
2
+ /// TRP : Trisul Remote Protocol is a remote query API that allows
3
+ /// clients to connect and retrieve data from Trisul Hub
4
+
1
5
  // Trisul Remote Protocol (TRP) definition
2
6
  // Based on Google Protocol Buffers
3
7
  // (c) 2012-16, Unleash Networks (http://www.unleashnetworks.com)
@@ -11,174 +15,191 @@ package TRP;
11
15
  //
12
16
  // Basic structures
13
17
  //
18
+ /// Timestamp : Epoch time unix time (seconds since Jan 1 1970)
14
19
  message Timestamp {
15
20
  required int64 tv_sec=1;
16
21
  optional int64 tv_usec=2 [default=0];
17
22
  }
18
23
 
24
+ /// TimeInterval from and to
19
25
  message TimeInterval {
20
- required Timestamp from=1;
21
- required Timestamp to=2;
26
+ required Timestamp from=1; /// start time
27
+ required Timestamp to=2; /// end time
22
28
  }
23
29
 
30
+ /// StatsTuple : a single timeseries vaue (t,v)
24
31
  message StatsTuple {
25
- required Timestamp ts=1;
26
- required int64 val=2;
32
+ required Timestamp ts=1; /// ts
33
+ required int64 val=2; /// value metric
27
34
  }
28
35
 
36
+ /// StatsArray : multiple timeseries values (t, v1, v2, v3...vn)
37
+ /// notice we use ts_tv_sec. Most Trisul data have 1 sec resolution.
29
38
  message StatsArray {
30
- required int64 ts_tv_sec=1;
31
- repeated int64 values=2;
39
+ required int64 ts_tv_sec=1; /// tv.tv_sec
40
+ repeated int64 values=2; /// array of values
32
41
  }
33
42
 
43
+ /// MeterValues : a timeseries (meter_id, stat1, stat2, ... statn)
44
+ /// this is rarely used because StatsArray is available .
34
45
  message MeterValues {
35
- required int32 meter=1;
46
+ required int32 meter=1; /// metric id , eg Hosts:TotalConnections
36
47
  repeated StatsTuple values=2;
37
- optional int64 total=3;
38
- optional int64 seconds=4;
48
+ optional int64 total=3; /// total of all metric values
49
+ optional int64 seconds=4; /// total number of seconds in time series
39
50
  }
40
51
 
52
+
53
+ /// MeterType : information about a particular meter
54
+ ///
41
55
  message MeterInfo {
42
56
 
43
- // from TrisulAPI
44
- enum MeterType
45
- {
46
- VT_INVALID=0;
47
- VT_RATE_COUNTER_WITH_SLIDING_WINDOW=1;// this for top-N type counters
48
- VT_COUNTER=2; // basic counter, stores val in the raw
49
- VT_COUNTER_WITH_SLIDING_WINDOW=3; // use this for top-N type counters
50
- VT_RATE_COUNTER=4; // rate counter stores val/sec
51
- VT_GAUGE=5; // basic gauge
52
- VT_GAUGE_MIN_MAX_AVG=6; // gauge with 3 additional min/avg/max cols (auto)
53
- VT_AUTO=7; // automatic (eg, min/max/avg/stddev/)
54
- VT_RUNNING_COUNTER=8; // running counter, no delta calc
55
- VT_AVERAGE=9; // average of samples, total/sampl uses 32bt|32bit
56
- }
57
+ /// types of meters
58
+ // from TrisulAPI
59
+ enum MeterType
60
+ {
61
+ VT_INVALID=0;
62
+ VT_RATE_COUNTER_WITH_SLIDING_WINDOW=1;/// this for top-N type counters
63
+ VT_COUNTER=2; /// basic counter, stores val in the raw
64
+ VT_COUNTER_WITH_SLIDING_WINDOW=3; /// use this for top-N type counters
65
+ VT_RATE_COUNTER=4; /// rate counter stores val/sec
66
+ VT_GAUGE=5; /// basic gauge
67
+ VT_GAUGE_MIN_MAX_AVG=6; /// gauge with 3 additional min/avg/max cols (auto)
68
+ VT_AUTO=7; /// automatic (eg, min/max/avg/stddev/)
69
+ VT_RUNNING_COUNTER=8; /// running counter, no delta calc
70
+ VT_AVERAGE=9; /// average of samples, total/sampl uses 32bt|32bit
71
+ }
57
72
 
58
73
 
59
74
  required int32 id=1;
60
75
  required MeterType type=2;
61
- required int32 topcount=3;
62
- required string name=4;
63
- optional string description=5;
64
- optional string units=6;
76
+ required int32 topcount=3;
77
+ required string name=4;
78
+ optional string description=5;
79
+ optional string units=6;
65
80
  }
66
81
 
82
+ /// KeyStats - A full time series item (countergroup, key, timeseries)
83
+ ///
67
84
  message KeyStats {
68
- required string counter_group=2;
69
- required KeyT key=3;
70
- repeated MeterValues meters=4;
85
+ required string counter_group=2; /// guid of counter group
86
+ required KeyT key=3; /// key representing an item
87
+ repeated MeterValues meters=4; /// array of timeseries (timeseries-meter0, ts-meter1, ...ts-meter-n)
71
88
  }
72
89
 
73
90
 
74
- //
75
- // Top level objects are named ObjT
76
- // eg KeyT - Key Type, SessionT - Session Type etc.
77
- //
91
+ /// KeyT : Represents a Key
92
+ /// Top level objects are named ObjT
93
+ /// eg KeyT - Key Type, SessionT - Session Type etc.
78
94
  message KeyT {
79
- optional string key=1;
80
- optional string readable=2;
81
- optional string label=3;
82
- optional string description=4;
83
- optional int64 metric=5;
95
+ optional string key=1; /// key in trisul key format eg, C0.A8.01.02 for 192.168.1.2
96
+ optional string readable=2; /// human friendly name
97
+ optional string label=3; /// a user label eg, a hostname or manually assigned name
98
+ optional string description=4; /// description
99
+ optional int64 metric=5; /// optional : a single metric value - relevant to the query used
84
100
  }
85
101
 
86
102
 
103
+ /// CounterGroupT : Represents a counter group
104
+ ///
87
105
  message CounterGroupT {
88
- required string guid=1;
89
- required string name=2;
90
- optional int64 bucket_size=3;
91
- optional TimeInterval time_interval=4;
92
- optional int64 topper_bucket_size=5;
93
- repeated MeterInfo meters=6;
106
+ required string guid=1; /// guid identifying the CG
107
+ required string name=2; /// CG name
108
+ optional int64 bucket_size=3; /// bucketsize for all meters in this group
109
+ optional TimeInterval time_interval=4; /// total time interval available in DB
110
+ optional int64 topper_bucket_size=5; /// topper bucketsize (streaming analytics window)
111
+ repeated MeterInfo meters=6; /// array of meter information (m0, m1, .. mn)
94
112
  }
95
113
 
114
+ /// SessionT : an IP flow
115
+ ///
96
116
  message SessionT {
97
- optional string session_key=1;
98
- required string session_id=2;
99
- optional string user_label=3;
100
- required TimeInterval time_interval=4;
101
- optional int64 state=5;
102
- optional int64 az_bytes=6;
103
- optional int64 za_bytes=7;
104
- optional int64 az_packets=8;
105
- optional int64 za_packets=9;
106
- required KeyT key1A=10;
107
- required KeyT key2A=11;
108
- required KeyT key1Z=12;
109
- required KeyT key2Z=13;
110
- required KeyT protocol=14;
111
- optional KeyT nf_routerid=15;
112
- optional KeyT nf_ifindex_in=16;
113
- optional KeyT nf_ifindex_out=17;
114
- optional string tags=18;
115
- optional int64 az_payload=19;
116
- optional int64 za_payload=20;
117
- optional int64 setup_rtt=21;
118
- optional int64 retransmissions=22;
119
- optional int64 tracker_statval=23;
120
- optional string probe_id=24;
121
- }
122
-
123
-
124
- ////////////////////////////////////
125
- // AlertT
117
+ optional string session_key=1; /// Trisul format eg 06A:C0.A8.01.02:p-0B94_D1.D8.F9.3A:p-0016
118
+ required string session_id=2; /// SID once stored in DB 883:3:883488
119
+ optional string user_label=3; /// any label assigned by user
120
+ required TimeInterval time_interval=4; /// start and end time of flow
121
+ optional int64 state=5; /// flow state (see docs)
122
+ optional int64 az_bytes=6; /// bytes in A>Z direction, see KeyA>KeyZ
123
+ optional int64 za_bytes=7; /// bytes in Z>A direction
124
+ optional int64 az_packets=8; /// pkts in A>Z direction
125
+ optional int64 za_packets=9; /// pkts in Z>A direction
126
+ required KeyT key1A=10; /// basically IP A End
127
+ required KeyT key2A=11; /// Port Z End (can be a string like ICMP00, GRE00, for non TCP/UDP)
128
+ required KeyT key1Z=12; /// IP Z end
129
+ required KeyT key2Z=13; /// Port Z End
130
+ required KeyT protocol=14; /// IP Protocol
131
+ optional KeyT nf_routerid=15; /// Netflow only : Router ID
132
+ optional KeyT nf_ifindex_in=16; /// Netflow only : Interface Index
133
+ optional KeyT nf_ifindex_out=17; /// Netflow only : Interface Index
134
+ optional string tags=18; /// tags assigned using flow taggers
135
+ optional int64 az_payload=19; /// AZ payload - actual content transferred
136
+ optional int64 za_payload=20; /// ZA payload
137
+ optional int64 setup_rtt=21; /// Round Trip Time for setup : Must have TCPReassmbly enabled on Probe
138
+ optional int64 retransmissions=22; /// Retransmissiosn total
139
+ optional int64 tracker_statval=23; /// Metric for flow trackers
140
+ optional string probe_id=24; /// Probe ID generating this flow
141
+ }
142
+
143
+
144
+ /// AlertT : an alert in Trisul
145
+ /// all alert types Threshold Crossing, Flow Tracker, Badfellas, custom alerts use
146
+ /// the same object below
126
147
  message AlertT{
127
- optional int64 sensor_id=1;
128
- required Timestamp time=2;
129
- required string alert_id=3;
130
- optional KeyT source_ip=4;
131
- optional KeyT source_port=5;
132
- optional KeyT destination_ip=6;
133
- optional KeyT destination_port=7;
134
- optional KeyT sigid=8;
135
- optional KeyT classification=9;
136
- optional KeyT priority=10;
137
- optional Timestamp dispatch_time=11;
138
- optional string dispatch_message1=12;
139
- optional string dispatch_message2=13;
140
- optional int64 occurrances=14[default=1];
141
- optional string group_by_key=15;
142
- optional string probe_id=16;
143
- optional string alert_status=17;
144
- optional int64 acknowledge_flag=18;
145
- }
146
-
147
-
148
- ////////////////////////////////////
149
- // ResourceT
148
+ optional int64 sensor_id=1; /// source of alert, usually not used
149
+ required Timestamp time=2; /// timestamp
150
+ required string alert_id=3; /// DB alert ID eg 99:8:98838
151
+ optional KeyT source_ip=4; /// source ip
152
+ optional KeyT source_port=5;
153
+ optional KeyT destination_ip=6;
154
+ optional KeyT destination_port=7;
155
+ optional KeyT sigid=8; /// unique key representing alert type
156
+ optional KeyT classification=9; /// classification (from IDS terminology)
157
+ optional KeyT priority=10; /// priority 1,2,3
158
+ optional Timestamp dispatch_time=11; /// sent time
159
+ optional string dispatch_message1=12; /// a free format string created by generator of alert
160
+ optional string dispatch_message2=13; /// second format
161
+ optional int64 occurrances=14[default=1];/// number of occurranes, used by QueryAlerts for aggregation
162
+ optional string group_by_key=15; /// aggregation key
163
+ optional string probe_id=16; /// probe generating this alert
164
+ optional string alert_status=17; /// FIRE,CLEAR,BLOCK etc
165
+ optional int64 acknowledge_flag=18; /// ACK or NOT
166
+ }
167
+
168
+
169
+ /// ResourceT : represents a "resource" object
170
+ /// examples DNS records, HTTP URLs, TLS Certificates, extracted file hashes, etc
150
171
  message ResourceT {
151
- required Timestamp time=1;
152
- required string resource_id=2;
153
- optional KeyT source_ip=3;
154
- optional KeyT source_port=4;
155
- optional KeyT destination_ip=5;
156
- optional KeyT destination_port=6;
157
- optional string uri=7;
158
- optional string userlabel=8;
159
- optional string probe_id=9;
160
- }
161
-
162
- ////////////////////////////////////
163
- // DocumentT
172
+ required Timestamp time=1; /// time resource was seen
173
+ required string resource_id=2; /// DB id format = 988:0:8388383
174
+ optional KeyT source_ip=3;
175
+ optional KeyT source_port=4;
176
+ optional KeyT destination_ip=5;
177
+ optional KeyT destination_port=6;
178
+ optional string uri=7; /// raw resource - uniform resource id ,dns names, http url, etc
179
+ optional string userlabel=8; /// additional data
180
+ optional string probe_id=9; /// which probe detected this
181
+ }
182
+
183
+ /// DocumentT : a full text document
184
+ /// full HTTP headers, printable TLS certs, etc
164
185
  message DocumentT {
165
- required string dockey=1;
166
- optional string fts_attributes=2;
167
- optional string fullcontent=3;
186
+ required string dockey=1; /// unique id
187
+ optional string fts_attributes=2; /// attibutes used for facets
188
+ optional string fullcontent=3; /// full document text
168
189
 
190
+ /// this document was seen at these time and on this flow
169
191
  message Flow {
170
- required Timestamp time=1;
192
+ required Timestamp time=1;
171
193
  required string key=2;
172
194
  }
173
195
 
174
- repeated Flow flows=4;
175
- optional string probe_id=5;
196
+ repeated Flow flows=4; /// list of flows where this doc was seen
197
+ optional string probe_id=5;
176
198
  }
177
199
 
178
200
 
179
- //
180
- // Enums
181
- //
201
+ /// Enums
202
+ /// Auth Level
182
203
  enum AuthLevel {
183
204
  ADMIN=1;
184
205
  BASIC_USER=2;
@@ -186,42 +207,46 @@ enum AuthLevel {
186
207
  BLOCKED_USER=4;
187
208
  }
188
209
 
210
+ /// Compression: Used by PCAP or other content requests
189
211
  enum CompressionType {
190
212
  UNCOMPRESSED=1;
191
213
  GZIP=2;
192
214
  }
193
215
 
216
+ /// Pcap: format
194
217
  enum PcapFormat {
195
- LIBPCAP=1;
196
- UNSNIFF=2;
197
- LIBPCAPNOFILEHEADER=3;
218
+ LIBPCAP=1; /// normal libpcap format *.pcap
219
+ UNSNIFF=2; ///
220
+ LIBPCAPNOFILEHEADER=3; /// libpcap but without the pcap file header
198
221
  }
199
222
 
200
223
  enum DomainNodeType
201
224
  {
202
- HUB=0;
203
- PROBE=1;
204
- CONFIG=2;
205
- ROUTER=3;
206
- WEB=4;
207
- MONITOR=5;
225
+ HUB=0;
226
+ PROBE=1;
227
+ CONFIG=2;
228
+ ROUTER=3;
229
+ WEB=4;
230
+ MONITOR=5;
208
231
  }
209
232
 
210
233
  enum DomainOperation {
211
- GETNODES=1;
212
- HEARTBEAT=2;
213
- REGISTER=3;
234
+ GETNODES=1;
235
+ HEARTBEAT=2;
236
+ REGISTER=3;
214
237
  }
215
238
 
216
239
  message NameValue {
217
- required string name=1;
218
- optional string value=2;
240
+ required string name=1;
241
+ optional string value=2;
219
242
  }
220
243
 
221
- //
222
- // Top level message is TRP::Message
223
- // - wraps the actual request or response
224
- //
244
+ /// Top level message is TRP::Message
245
+ /// wraps the actual request or response
246
+ ///
247
+ /// You must set trp.command = <cmd> for EACH request in addition to
248
+ /// constructing the actual TRP request message
249
+ ///
225
250
  message Message {
226
251
  enum Command { HELLO_REQUEST=1;
227
252
  HELLO_RESPONSE=2;
@@ -249,12 +274,12 @@ message Message {
249
274
  QUERY_ALERTS_RESPONSE=45;
250
275
  QUERY_RESOURCES_REQUEST=48;
251
276
  QUERY_RESOURCES_RESPONSE=49;
252
- GREP_REQUEST=60;
253
- GREP_RESPONSE=61;
254
- KEYSPACE_REQUEST=70;
255
- KEYSPACE_RESPONSE=71;
256
- TOPPER_TREND_REQUEST=72;
257
- TOPPER_TREND_RESPONSE=73;
277
+ GREP_REQUEST=60;
278
+ GREP_RESPONSE=61;
279
+ KEYSPACE_REQUEST=70;
280
+ KEYSPACE_RESPONSE=71;
281
+ TOPPER_TREND_REQUEST=72;
282
+ TOPPER_TREND_RESPONSE=73;
258
283
  STAB_PUBSUB_CTL=80;
259
284
  QUERY_FTS_REQUEST=90;
260
285
  QUERY_FTS_RESPONSE=91;
@@ -270,24 +295,24 @@ message Message {
270
295
  CONFIG_RESPONSE=104;
271
296
  LOG_REQUEST=105;
272
297
  LOG_RESPONSE=106;
273
- CONTEXT_CREATE_REQUEST=108;
274
- CONTEXT_DELETE_REQUEST=109;
275
- CONTEXT_START_REQUEST=110;
276
- CONTEXT_STOP_REQUEST=111;
277
- CONTEXT_INFO_REQUEST=112;
278
- CONTEXT_INFO_RESPONSE=113;
279
- CONTEXT_CONFIG_REQUEST=114;
280
- CONTEXT_CONFIG_RESPONSE=115;
281
- DOMAIN_REQUEST=116;
282
- DOMAIN_RESPONSE=117;
283
- NODE_CONFIG_REQUEST=118;
284
- NODE_CONFIG_RESPONSE=119;
285
- ASYNC_REQUEST=120;
286
- ASYNC_RESPONSE=121;
287
- FILE_REQUEST=122;
288
- FILE_RESPONSE=123;
289
- SUBSYSTEM_INIT=124; // init msg used to prepare services
290
- SUBSYSTEM_EXIT=125;
298
+ CONTEXT_CREATE_REQUEST=108;
299
+ CONTEXT_DELETE_REQUEST=109;
300
+ CONTEXT_START_REQUEST=110;
301
+ CONTEXT_STOP_REQUEST=111;
302
+ CONTEXT_INFO_REQUEST=112;
303
+ CONTEXT_INFO_RESPONSE=113;
304
+ CONTEXT_CONFIG_REQUEST=114;
305
+ CONTEXT_CONFIG_RESPONSE=115;
306
+ DOMAIN_REQUEST=116;
307
+ DOMAIN_RESPONSE=117;
308
+ NODE_CONFIG_REQUEST=118;
309
+ NODE_CONFIG_RESPONSE=119;
310
+ ASYNC_REQUEST=120;
311
+ ASYNC_RESPONSE=121;
312
+ FILE_REQUEST=122;
313
+ FILE_RESPONSE=123;
314
+ SUBSYSTEM_INIT=124; // init msg used to prepare services
315
+ SUBSYSTEM_EXIT=125;
291
316
 
292
317
  }
293
318
 
@@ -327,32 +352,32 @@ message Message {
327
352
  optional TimeSlicesRequest time_slices_request=62;
328
353
  optional TimeSlicesResponse time_slices_response=63;
329
354
  optional DeleteAlertsRequest delete_alerts_request=64;
330
- optional MetricsSummaryRequest metrics_summary_request=65;
331
- optional MetricsSummaryResponse metrics_summary_response=66;
332
- optional KeySpaceRequest key_space_request=67;
333
- optional KeySpaceResponse key_space_response=68;
334
- optional PcapSlicesRequest pcap_slices_request=69;
335
- optional LogRequest log_request=105;
336
- optional LogResponse log_response=106;
337
- optional ContextCreateRequest context_create_request=108;
338
- optional ContextDeleteRequest context_delete_request=109;
339
- optional ContextStartRequest context_start_request=110;
340
- optional ContextStopRequest context_stop_request=111;
341
- optional ContextConfigRequest context_config_request=112;
342
- optional ContextConfigResponse context_config_response=113;
343
- optional ContextInfoRequest context_info_request=114;
344
- optional ContextInfoResponse context_info_response=115;
345
- optional DomainRequest domain_request=116;
346
- optional DomainResponse domain_response=117;
347
- optional NodeConfigRequest node_config_request=118;
348
- optional NodeConfigResponse node_config_response=119;
349
- optional AsyncRequest async_request=120;
350
- optional AsyncResponse async_response=121;
351
- optional FileRequest file_request=122;
352
- optional FileResponse file_response=123;
353
- optional string destination_node=200; // todo move 2nd
354
- optional string probe_id=201; // todo move 3rd
355
- optional bool run_async=202; // todo move 3rd
355
+ optional MetricsSummaryRequest metrics_summary_request=65;
356
+ optional MetricsSummaryResponse metrics_summary_response=66;
357
+ optional KeySpaceRequest key_space_request=67;
358
+ optional KeySpaceResponse key_space_response=68;
359
+ optional PcapSlicesRequest pcap_slices_request=69;
360
+ optional LogRequest log_request=105;
361
+ optional LogResponse log_response=106;
362
+ optional ContextCreateRequest context_create_request=108;
363
+ optional ContextDeleteRequest context_delete_request=109;
364
+ optional ContextStartRequest context_start_request=110;
365
+ optional ContextStopRequest context_stop_request=111;
366
+ optional ContextConfigRequest context_config_request=112;
367
+ optional ContextConfigResponse context_config_response=113;
368
+ optional ContextInfoRequest context_info_request=114;
369
+ optional ContextInfoResponse context_info_response=115;
370
+ optional DomainRequest domain_request=116;
371
+ optional DomainResponse domain_response=117;
372
+ optional NodeConfigRequest node_config_request=118;
373
+ optional NodeConfigResponse node_config_response=119;
374
+ optional AsyncRequest async_request=120;
375
+ optional AsyncResponse async_response=121;
376
+ optional FileRequest file_request=122;
377
+ optional FileResponse file_response=123;
378
+ optional string destination_node=200; // todo move 2nd
379
+ optional string probe_id=201; // todo move 3rd
380
+ optional bool run_async=202; /// if run_async = true, then you will immediately get a AsynResponse with a token you can poll
356
381
 
357
382
  }
358
383
 
@@ -365,80 +390,75 @@ message Message {
365
390
  // --------------- Messages Section -------------------------//
366
391
  //////////////////////////////////////////////////////////////
367
392
 
368
- ///////////////////////////////
369
- // Hello
393
+ /// Hello Request : use to check connectivity
370
394
  message HelloRequest{
371
- required string station_id=1;
372
- optional string message=2;
395
+ required string station_id=1; /// an id of the query client trying to connect
396
+ optional string message=2; /// a message (will be echoed back in response)
373
397
  }
374
398
 
375
399
  message HelloResponse{
376
- required string station_id=1;
377
- optional string station_id_request=2;
378
- optional string message=3;
379
- optional int64 local_timestamp=4;
400
+ required string station_id=1; /// station id of the query server
401
+ optional string station_id_request=2; /// station id found in the request
402
+ optional string message=3; /// message found in the request
403
+ optional int64 local_timestamp=4; /// local timestamp at server, used to detect drifts
380
404
  }
381
405
 
382
- ///////////////////////////////
383
- // Error
406
+ /// ErrorResponse
407
+ /// All XYZRequest() messages can either generate a XYZResponse() or an ErrorResponse()
408
+ /// you need to handle the error case
384
409
  message ErrorResponse{
385
- required int64 original_command=1;
386
- required int64 error_code=2;
387
- required string error_message=3;
410
+ required int64 original_command=1; /// Command ID of request
411
+ required int64 error_code=2; /// numeric error code
412
+ required string error_message=3; /// error string
388
413
  }
389
414
 
390
- ///////////////////////////////
391
- // OK
415
+ /// OKResponse
416
+ /// many messages return an OKResponse indicating success of operation
392
417
  message OKResponse{
393
- required int64 original_command=1;
394
- optional string message=2;
418
+ required int64 original_command=1; /// command id of request
419
+ optional string message=2; /// success message
395
420
  }
396
421
 
397
422
 
398
- ///////////////////////////////
399
- // CounterItemRequest
423
+ /// CounterItemRequest : Time series history statistics for an item
400
424
  message CounterItemRequest{
401
- required string counter_group=2;
402
- optional int64 meter=3;
403
- required KeyT key=4;
404
- required TimeInterval time_interval=5;
405
- optional int64 volumes_only=6 [default=0];
425
+ required string counter_group=2; /// guid of counter group
426
+ optional int64 meter=3; /// optional meter, default will retrieve all (same cost)
427
+ required KeyT key=4; /// key (can specify key.key, key.label, etc too
428
+ required TimeInterval time_interval=5; /// Time interval for query
429
+ optional int64 volumes_only=6 [default=0]; /// if '1' ; then only retrieves totals for each meter
406
430
  }
407
431
 
408
- ///////////////////////////////
409
- // CounterItemResponse
432
+ /// CounterItemResponse -
410
433
  message CounterItemResponse{
411
- required string counter_group=1;
412
- required KeyT key=2;
413
- optional StatsArray totals=3;
414
- repeated StatsArray stats=4;
434
+ required string counter_group=1; /// guid of CG
435
+ required KeyT key=2; /// key : filled up with readable,label automatically
436
+ optional StatsArray totals=3; /// if volumes_only = 1 in request, this contains totals for each metric
437
+ repeated StatsArray stats=4; /// time series stats - can use to draw charts etc
415
438
  }
416
439
 
417
440
 
418
- ///////////////////////////////
419
- // CounterGroupTopperRequest
441
+ /// CounterGroupTopperRequest - retrieve toppers for a counter group (top-K)
420
442
  message CounterGroupTopperRequest{
421
- required string counter_group=2;
422
- optional int64 meter=3 [default=0];
423
- optional int64 maxitems=4 [default=100];
424
- optional TimeInterval time_interval=5;
425
- optional Timestamp time_instant=6;
426
- optional int64 flags=7;
427
- optional bool resolve_keys=8 [default=true];
443
+ required string counter_group=2; /// guid of CG
444
+ optional int64 meter=3 [default=0]; /// meter; eg to get Top Hosts By Connections use cg=Hosts meter = 6(connections)
445
+ optional int64 maxitems=4 [default=100]; /// number of top items to retreive
446
+ optional TimeInterval time_interval=5; /// time interval
447
+ optional Timestamp time_instant=6; ///
448
+ optional int64 flags=7;
449
+ optional bool resolve_keys=8 [default=true]; /// retrieve labels as set in the response for each key
428
450
  }
429
451
 
430
- ///////////////////////////////
431
- // CounterGroupTopperResponse
452
+ /// CounterGroupTopperResponse
432
453
  message CounterGroupTopperResponse{
433
- required string counter_group=2;
434
- required int64 meter=3;
435
- optional int64 sysgrouptotal=4;
436
- repeated KeyT keys=6;
454
+ required string counter_group=2; /// request cgid
455
+ required int64 meter=3; /// from request
456
+ optional int64 sysgrouptotal=4; /// the metric value for "Others.." after Top-K
457
+ repeated KeyT keys=6; /// topper keys, KeyT.metric contains the top-k value
437
458
  }
438
459
 
439
460
 
440
- ///////////////////////////////////////
441
- // SearchkeysRequest
461
+ /// SearchkeysRequest - search for keys
442
462
  message SearchKeysRequest{
443
463
  required string counter_group=2;
444
464
  optional int64 maxitems=3[default=100];
@@ -449,174 +469,175 @@ message SearchKeysRequest{
449
469
  optional bool get_totals=8[default=false];
450
470
  }
451
471
 
452
- //////////////////////////////////////
453
- // SearchKeysResponse
472
+ /// SearchKeysResponse
454
473
  message SearchKeysResponse{
455
474
  required string counter_group=2;
456
- repeated KeyT keys=3;
475
+ repeated KeyT keys=3;
457
476
  optional int64 total_count=4;
458
477
 
459
478
  }
460
479
 
461
- /////////////////////////////////////
462
- /// CounterGroupInfoRequest
480
+ /// CounterGroupInfoRequest - retrieve information about enabled counter groups
463
481
  message CounterGroupInfoRequest{
464
482
  optional string counter_group=2;
465
- optional bool get_meter_info=3[default=false];
483
+ optional bool get_meter_info=3[default=false];
466
484
  }
467
485
 
468
- ///////////////////////////////////
469
486
  /// CounterGroupInfoResponse
470
487
  message CounterGroupInfoResponse{
471
488
  repeated CounterGroupT group_details=2;
472
489
  }
473
490
 
474
- ///////////////////////////////////
475
- // QuerySessions - any of the fields can be filled
476
- // all the fields filled are treated as AND criteria
491
+ /// QuerySessions - Query flows
492
+ /// fields filled are treated as AND criteria
493
+ /// See SessionT for description of common query fields
477
494
  message QuerySessionsRequest {
478
495
  optional string session_group=2[default="{99A78737-4B41-4387-8F31-8077DB917336}"];
479
496
  optional TimeInterval time_interval=3;
480
497
  optional string key=4;
481
- optional KeyT source_ip=5;
482
- optional KeyT source_port=6;
483
- optional KeyT dest_ip=7;
484
- optional KeyT dest_port=8;
485
- optional KeyT any_ip=9;
486
- optional KeyT any_port=10;
487
- repeated KeyT ip_pair=11; // array of 2 ips
488
- optional KeyT protocol=12;
489
- optional string flowtag=13;
490
- optional KeyT nf_routerid=14;
491
- optional KeyT nf_ifindex_in=15;
492
- optional KeyT nf_ifindex_out=16;
493
- optional string subnet_24=17;
494
- optional string subnet_16=18;
495
- optional int64 maxitems=19[default=100];
496
- optional int64 volume_filter=20[default=0];
497
- optional bool resolve_keys=21[default=true];
498
- optional string outputpath=22;
499
- repeated string idlist=23;
500
- }
501
-
502
- /////////////////////////////////////
503
- // QuerySessionsResponse
498
+ optional KeyT source_ip=5;
499
+ optional KeyT source_port=6;
500
+ optional KeyT dest_ip=7;
501
+ optional KeyT dest_port=8;
502
+ optional KeyT any_ip=9; /// source or dest match
503
+ optional KeyT any_port=10; /// source or dest match
504
+ repeated KeyT ip_pair=11; /// array of 2 ips
505
+ optional KeyT protocol=12;
506
+ optional string flowtag=13; /// string flow tagger text
507
+ optional KeyT nf_routerid=14;
508
+ optional KeyT nf_ifindex_in=15;
509
+ optional KeyT nf_ifindex_out=16;
510
+ optional string subnet_24=17; /// ip /24 subnet matching
511
+ optional string subnet_16=18; /// ip /16 subnet
512
+ optional int64 maxitems=19[default=100]; /// maximum number of matching flows to retrieve
513
+ optional int64 volume_filter=20[default=0]; /// only retrieve flows > this many bytes (a+z)
514
+ optional bool resolve_keys=21[default=true];
515
+ optional string outputpath=22; /// write results to a file (CSV) on trisul-hub (for very large dumps)
516
+ repeated string idlist=23; /// array of flow ids , usually from SessionTracker response
517
+ }
518
+
519
+
520
+ /// QuerySessionsResponse
521
+ /// a list of matching flows
504
522
  message QuerySessionsResponse {
505
- required string session_group=2;
506
- repeated SessionT sessions=3;
507
- optional string outputpath=4;
523
+ required string session_group=2;
524
+ repeated SessionT sessions=3; /// matching flows SessionT objects
525
+ optional string outputpath=4; /// if 'outputpath' set in request, the sessions are here (in CSV format)
508
526
  }
509
527
 
510
- //////////////////////////////////////////////
511
528
  /// UpdatekeysRequest
512
529
  /// Response = OKResponse or ErrorResponse
513
530
  message UpdateKeyRequest{
514
531
  required string counter_group=2;
515
- repeated KeyT keys=4;
532
+ repeated KeyT keys=4; /// key : if you set both key and label, the DB label will be updated
516
533
  }
517
534
 
518
- /////////////////////////////////////
519
- // SessionTrackerRequest
535
+ /// SessionTrackerRequest - query session trackers
536
+ /// session trackers are top-k streaming algorithm for network flows
537
+ /// They are Top Sessions fulfilling a particular preset criterion
520
538
  message SessionTrackerRequest {
521
539
  optional string session_group=2[default="{99A78737-4B41-4387-8F31-8077DB917336}"];
522
- required int64 tracker_id=3 [default=1];
523
- optional int64 maxitems=4 [default=100];
540
+ required int64 tracker_id=3 [default=1]; /// session tracker id
541
+ optional int64 maxitems=4 [default=100];
524
542
  required TimeInterval time_interval=5;
525
543
  optional bool resolve_keys=6 [default=true];
526
544
  }
527
545
 
528
- ///////////////////////////////////
529
- // SessionTrackerResponse
546
+ /// SessionTrackerResponse - results of tracker
547
+ /// returns a list of SessionT for the matching sessions.
548
+ /// Note: the returned list of SessionT only contains keys (in key format) and the
549
+ /// tracker_statval reprsenting the tracker metric. You need to send further QuerySession
550
+ /// request with the session_key to retrive the fullflow
530
551
  message SessionTrackerResponse{
531
552
  required string session_group=2;
532
- repeated SessionT sessions=3;
553
+ repeated SessionT sessions=3; /// contains session_key and tracker_statval
533
554
  optional int64 tracker_id=4;
534
555
  }
535
556
 
536
- ////////////////////////////////////
537
- // QueryAlertsRequest
557
+ /// QueryAlertsRequest - query alerts in system, can group_by (aggregate) any one field
558
+ /// multiple query fields are treated as AND
538
559
  message QueryAlertsRequest {
539
560
  required string alert_group=2;
540
561
  optional TimeInterval time_interval=3;
541
562
  optional int64 maxitems=5 [default=100];
542
- optional KeyT source_ip=6;
543
- optional KeyT source_port=7;
544
- optional KeyT destination_ip=8;
545
- optional KeyT destination_port=9;
546
- optional KeyT sigid=10;
547
- optional KeyT classification=11;
548
- optional KeyT priority=12;
549
- optional string aux_message1=13;
550
- optional string aux_message2=14;
551
- optional string group_by_fieldname=15;
552
- repeated string idlist=16;
553
- optional bool resolve_keys=17[default=true];
554
- optional KeyT any_ip=18;
555
- optional KeyT any_port=19;
556
- repeated KeyT ip_pair=20; // array of 2 ips
557
- optional string message_regex=21; // searech via regex
558
- }
559
-
560
- /////////////////////////////////////
561
- // QueryAlertsResponse
563
+ optional KeyT source_ip=6;
564
+ optional KeyT source_port=7;
565
+ optional KeyT destination_ip=8;
566
+ optional KeyT destination_port=9;
567
+ optional KeyT sigid=10;
568
+ optional KeyT classification=11;
569
+ optional KeyT priority=12;
570
+ optional string aux_message1=13; /// matches dispatchmessage1 in AlertT
571
+ optional string aux_message2=14; /// matches dispatchmessage2 in AlertT
572
+ optional string group_by_fieldname=15; /// can group by any field - group by 'sigid' will group results by sigid
573
+ repeated string idlist=16; /// list of alert ids
574
+ optional bool resolve_keys=17[default=true];
575
+ optional KeyT any_ip=18; /// search by any_ip (source_dest)
576
+ optional KeyT any_port=19; /// search by any_port (source_dest)
577
+ repeated KeyT ip_pair=20; /// array of 2 ips
578
+ optional string message_regex=21; /// searech via regex of the dispatch message
579
+ }
580
+
581
+ /// QueryAlertsResponse - response
582
+ /// if you used group_by_fieldname then AlertT.occurrances would contain the count
562
583
  message QueryAlertsResponse {
563
584
  required string alert_group=2;
564
- repeated AlertT alerts=3;
585
+ repeated AlertT alerts=3; /// array of matching alerts
565
586
  }
566
- ////////////////////////////////////
567
- // QueryResourcesRequest
587
+
588
+
589
+ /// QueryResourcesRequest - resource queries
568
590
  message QueryResourcesRequest {
569
591
  required string resource_group=2;
570
592
  optional TimeInterval time_interval=3;
571
593
  optional int64 maxitems=4 [default=100];
572
- optional KeyT source_ip=5;
573
- optional KeyT source_port=6;
574
- optional KeyT destination_ip=7;
575
- optional KeyT destination_port=8;
594
+ optional KeyT source_ip=5;
595
+ optional KeyT source_port=6;
596
+ optional KeyT destination_ip=7;
597
+ optional KeyT destination_port=8;
576
598
  optional string uri_pattern=9;
577
599
  optional string userlabel_pattern=10;
578
600
  repeated string regex_uri=12; // cant be combined with others
579
- repeated string idlist=13; // resource ID list
580
- optional bool resolve_keys=14 [default=true];
581
- optional KeyT any_port=15;
582
- optional KeyT any_ip=16;
583
- repeated KeyT ip_pair=17; // array of 2 ips
601
+ repeated string idlist=13; // resource ID list
602
+ optional bool resolve_keys=14 [default=true];
603
+ optional KeyT any_port=15;
604
+ optional KeyT any_ip=16;
605
+ repeated KeyT ip_pair=17; // array of 2 ips
584
606
  }
585
607
 
586
- /////////////////////////////////////
587
- // QueryResourceResponse
608
+ /// QueryResourceResponse
588
609
  message QueryResourcesResponse {
589
- required string resource_group=2;
590
- repeated ResourceT resources=3;
610
+ required string resource_group=2;
611
+ repeated ResourceT resources=3;
591
612
  }
592
613
 
593
614
 
594
615
 
595
- ////////////////////////////////////
596
- // KeySpaceRequest
616
+ /// KeySpaceRequest - search hits in Key Space
617
+ /// for example you can search the key space 10.0.0.0 to 11.0.0.0 to get all IP
618
+ /// seen in that range
597
619
  message KeySpaceRequest {
598
620
  required string counter_group=2;
599
621
  required TimeInterval time_interval=3;
600
622
  optional int64 maxitems=4 [default=100];
601
623
 
602
- message KeySpace {
603
- required KeyT from_key=1;
604
- required KeyT to_key=2;
605
- }
624
+ message KeySpace {
625
+ required KeyT from_key=1; /// from key representing start of keyspace
626
+ required KeyT to_key=2; /// end of key space
627
+ }
606
628
 
607
- repeated KeySpace spaces=5;
629
+ repeated KeySpace spaces=5;
608
630
  optional bool resolve_keys=6[default=true];
609
631
  }
610
632
 
611
- /////////////////////////////////////
612
- // KeySpaceResponse
633
+ /// KeySpaceResponse
613
634
  message KeySpaceResponse {
614
635
  optional string counter_group=2;
615
- repeated KeyT hits=3;
636
+ repeated KeyT hits=3; /// array of keys in the requested space
616
637
  }
617
638
 
618
- ///////////////////////////////
619
- // TopperTrendRequest
639
+ /// TopperTrendRequest - raw top-K at each topper snapshot interval
640
+ /// can use this to see "Top apps over 1 Week"
620
641
  message TopperTrendRequest {
621
642
  required string counter_group=2;
622
643
  optional int64 meter=3 [default=0];
@@ -624,53 +645,50 @@ message TopperTrendRequest {
624
645
  optional TimeInterval time_interval=5;
625
646
  }
626
647
 
627
- ///////////////////////////////
628
- // TopperTrendResponse
648
+ /// TopperTrendResponse
629
649
  message TopperTrendResponse {
630
650
  required string counter_group=2;
631
- required int64 meter=3;
632
- repeated KeyStats keytrends=4;
651
+ required int64 meter=3;
652
+ repeated KeyStats keytrends=4; /// timeseries - ts, (array of key stats) for each snapshot interval
633
653
  }
634
654
 
635
655
 
636
656
 
637
- ///////////////////////////////////
638
- // Subscribe - add a subcription to the Real Time channel
657
+ /// Subscribe - add a subcription to the Real Time channel
639
658
  message SubscribeCtl {
640
659
 
641
- // from TrisulAPI
642
- enum StabberType
643
- {
644
- ST_COUNTER_ITEM=0;
645
- ST_ALERT=1;
646
- ST_FLOW=2;
647
- ST_TOPPER=3;
648
- }
660
+ // from TrisulAPI
661
+ enum StabberType
662
+ {
663
+ ST_COUNTER_ITEM=0;
664
+ ST_ALERT=1;
665
+ ST_FLOW=2;
666
+ ST_TOPPER=3;
667
+ }
649
668
 
650
- enum CtlType
651
- {
652
- CT_SUBSCRIBE=0;
653
- CT_UNSUBSCRIBE=1;
654
- }
669
+ enum CtlType
670
+ {
671
+ CT_SUBSCRIBE=0;
672
+ CT_UNSUBSCRIBE=1;
673
+ }
655
674
 
656
- required string context_name=1;
657
- required CtlType ctl=2;
658
- required StabberType type=3;
659
- optional string guid=4;
660
- optional string key=5;
661
- optional int64 meterid=6;
675
+ required string context_name=1;
676
+ required CtlType ctl=2;
677
+ required StabberType type=3;
678
+ optional string guid=4;
679
+ optional string key=5;
680
+ optional int64 meterid=6;
662
681
  }
663
682
 
664
683
 
665
684
 
666
- // FTS
667
- // query to return docs, docids, and flows based on keyword search
668
- //
669
-
685
+ /// FTS
686
+ /// query to return docs, docids, and flows based on keyword search
687
+ ///
670
688
  message QueryFTSRequest {
671
689
 
672
690
  required TimeInterval time_interval=2;
673
- required string fts_group=3;
691
+ required string fts_group=3;
674
692
  required string keywords=4;
675
693
  optional int64 maxitems=5[default=100];
676
694
  }
@@ -678,74 +696,71 @@ message QueryFTSRequest {
678
696
 
679
697
  message QueryFTSResponse {
680
698
 
681
- required string fts_group=2;
682
- repeated DocumentT documents=3;
699
+ required string fts_group=2;
700
+ repeated DocumentT documents=3;
683
701
 
684
702
  }
685
703
 
686
704
 
687
- // Timeslices
688
- //
689
- // get the METERS METASLICE info
690
- // .. response = TimeSlicesResponse
691
-
705
+ /// Timeslices - retrieves the backend timeslice details
706
+ ///
707
+ /// get the METERS METASLICE info
708
+ /// .. response = TimeSlicesResponse
692
709
  message TimeSlicesRequest {
693
- optional bool get_disk_usage=1[default=false];
694
- optional bool get_all_engines=2[default=false];
695
- optional bool get_total_window=3[default=false];
710
+ optional bool get_disk_usage=1[default=false];
711
+ optional bool get_all_engines=2[default=false];
712
+ optional bool get_total_window=3[default=false];
696
713
  }
697
714
 
698
- // .. response = TimeSlicesResponse
699
- // get the PCAP METASLICE based info
715
+ /// .. response = TimeSlicesResponse
716
+ /// get the PCAP METASLICE based info
700
717
  message PcapSlicesRequest {
701
- required string context_name=1;
702
- optional bool get_total_window=2[default=false];
718
+ required string context_name=1;
719
+ optional bool get_total_window=2[default=false];
703
720
  }
704
721
 
705
722
  message TimeSlicesResponse {
706
- message SliceT
707
- {
708
- required TimeInterval time_interval=1;
709
- optional string name=2;
710
- optional string status=3;
711
- optional int64 disk_size=4;
712
- optional string path=5;
713
- optional bool available=6;
714
- };
715
-
716
- repeated SliceT slices=1;
723
+ message SliceT
724
+ {
725
+ required TimeInterval time_interval=1;
726
+ optional string name=2;
727
+ optional string status=3;
728
+ optional int64 disk_size=4;
729
+ optional string path=5;
730
+ optional bool available=6;
731
+ };
732
+
733
+ repeated SliceT slices=1;
717
734
  optional TimeInterval total_window=2;
718
- optional string context_name=3;
735
+ optional string context_name=3;
719
736
  }
720
737
 
721
738
 
722
- // DeleteAlerts
723
- // - very limited exception to Trisul rule of not having delete options
739
+ /// DeleteAlerts
740
+ /// - very limited exception to Trisul rule of not having delete options
724
741
  message DeleteAlertsRequest {
725
742
  required string alert_group=2;
726
743
  required TimeInterval time_interval=3;
727
- optional KeyT source_ip=6;
728
- optional KeyT source_port=7;
729
- optional KeyT destination_ip=8;
730
- optional KeyT destination_port=9;
731
- optional KeyT sigid=10;
732
- optional KeyT classification=11;
733
- optional KeyT priority=12;
734
- optional KeyT any_ip=18;
735
- optional KeyT any_port=19;
736
- optional string message_regex=21; // delete using regex
744
+ optional KeyT source_ip=6;
745
+ optional KeyT source_port=7;
746
+ optional KeyT destination_ip=8;
747
+ optional KeyT destination_port=9;
748
+ optional KeyT sigid=10;
749
+ optional KeyT classification=11;
750
+ optional KeyT priority=12;
751
+ optional KeyT any_ip=18;
752
+ optional KeyT any_port=19;
753
+ optional string message_regex=21; /// delete using regex
737
754
  }
738
755
 
739
- //////////////////////////////////
740
- // MetricsSummaryRequest
756
+ /// MetricsSummaryRequest - used to retrieve DB stats
741
757
  message MetricsSummaryRequest{
742
758
  optional TimeInterval time_interval=1;
743
759
  required string metric_name=2;
744
- optional bool totals_only=3[default=true];
760
+ optional bool totals_only=3[default=true];
745
761
  }
746
762
 
747
- //////////////////////////////////
748
- // MetricsSummaryResponse
763
+ /// MetricsSummaryResponse
749
764
  message MetricsSummaryResponse {
750
765
  required string metric_name=2;
751
766
  repeated StatsTuple vals=3;
@@ -753,265 +768,267 @@ message MetricsSummaryResponse {
753
768
 
754
769
 
755
770
 
756
- //////////////////////////////////
757
- // LogRequest - want log file
771
+ /// LogRequest - get log file from a domain node
758
772
  message LogRequest {
759
773
 
760
774
  required string context_name=1;
761
775
  required string log_type=2;
762
776
  optional string regex_filter=4;
763
777
  optional int64 maxlines=5[default=1000];
764
- optional string continue_logfilename=6;
765
- optional int64 continue_seekpos=7;
766
- optional bool latest_run_only=8[default=false];
778
+ optional string continue_logfilename=6;
779
+ optional int64 continue_seekpos=7;
780
+ optional bool latest_run_only=8[default=false];
767
781
  }
768
782
 
769
783
 
770
784
  message LogResponse {
771
785
 
772
786
  required string context_name=1;
773
- optional string logfilename=6;
774
- optional int64 seekpos=7;
775
- repeated string log_lines=8; // compressed gz
787
+ optional string logfilename=6;
788
+ optional int64 seekpos=7;
789
+ repeated string log_lines=8; /// compressed gz
776
790
  }
777
791
 
778
792
 
779
- // messages to routerX backend
793
+ /// messages to routerX backend
780
794
  message DomainRequest {
781
- required DomainOperation cmd=1;
782
- optional string station_id=2;
783
- optional string params=3;
784
- optional DomainNodeType nodetype=4;
795
+ required DomainOperation cmd=1;
796
+ optional string station_id=2;
797
+ optional string params=3;
798
+ optional DomainNodeType nodetype=4;
785
799
  }
786
800
 
787
801
  message DomainResponse {
788
802
 
789
803
 
790
- message Node {
804
+ message Node {
791
805
 
792
- required string id=1;
793
- required DomainNodeType nodetype=2;
794
- optional string station_id=3;
795
- optional string extra_info=4;
796
- optional Timestamp register_time=5;
797
- optional Timestamp heartbeat_time=6;
806
+ required string id=1;
807
+ required DomainNodeType nodetype=2;
808
+ optional string station_id=3;
809
+ optional string extra_info=4;
810
+ optional Timestamp register_time=5;
811
+ optional Timestamp heartbeat_time=6;
798
812
 
799
- }
813
+ }
800
814
 
801
- required DomainOperation cmd=1;
802
- repeated Node nodes=2;
803
- optional string req_params=3;
804
- optional string params=4;
805
- optional bool need_reconnect=5[default=false];
815
+ required DomainOperation cmd=1;
816
+ repeated Node nodes=2;
817
+ optional string req_params=3;
818
+ optional string params=4;
819
+ optional bool need_reconnect=5[default=false];
806
820
  }
807
821
 
808
822
 
809
823
  message NodeConfigRequest {
810
- optional string message=1;
824
+ optional string message=1;
811
825
 
812
- message IntelFeed {
813
- required string guid=1; // identifying feed group (eg Geo, Badfellas)
814
- optional string name=2; // name
815
- optional string download_rules=3; // xml file with feed update instructions
816
- repeated string uri=4; // individual files in config//.. for FileRequest download
817
- }
826
+ message IntelFeed {
827
+ required string guid=1; /// identifying feed group (eg Geo, Badfellas)
828
+ optional string name=2; /// name
829
+ optional string download_rules=3; /// xml file with feed update instructions
830
+ repeated string uri=4; /// individual files in config//.. for FileRequest download
831
+ }
818
832
 
819
- optional IntelFeed add_feed=2;
820
- optional IntelFeed process_new_feed=3;
821
- optional bool get_all_nodes=4[default=true];
822
- repeated NameValue query_config=5;
833
+ optional IntelFeed add_feed=2;
834
+ optional IntelFeed process_new_feed=3;
835
+ optional bool get_all_nodes=4[default=true];
836
+ repeated NameValue query_config=5;
823
837
 
824
838
  }
825
839
 
826
840
  message NodeConfigResponse {
827
841
 
828
- message Node {
829
- required string id=1;
830
- required DomainNodeType nodetype=2;
831
- required string description=3;
832
- required string public_key=4;
833
- }
842
+ message Node {
843
+ required string id=1;
844
+ required DomainNodeType nodetype=2;
845
+ required string description=3;
846
+ required string public_key=4;
847
+ }
834
848
 
835
- repeated Node domains=1;
836
- repeated Node hubs=2;
837
- repeated Node probes=3;
838
- repeated string feeds=4;
839
- repeated NameValue config_values=5;
849
+ repeated Node domains=1;
850
+ repeated Node hubs=2;
851
+ repeated Node probes=3;
852
+ repeated string feeds=4;
853
+ repeated NameValue config_values=5;
840
854
  }
841
855
 
842
856
 
843
- //////////////////////////////////
844
- // ContextRequest - Context methods
845
- // response Ok or Error, follow up with ContextInfo to print details
846
- //
857
+ /// ContextRequest - Context methods
858
+ /// response Ok or Error, follow up with ContextInfo to print details
859
+ ///
847
860
  message ContextCreateRequest {
848
861
  required string context_name=1;
849
862
  optional string clone_from=2;
850
863
  }
851
864
 
852
- //////////////////////////////////
853
- // ContextInfo : one or all contexts
854
- // use is_init to prime with config
865
+ /// ContextInfo : one or all contexts
866
+ /// use is_init to prime with config
855
867
  message ContextInfoRequest {
856
- optional string context_name=1; // if not set all context get in
857
- optional bool get_size_on_disk=2[default=false]; // get size on disk (expensive)
868
+ optional string context_name=1; /// if not set all context get in
869
+ optional bool get_size_on_disk=2[default=false]; /// get size on disk (expensive)
858
870
  }
859
871
 
860
872
  message ContextInfoResponse {
861
873
 
862
874
 
863
- message Item
864
- {
865
- required string context_name=1;
866
- required bool is_initialized=2;
867
- required bool is_running=3;
868
- optional int64 size_on_disk=4;
869
- optional TimeInterval time_interval=5;
870
- optional bool is_clean=6;
871
- optional string extrainfo=7;
872
- repeated TimeInterval run_history=8;
873
- optional string profile=9;
874
- optional string runmode=10;
875
- optional string node_version=11;
876
- }
875
+ message Item
876
+ {
877
+ required string context_name=1;
878
+ required bool is_initialized=2;
879
+ required bool is_running=3;
880
+ optional int64 size_on_disk=4;
881
+ optional TimeInterval time_interval=5;
882
+ optional bool is_clean=6;
883
+ optional string extrainfo=7;
884
+ repeated TimeInterval run_history=8;
885
+ optional string profile=9;
886
+ optional string runmode=10;
887
+ optional string node_version=11;
888
+ }
877
889
 
878
- repeated Item items=1;
890
+ repeated Item items=1;
879
891
  }
880
892
 
881
- //////////////////////////////////
882
- // ContextDelete : initialize
883
- // reset data only ..
893
+ /// ContextDelete : initialize
894
+ /// reset data only ..
884
895
  message ContextDeleteRequest {
885
- required string context_name=1; // if not set all context get in
886
- optional bool reset_data=2; // reset data dont delete everything
896
+ required string context_name=1; /// if not set all context get in
897
+ optional bool reset_data=2; /// reset data dont delete everything
887
898
  }
888
899
 
889
- // ContextStart : run
890
- // run data only ..
900
+ /// ContextStart : run
901
+ /// run data only ..
891
902
  message ContextStartRequest {
892
- required string context_name=1; // if not set all context get in
893
- optional string mode=2;
894
- optional bool background=3;
895
- optional string pcap_path=4;
896
- optional string run_tool=5; // snort, suricata supported..
897
- optional string tool_ids_config=6;
898
- optional string tool_av_config=7;
903
+ required string context_name=1; /// if not set all context get in
904
+ optional string mode=2; /// same as trisul cmdline run mode
905
+ optional bool background=3;
906
+ optional string pcap_path=4;
907
+ optional string run_tool=5; /// snort, suricata supported..
908
+ optional string tool_ids_config=6;
909
+ optional string tool_av_config=7;
910
+ optional string cmd_in=8; /// maps to trisul -in
911
+ optional string cmd_out=9; /// maps to trisul -out
912
+ optional string cmd_args=10; /// maps to trisul -args
899
913
 
900
914
  }
901
915
 
902
- // ContextSttop : kill
916
+ /// ContextSttop : kill the context processes
903
917
  message ContextStopRequest {
904
- required string context_name=1; // if not set all context get in
905
- optional string run_tool=5; // snort, suricata , trp, flushd supported..
918
+ required string context_name=1; /// if not set all context get in
919
+ optional string run_tool=5; /// snort, suricata , trp, flushd supported..
906
920
  }
907
921
 
908
922
 
909
- //////////////////////////////////
910
- // ContextConfigRequest - start stop status
911
- // OK or ERROR response
912
- // Status = OK if running with PID etc in message text
923
+ /// ContextConfigRequest - start stop status
924
+ /// OK or ERROR response
925
+ /// Status = OK if running with PID etc in message text
913
926
  message ContextConfigRequest {
914
927
  required string context_name=1;
915
928
  optional string profile=2;
916
929
  optional string params=3;
917
- optional bytes push_config_blob=4; // push this ..
918
- repeated NameValue query_config=5; // query, leave the .value field blank
919
- repeated NameValue set_config_values=6; // push this .. (name=value;name=value ..)
930
+ optional bytes push_config_blob=4; /// push this ..
931
+ repeated NameValue query_config=5; /// query, leave the .value field blank
932
+ repeated NameValue set_config_values=6; /// push this .. (name=value;name=value ..)
920
933
  }
921
934
 
922
935
 
923
936
  message ContextConfigResponse {
924
937
 
925
- message Layer
926
- {
927
- required int64 layer=1;
928
- required string probe_id=2;
929
- optional string probe_description=3;
930
- }
931
-
932
- required string context_name=1;
933
- optional string profile=2;
934
- optional string params=3; // what kind of config you want
935
- optional bytes pull_config_blob=4; // config
936
- optional bytes config_blob=5; // compress tar.gz ..
937
- repeated string endpoints_flush=6;
938
- repeated string endpoints_query=7;
939
- repeated string endpoints_pub=8;
940
- repeated NameValue config_values=10; // query, leave the .value field blank
941
- repeated Layer layers=11;
942
-
943
- }
944
-
945
- ///////////////////////////////
946
- // PcapReqiest
947
- // NOTE - only one of the various filters are supported
948
- // sending > 1 will result in error
949
- //
950
- // Modes
951
- // 1. nothing set => PCAP file in contents
952
- // 2. save_file_prefix set => file download token
953
- // 3. merge_pcap_files => file download token
954
- //
938
+ message Layer
939
+ {
940
+ required int64 layer=1;
941
+ required string probe_id=2;
942
+ optional string probe_description=3;
943
+ }
944
+
945
+ required string context_name=1;
946
+ optional string profile=2;
947
+ optional string params=3; /// what kind of config you want
948
+ optional bytes pull_config_blob=4; /// config
949
+ optional bytes config_blob=5; /// compress tar.gz ..
950
+ repeated string endpoints_flush=6;
951
+ repeated string endpoints_query=7;
952
+ repeated string endpoints_pub=8;
953
+ repeated NameValue config_values=10; /// query, leave the .value field blank
954
+ repeated Layer layers=11;
955
+
956
+ }
957
+
958
+ /// PcapRequest - retrieve a PCAP
959
+ /// Sent directly to each probe rather than to the DB query HUB
960
+ ///
961
+ /// the flow is PCAP Request for a file -> put a file on the probe > return a token
962
+ /// > use that token in FileRequest to download the file from the probe
963
+ ///
964
+ /// see app notes and examples
965
+ ///
966
+ /// NOTE - only one of the various filters are supported
967
+ /// sending > 1 will result in error
968
+ ///
969
+ /// Modes
970
+ /// 1. nothing set => PCAP file in contents
971
+ /// 2. save_file_prefix set => file download token
972
+ /// 3. merge_pcap_files => file download token
973
+ ///
974
+ ///
955
975
  message PcapRequest {
956
- required string context_name=1;
957
- optional int64 max_bytes=2[default=100000000]; // 100MB , can increase to 0.75 Filesystem freespace
976
+ required string context_name=1; // context
977
+ optional int64 max_bytes=2[default=100000000]; // max return PCAP size default=100MB , can increase to 0.75 Filesystem freespace
958
978
  optional CompressionType compress_type=3[default=UNCOMPRESSED];
959
- optional TimeInterval time_interval=4; // not needed for merge option
979
+ optional TimeInterval time_interval=4; // not needed for merge option
960
980
  optional string save_file_prefix=5;
961
- optional string filter_expression=6;
962
- repeated string merge_pcap_files=7;
963
- optional bool delete_after_merge=8[default=true];
981
+ optional string filter_expression=6; /// PCAP filter expression in Trisul Filter format
982
+ repeated string merge_pcap_files=7; /// list of PCAP files on probe that you need to merge
983
+ optional bool delete_after_merge=8[default=true];
964
984
  optional PcapFormat format=9[default=LIBPCAP];
965
985
  }
966
986
 
967
987
 
968
- /////////////////////////////////////
969
- // FileredDatagaramResponse
988
+ /// Pcap Response - for small files (<1MB) contents directly contain the PCAP
989
+ /// for larger files, save_file contains a download token for use by FileRequest
970
990
  message PcapResponse {
971
- required string context_name=1;
972
- optional PcapFormat format=2[default=LIBPCAP];
973
- optional CompressionType compress_type=3[default=UNCOMPRESSED];
974
- optional TimeInterval time_interval=4;
975
- optional int64 num_bytes=5;
976
- optional string sha1=6;
977
- optional bytes contents=7;
978
- optional string save_file=8; //use FileRequest framework to download
979
- }
980
-
981
- ////////////////////////////////////
982
- // GrepRequest
991
+ required string context_name=1;
992
+ optional PcapFormat format=2[default=LIBPCAP];
993
+ optional CompressionType compress_type=3[default=UNCOMPRESSED];
994
+ optional TimeInterval time_interval=4;
995
+ optional int64 num_bytes=5;
996
+ optional string sha1=6;
997
+ optional bytes contents=7;
998
+ optional string save_file=8; //use FileRequest framework to download
999
+ }
1000
+
1001
+ /// GrepRequest - reconstruct and search for patterns in saved packets
983
1002
  message GrepRequest {
984
- required string context_name=1;
1003
+ required string context_name=1;
985
1004
  required TimeInterval time_interval=2;
986
1005
  optional int64 maxitems=3 [default=100];
987
1006
  optional int64 flowcutoff_bytes=4;
988
- optional string pattern_hex=5;
989
- optional string pattern_text=6;
990
- optional string pattern_file=7;
991
- repeated string md5list=8;
1007
+ optional string pattern_hex=5; /// hex patttern
1008
+ optional string pattern_text=6; /// plain text
1009
+ optional string pattern_file=7; /// a file - must be available at probe
1010
+ repeated string md5list=8; /// a list of MD5 matching the content
992
1011
  optional bool resolve_keys=9 [default=true];
993
1012
  }
994
1013
 
995
- /////////////////////////////////////
996
- // GrepResponse
1014
+ /// GrepResponse
997
1015
  message GrepResponse {
998
- required string context_name=1;
999
- repeated SessionT sessions=2;
1000
- repeated string hints=3;
1001
- optional string probe_id=4;
1016
+ required string context_name=1;
1017
+ repeated SessionT sessions=2; /// sessionT with keys containing the content
1018
+ repeated string hints=3; /// some surrounding context for the match
1019
+ optional string probe_id=4;
1002
1020
  }
1003
1021
 
1004
- //////////////////////////////////
1005
- // ProbeStatsRequest
1022
+ /// ProbeStatsRequest - DOMAIN
1023
+ /// retrieve statistics about probe cpu, mem, etc
1006
1024
  message ProbeStatsRequest{
1007
- required string context_name=1;
1025
+ required string context_name=1;
1008
1026
  optional string param=2;
1009
1027
  }
1010
1028
 
1011
- //////////////////////////////////
1012
- // ProbeStatsResponse
1029
+ /// ProbeStatsResponse
1013
1030
  message ProbeStatsResponse {
1014
- required string context_name=1;
1031
+ required string context_name=1;
1015
1032
  required string instance_name=2;
1016
1033
  required int64 connections=3;
1017
1034
  required int64 uptime_seconds=4;
@@ -1022,49 +1039,46 @@ message ProbeStatsResponse {
1022
1039
  required double mem_total=9;
1023
1040
  required double drop_percent_cap=10;
1024
1041
  required double drop_percent_trisul=11;
1025
- optional int64 proc_bytes=12;
1026
- optional int64 proc_packets=13;
1027
- optional string offline_pcap_file=14;
1028
- optional bool is_running=15;
1042
+ optional int64 proc_bytes=12;
1043
+ optional int64 proc_packets=13;
1044
+ optional string offline_pcap_file=14;
1045
+ optional bool is_running=15;
1029
1046
  }
1030
1047
 
1031
- /////////////////////////////////////
1032
- // AsyncResponse
1048
+ /// AsyncResponse - a token represnting a future response
1049
+ /// you will get an AsyncResponse for TRP Request if you set the run_async=true at the message level
1033
1050
  message AsyncResponse {
1034
- required int64 token=1;
1035
- optional string response_message=3;
1036
- optional Message response=4;
1051
+ required int64 token=1; /// use this token in AsyncRequest polling until you get the original Response you expected
1052
+ optional string response_message=3;
1053
+ optional Message response=4;
1037
1054
  }
1038
1055
 
1039
- //////////////////////////////////
1040
- // AsyncRequest
1041
- // response taken from original (if ready) or not_ready flag set
1056
+ /// AsyncRequest - Asynchrononous query framework
1057
+ /// response taken from original , the token
1042
1058
  message AsyncRequest {
1043
- required int64 token=1;
1059
+ required int64 token=1; // token from AsyncResponse
1044
1060
  optional string request_message =2; // basically extra text for logging
1045
1061
  }
1046
1062
 
1047
- /////////////////////////////////////
1048
- // FileRequest
1063
+ /// FileRequest - used to download files from Trisul domain nodes like probes
1049
1064
  message FileRequest {
1050
- required string uri=1;
1051
- required int64 position=2;
1052
- optional string params=3; // local meaning sentback n response
1053
- optional string context_name=4;
1054
- optional bool delete_on_eof=5[default=false];
1065
+ required string uri=1; /// uri of resource you want to download , example PcapResponse.save_file
1066
+ required int64 position=2; /// seek position in that file
1067
+ optional string params=3; /// local meaning sentback n response
1068
+ optional string context_name=4; /// context name
1069
+ optional bool delete_on_eof=5[default=false];
1055
1070
  }
1056
1071
 
1057
- //////////////////////////////////
1058
- // FileResponse
1059
- // one chunk at at time, Trisul has slightly inefficient File Transfer
1060
- // for very large files, since most files are data feeds < 100MB fine for now
1072
+ /// FileResponse
1073
+ /// one chunk at at time, Trisul has slightly inefficient File Transfer
1074
+ /// for very large files, since most files are data feeds < 100MB fine for now
1061
1075
  message FileResponse {
1062
- required string uri=1;
1063
- required bool eof=2;
1064
- optional int64 position=3;
1065
- optional bytes content=4;
1076
+ required string uri=1; /// requested URI
1077
+ required bool eof=2; /// end of all chunks
1078
+ optional int64 position=3; /// current position
1079
+ optional bytes content=4; /// file chunk content
1066
1080
  optional string request_params =5;
1067
- optional string context_name=6;
1081
+ optional string context_name=6;
1068
1082
  }
1069
1083
 
1070
1084