@censys/platform-sdk 0.10.3 → 0.10.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +21 -2
  2. package/docs/sdks/adversaryinvestigation/README.md +625 -0
  3. package/docs/sdks/threathunting/README.md +8 -8
  4. package/funcs/threatHuntingCreateCenseyeJob.d.ts +1 -1
  5. package/funcs/threatHuntingCreateCenseyeJob.js +1 -1
  6. package/funcs/threatHuntingCreateTrackedScan.d.ts +1 -1
  7. package/funcs/threatHuntingCreateTrackedScan.js +1 -1
  8. package/funcs/threatHuntingGetCenseyeJob.d.ts +1 -1
  9. package/funcs/threatHuntingGetCenseyeJob.js +1 -1
  10. package/funcs/threatHuntingGetCenseyeJobResults.d.ts +1 -1
  11. package/funcs/threatHuntingGetCenseyeJobResults.js +1 -1
  12. package/funcs/threatHuntingGetHostObservationsWithCertificate.d.ts +1 -1
  13. package/funcs/threatHuntingGetHostObservationsWithCertificate.js +1 -1
  14. package/funcs/threatHuntingListThreats.d.ts +1 -1
  15. package/funcs/threatHuntingListThreats.js +1 -1
  16. package/funcs/threatHuntingValueCounts.d.ts +1 -1
  17. package/funcs/threatHuntingValueCounts.js +1 -1
  18. package/jsr.json +1 -1
  19. package/lib/config.d.ts +3 -3
  20. package/lib/config.js +3 -3
  21. package/package.json +1 -1
  22. package/sdk/adversaryinvestigation.d.ts +54 -0
  23. package/sdk/adversaryinvestigation.d.ts.map +1 -0
  24. package/sdk/adversaryinvestigation.js +82 -0
  25. package/sdk/adversaryinvestigation.js.map +1 -0
  26. package/sdk/sdk.d.ts +3 -0
  27. package/sdk/sdk.d.ts.map +1 -1
  28. package/sdk/sdk.js +4 -0
  29. package/sdk/sdk.js.map +1 -1
  30. package/sdk/threathunting.d.ts +7 -7
  31. package/sdk/threathunting.js +7 -7
  32. package/src/funcs/threatHuntingCreateCenseyeJob.ts +1 -1
  33. package/src/funcs/threatHuntingCreateTrackedScan.ts +1 -1
  34. package/src/funcs/threatHuntingGetCenseyeJob.ts +1 -1
  35. package/src/funcs/threatHuntingGetCenseyeJobResults.ts +1 -1
  36. package/src/funcs/threatHuntingGetHostObservationsWithCertificate.ts +1 -1
  37. package/src/funcs/threatHuntingListThreats.ts +1 -1
  38. package/src/funcs/threatHuntingValueCounts.ts +1 -1
  39. package/src/lib/config.ts +3 -3
  40. package/src/sdk/adversaryinvestigation.ts +138 -0
  41. package/src/sdk/sdk.ts +8 -0
  42. package/src/sdk/threathunting.ts +7 -7
package/docs/sdks/adversaryinvestigation/README.md ADDED
@@ -0,0 +1,625 @@
1
+ # AdversaryInvestigation
2
+
3
+ ## Overview
4
+
5
+ Endpoints related to the Adversary Investigation product
6
+
7
+ ### Available Operations
8
+
9
+ * [createCenseyeJob](#createcenseyejob) - CensEye: Create a pivot analysis job
10
+ * [getCenseyeJob](#getcenseyejob) - CensEye: Get job status
11
+ * [getCenseyeJobResults](#getcenseyejobresults) - CensEye: Get job results
12
+ * [getHostObservationsWithCertificate](#gethostobservationswithcertificate) - Get host history for a certificate
13
+ * [createTrackedScan](#createtrackedscan) - Live Discovery: Initiate a new scan
14
+ * [listThreats](#listthreats) - List active threats
15
+ * [valueCounts](#valuecounts) - CensEye: Retrieve value counts to discover pivots
16
+
17
+ ## createCenseyeJob
18
+
19
+ Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate. The job extracts default pivot fields from the target asset and counts matching documents for each field-value pair. Poll the job status endpoint to track progress, then retrieve results when complete.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
20
+
21
+ ### Example Usage
22
+
23
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-censeye-jobs-create" method="post" path="/v3/threat-hunting/censeye/jobs" -->
24
+ ```typescript
25
+ import { SDK } from "@censys/platform-sdk";
26
+
27
+ const sdk = new SDK({
28
+ organizationId: "11111111-2222-3333-4444-555555555555",
29
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
30
+ });
31
+
32
+ async function run() {
33
+ const result = await sdk.adversaryInvestigation.createCenseyeJob({
34
+ createCenseyeJobInputBody: {
35
+ target: {
36
+ certificateId: "3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf",
37
+ hostId: "8.8.8.8",
38
+ webpropertyId: "example.com:443",
39
+ },
40
+ },
41
+ });
42
+
43
+ console.log(result);
44
+ }
45
+
46
+ run();
47
+ ```
48
+
49
+ ### Standalone function
50
+
51
+ The standalone function version of this method:
52
+
53
+ ```typescript
54
+ import { SDKCore } from "@censys/platform-sdk/core.js";
55
+ import { threatHuntingCreateCenseyeJob } from "@censys/platform-sdk/funcs/threatHuntingCreateCenseyeJob.js";
56
+
57
+ // Use `SDKCore` for best tree-shaking performance.
58
+ // You can create one instance of it to use across an application.
59
+ const sdk = new SDKCore({
60
+ organizationId: "11111111-2222-3333-4444-555555555555",
61
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
62
+ });
63
+
64
+ async function run() {
65
+ const res = await threatHuntingCreateCenseyeJob(sdk, {
66
+ createCenseyeJobInputBody: {
67
+ target: {
68
+ certificateId: "3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf",
69
+ hostId: "8.8.8.8",
70
+ webpropertyId: "example.com:443",
71
+ },
72
+ },
73
+ });
74
+ if (res.ok) {
75
+ const { value: result } = res;
76
+ console.log(result);
77
+ } else {
78
+ console.log("threatHuntingCreateCenseyeJob failed:", res.error);
79
+ }
80
+ }
81
+
82
+ run();
83
+ ```
84
+
85
+ ### Parameters
86
+
87
+ | Parameter | Type | Required | Description |
88
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
89
+ | `request` | [operations.V3ThreathuntingCenseyeJobsCreateRequest](../../models/operations/v3threathuntingcenseyejobscreaterequest.md) | :heavy_check_mark: | The request object to use for the request. |
90
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
91
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
92
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
93
+
94
+ ### Response
95
+
96
+ **Promise\<[operations.V3ThreathuntingCenseyeJobsCreateResponse](../../models/operations/v3threathuntingcenseyejobscreateresponse.md)\>**
97
+
98
+ ### Errors
99
+
100
+ | Error Type | Status Code | Content Type |
101
+ | -------------------------- | -------------------------- | -------------------------- |
102
+ | errors.AuthenticationError | 401 | application/json |
103
+ | errors.ErrorModel | 400, 403, 422 | application/problem+json |
104
+ | errors.ErrorModel | 500 | application/problem+json |
105
+ | errors.SDKError | 4XX, 5XX | \*/\* |
106
+
107
+ ## getCenseyeJob
108
+
109
+ Retrieve the current status of a CensEye pivot analysis job. Use this to poll for completion before fetching results.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
110
+
111
+ ### Example Usage
112
+
113
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-censeye-jobs-get" method="get" path="/v3/threat-hunting/censeye/jobs/{job_id}" -->
114
+ ```typescript
115
+ import { SDK } from "@censys/platform-sdk";
116
+
117
+ const sdk = new SDK({
118
+ organizationId: "11111111-2222-3333-4444-555555555555",
119
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
120
+ });
121
+
122
+ async function run() {
123
+ const result = await sdk.adversaryInvestigation.getCenseyeJob({
124
+ jobId: "3c47b971-5db6-4a9e-8d59-14fc0486172b",
125
+ });
126
+
127
+ console.log(result);
128
+ }
129
+
130
+ run();
131
+ ```
132
+
133
+ ### Standalone function
134
+
135
+ The standalone function version of this method:
136
+
137
+ ```typescript
138
+ import { SDKCore } from "@censys/platform-sdk/core.js";
139
+ import { threatHuntingGetCenseyeJob } from "@censys/platform-sdk/funcs/threatHuntingGetCenseyeJob.js";
140
+
141
+ // Use `SDKCore` for best tree-shaking performance.
142
+ // You can create one instance of it to use across an application.
143
+ const sdk = new SDKCore({
144
+ organizationId: "11111111-2222-3333-4444-555555555555",
145
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
146
+ });
147
+
148
+ async function run() {
149
+ const res = await threatHuntingGetCenseyeJob(sdk, {
150
+ jobId: "3c47b971-5db6-4a9e-8d59-14fc0486172b",
151
+ });
152
+ if (res.ok) {
153
+ const { value: result } = res;
154
+ console.log(result);
155
+ } else {
156
+ console.log("threatHuntingGetCenseyeJob failed:", res.error);
157
+ }
158
+ }
159
+
160
+ run();
161
+ ```
162
+
163
+ ### Parameters
164
+
165
+ | Parameter | Type | Required | Description |
166
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
167
+ | `request` | [operations.V3ThreathuntingCenseyeJobsGetRequest](../../models/operations/v3threathuntingcenseyejobsgetrequest.md) | :heavy_check_mark: | The request object to use for the request. |
168
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
169
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
170
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
171
+
172
+ ### Response
173
+
174
+ **Promise\<[operations.V3ThreathuntingCenseyeJobsGetResponse](../../models/operations/v3threathuntingcenseyejobsgetresponse.md)\>**
175
+
176
+ ### Errors
177
+
178
+ | Error Type | Status Code | Content Type |
179
+ | -------------------------- | -------------------------- | -------------------------- |
180
+ | errors.AuthenticationError | 401 | application/json |
181
+ | errors.ErrorModel | 400, 403, 404 | application/problem+json |
182
+ | errors.ErrorModel | 500 | application/problem+json |
183
+ | errors.SDKError | 4XX, 5XX | \*/\* |
184
+
185
+ ## getCenseyeJobResults
186
+
187
+ Retrieve the results of a completed CensEye pivot analysis job. Each result contains a count and the field-value pairs that were analyzed. Results may be empty if the job is still running.<br><br>Results are paginated. Use the `next_page_token` from the response to fetch subsequent pages.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
188
+
189
+ ### Example Usage
190
+
191
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-censeye-job-results" method="get" path="/v3/threat-hunting/censeye/jobs/{job_id}/results" -->
192
+ ```typescript
193
+ import { SDK } from "@censys/platform-sdk";
194
+
195
+ const sdk = new SDK({
196
+ organizationId: "11111111-2222-3333-4444-555555555555",
197
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
198
+ });
199
+
200
+ async function run() {
201
+ const result = await sdk.adversaryInvestigation.getCenseyeJobResults({
202
+ jobId: "e58e9a0e-e104-42cf-9d0e-fe88713bc6e3",
203
+ });
204
+
205
+ console.log(result);
206
+ }
207
+
208
+ run();
209
+ ```
210
+
211
+ ### Standalone function
212
+
213
+ The standalone function version of this method:
214
+
215
+ ```typescript
216
+ import { SDKCore } from "@censys/platform-sdk/core.js";
217
+ import { threatHuntingGetCenseyeJobResults } from "@censys/platform-sdk/funcs/threatHuntingGetCenseyeJobResults.js";
218
+
219
+ // Use `SDKCore` for best tree-shaking performance.
220
+ // You can create one instance of it to use across an application.
221
+ const sdk = new SDKCore({
222
+ organizationId: "11111111-2222-3333-4444-555555555555",
223
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
224
+ });
225
+
226
+ async function run() {
227
+ const res = await threatHuntingGetCenseyeJobResults(sdk, {
228
+ jobId: "e58e9a0e-e104-42cf-9d0e-fe88713bc6e3",
229
+ });
230
+ if (res.ok) {
231
+ const { value: result } = res;
232
+ console.log(result);
233
+ } else {
234
+ console.log("threatHuntingGetCenseyeJobResults failed:", res.error);
235
+ }
236
+ }
237
+
238
+ run();
239
+ ```
240
+
241
+ ### Parameters
242
+
243
+ | Parameter | Type | Required | Description |
244
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
245
+ | `request` | [operations.V3ThreathuntingCenseyeJobResultsRequest](../../models/operations/v3threathuntingcenseyejobresultsrequest.md) | :heavy_check_mark: | The request object to use for the request. |
246
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
247
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
248
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
249
+
250
+ ### Response
251
+
252
+ **Promise\<[operations.V3ThreathuntingCenseyeJobResultsResponse](../../models/operations/v3threathuntingcenseyejobresultsresponse.md)\>**
253
+
254
+ ### Errors
255
+
256
+ | Error Type | Status Code | Content Type |
257
+ | -------------------------- | -------------------------- | -------------------------- |
258
+ | errors.AuthenticationError | 401 | application/json |
259
+ | errors.ErrorModel | 400, 403, 404 | application/problem+json |
260
+ | errors.ErrorModel | 500 | application/problem+json |
261
+ | errors.SDKError | 4XX, 5XX | \*/\* |
262
+
263
+ ## getHostObservationsWithCertificate
264
+
265
+ Retrieve the historical observations of hosts associated with a certificate. This is useful for threat hunting, detection engineering, and timeline generation. Certificate history is also visible to Adversary Investigation users in the Platform UI on the [certificate timeline](https://docs.censys.com/docs/platform-threat-hunting-use-cert-history-to-build-better-detections#/).<br><br>You can define a specific time frame of interest. If you do not specify a time frame, this endpoint will search the historical dataset that is available to your account. You may also filter results by port and transport protocol.<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module. It costs 5 credits per page of results.
266
+
267
+ ### Example Usage
268
+
269
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-get-host-observations-with-certificate" method="get" path="/v3/threat-hunting/certificate/{certificate_id}/observations/hosts" -->
270
+ ```typescript
271
+ import { SDK } from "@censys/platform-sdk";
272
+
273
+ const sdk = new SDK({
274
+ organizationId: "11111111-2222-3333-4444-555555555555",
275
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
276
+ });
277
+
278
+ async function run() {
279
+ const result = await sdk.adversaryInvestigation.getHostObservationsWithCertificate({
280
+ certificateId: "55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46",
281
+ startTime: "2023-01-01T00:00:00Z",
282
+ endTime: "2023-12-31T23:59:59Z",
283
+ port: 443,
284
+ protocol: "TCP",
285
+ pageSize: 50,
286
+ });
287
+
288
+ console.log(result);
289
+ }
290
+
291
+ run();
292
+ ```
293
+
294
+ ### Standalone function
295
+
296
+ The standalone function version of this method:
297
+
298
+ ```typescript
299
+ import { SDKCore } from "@censys/platform-sdk/core.js";
300
+ import { threatHuntingGetHostObservationsWithCertificate } from "@censys/platform-sdk/funcs/threatHuntingGetHostObservationsWithCertificate.js";
301
+
302
+ // Use `SDKCore` for best tree-shaking performance.
303
+ // You can create one instance of it to use across an application.
304
+ const sdk = new SDKCore({
305
+ organizationId: "11111111-2222-3333-4444-555555555555",
306
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
307
+ });
308
+
309
+ async function run() {
310
+ const res = await threatHuntingGetHostObservationsWithCertificate(sdk, {
311
+ certificateId: "55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46",
312
+ startTime: "2023-01-01T00:00:00Z",
313
+ endTime: "2023-12-31T23:59:59Z",
314
+ port: 443,
315
+ protocol: "TCP",
316
+ pageSize: 50,
317
+ });
318
+ if (res.ok) {
319
+ const { value: result } = res;
320
+ console.log(result);
321
+ } else {
322
+ console.log("threatHuntingGetHostObservationsWithCertificate failed:", res.error);
323
+ }
324
+ }
325
+
326
+ run();
327
+ ```
328
+
329
+ ### Parameters
330
+
331
+ | Parameter | Type | Required | Description |
332
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
333
+ | `request` | [operations.V3ThreathuntingGetHostObservationsWithCertificateRequest](../../models/operations/v3threathuntinggethostobservationswithcertificaterequest.md) | :heavy_check_mark: | The request object to use for the request. |
334
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
335
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
336
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
337
+
338
+ ### Response
339
+
340
+ **Promise\<[operations.V3ThreathuntingGetHostObservationsWithCertificateResponse](../../models/operations/v3threathuntinggethostobservationswithcertificateresponse.md)\>**
341
+
342
+ ### Errors
343
+
344
+ | Error Type | Status Code | Content Type |
345
+ | -------------------------- | -------------------------- | -------------------------- |
346
+ | errors.AuthenticationError | 401 | application/json |
347
+ | errors.ErrorModel | 400, 403, 404 | application/problem+json |
348
+ | errors.ErrorModel | 500 | application/problem+json |
349
+ | errors.SDKError | 4XX, 5XX | \*/\* |
350
+
351
+ ## createTrackedScan
352
+
353
+ Initiate a scan to look for a currently unobserved service at a specific IP and port (`ip:port`) or hostname and port (`hostname:port`). This is equivalent to the [Live Discovery](https://docs.censys.com/docs/platform-threat-hunting-use-live-scan-and-rescan-to-validate-infrastructure#/) feature available in the UI, but you can also target web properties in addition to hosts.<br><br>The scan may take several minutes to complete. The response will contain a scan ID that you can use to [monitor the scan's status](https://docs.censys.com/reference/v3-threathunting-scans-get#/). After the scan completes, perform a lookup on the target asset to retrieve detailed scan information.<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module. It costs 15 credits to execute this endpoint.
354
+
355
+ ### Example Usage
356
+
357
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-scans-discovery" method="post" path="/v3/threat-hunting/scans/discovery" -->
358
+ ```typescript
359
+ import { SDK } from "@censys/platform-sdk";
360
+
361
+ const sdk = new SDK({
362
+ organizationId: "11111111-2222-3333-4444-555555555555",
363
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
364
+ });
365
+
366
+ async function run() {
367
+ const result = await sdk.adversaryInvestigation.createTrackedScan({
368
+ scansDiscoveryInputBody: {
369
+ target: {
370
+ hostnamePort: {
371
+ hostname: "censys.io",
372
+ port: 443,
373
+ },
374
+ },
375
+ },
376
+ });
377
+
378
+ console.log(result);
379
+ }
380
+
381
+ run();
382
+ ```
383
+
384
+ ### Standalone function
385
+
386
+ The standalone function version of this method:
387
+
388
+ ```typescript
389
+ import { SDKCore } from "@censys/platform-sdk/core.js";
390
+ import { threatHuntingCreateTrackedScan } from "@censys/platform-sdk/funcs/threatHuntingCreateTrackedScan.js";
391
+
392
+ // Use `SDKCore` for best tree-shaking performance.
393
+ // You can create one instance of it to use across an application.
394
+ const sdk = new SDKCore({
395
+ organizationId: "11111111-2222-3333-4444-555555555555",
396
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
397
+ });
398
+
399
+ async function run() {
400
+ const res = await threatHuntingCreateTrackedScan(sdk, {
401
+ scansDiscoveryInputBody: {
402
+ target: {
403
+ hostnamePort: {
404
+ hostname: "censys.io",
405
+ port: 443,
406
+ },
407
+ },
408
+ },
409
+ });
410
+ if (res.ok) {
411
+ const { value: result } = res;
412
+ console.log(result);
413
+ } else {
414
+ console.log("threatHuntingCreateTrackedScan failed:", res.error);
415
+ }
416
+ }
417
+
418
+ run();
419
+ ```
420
+
421
+ ### Parameters
422
+
423
+ | Parameter | Type | Required | Description |
424
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
425
+ | `request` | [operations.V3ThreathuntingScansDiscoveryRequest](../../models/operations/v3threathuntingscansdiscoveryrequest.md) | :heavy_check_mark: | The request object to use for the request. |
426
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
427
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
428
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
429
+
430
+ ### Response
431
+
432
+ **Promise\<[operations.V3ThreathuntingScansDiscoveryResponse](../../models/operations/v3threathuntingscansdiscoveryresponse.md)\>**
433
+
434
+ ### Errors
435
+
436
+ | Error Type | Status Code | Content Type |
437
+ | -------------------------- | -------------------------- | -------------------------- |
438
+ | errors.AuthenticationError | 401 | application/json |
439
+ | errors.ErrorModel | 400, 403, 422 | application/problem+json |
440
+ | errors.ErrorModel | 500 | application/problem+json |
441
+ | errors.SDKError | 4XX, 5XX | \*/\* |
442
+
443
+ ## listThreats
444
+
445
+ Retrieve a list of active threats observed by Censys by aggregating threat IDs across hosts and web properties. Threats are active if their fingerprint has been identified on hosts or web properties by Censys scans. This information is also available on the [Explore Threats page in the Platform web UI](https://platform.censys.io/threats).<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module.
446
+
447
+ ### Example Usage
448
+
449
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-threats-list" method="get" path="/v3/threat-hunting/threats" -->
450
+ ```typescript
451
+ import { SDK } from "@censys/platform-sdk";
452
+
453
+ const sdk = new SDK({
454
+ organizationId: "11111111-2222-3333-4444-555555555555",
455
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
456
+ });
457
+
458
+ async function run() {
459
+ const result = await sdk.adversaryInvestigation.listThreats({
460
+ query: "*",
461
+ });
462
+
463
+ console.log(result);
464
+ }
465
+
466
+ run();
467
+ ```
468
+
469
+ ### Standalone function
470
+
471
+ The standalone function version of this method:
472
+
473
+ ```typescript
474
+ import { SDKCore } from "@censys/platform-sdk/core.js";
475
+ import { threatHuntingListThreats } from "@censys/platform-sdk/funcs/threatHuntingListThreats.js";
476
+
477
+ // Use `SDKCore` for best tree-shaking performance.
478
+ // You can create one instance of it to use across an application.
479
+ const sdk = new SDKCore({
480
+ organizationId: "11111111-2222-3333-4444-555555555555",
481
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
482
+ });
483
+
484
+ async function run() {
485
+ const res = await threatHuntingListThreats(sdk, {
486
+ query: "*",
487
+ });
488
+ if (res.ok) {
489
+ const { value: result } = res;
490
+ console.log(result);
491
+ } else {
492
+ console.log("threatHuntingListThreats failed:", res.error);
493
+ }
494
+ }
495
+
496
+ run();
497
+ ```
498
+
499
+ ### Parameters
500
+
501
+ | Parameter | Type | Required | Description |
502
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
503
+ | `request` | [operations.V3ThreathuntingThreatsListRequest](../../models/operations/v3threathuntingthreatslistrequest.md) | :heavy_check_mark: | The request object to use for the request. |
504
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
505
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
506
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
507
+
508
+ ### Response
509
+
510
+ **Promise\<[operations.V3ThreathuntingThreatsListResponse](../../models/operations/v3threathuntingthreatslistresponse.md)\>**
511
+
512
+ ### Errors
513
+
514
+ | Error Type | Status Code | Content Type |
515
+ | -------------------------- | -------------------------- | -------------------------- |
516
+ | errors.AuthenticationError | 401 | application/json |
517
+ | errors.ErrorModel | 400, 403, 422 | application/problem+json |
518
+ | errors.ErrorModel | 500 | application/problem+json |
519
+ | errors.SDKError | 4XX, 5XX | \*/\* |
520
+
521
+ ## valueCounts
522
+
523
+ Get counts of web assets for specific field-value pairs and combinations of field-value pairs. This is similar to the [CensEye functionality](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#/) available in the Platform web UI, but it allows you to define specific fields of interest rather than the [default fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#default-pivot-fields) leveraged by the tool in the UI.<br><br>Each array can only target fields within the same nested object and may contain at most 5 field-value pairs. For example, you can combine `host.services.port=80` and `host.services.protocol=SSH` in the same array, but you cannot combine `host.services.port=80` and `host.location.country="United States"` in the same array. You can input multiple arrays of objects in each API call.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module. This endpoint costs 1 credit per count condition (array of objects) included in the API call.
524
+
525
+ ### Example Usage
526
+
527
+ <!-- UsageSnippet language="typescript" operationID="v3-threathunting-value-counts" method="post" path="/v3/threat-hunting/value-counts" -->
528
+ ```typescript
529
+ import { SDK } from "@censys/platform-sdk";
530
+
531
+ const sdk = new SDK({
532
+ organizationId: "11111111-2222-3333-4444-555555555555",
533
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
534
+ });
535
+
536
+ async function run() {
537
+ const result = await sdk.adversaryInvestigation.valueCounts({
538
+ searchValueCountsInputBody: {
539
+ andCountConditions: [
540
+ {
541
+ fieldValuePairs: [
542
+ {
543
+ field: "host.services.port",
544
+ value: "80",
545
+ },
546
+ ],
547
+ },
548
+ {
549
+ fieldValuePairs: [],
550
+ },
551
+ ],
552
+ },
553
+ });
554
+
555
+ console.log(result);
556
+ }
557
+
558
+ run();
559
+ ```
560
+
561
+ ### Standalone function
562
+
563
+ The standalone function version of this method:
564
+
565
+ ```typescript
566
+ import { SDKCore } from "@censys/platform-sdk/core.js";
567
+ import { threatHuntingValueCounts } from "@censys/platform-sdk/funcs/threatHuntingValueCounts.js";
568
+
569
+ // Use `SDKCore` for best tree-shaking performance.
570
+ // You can create one instance of it to use across an application.
571
+ const sdk = new SDKCore({
572
+ organizationId: "11111111-2222-3333-4444-555555555555",
573
+ personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
574
+ });
575
+
576
+ async function run() {
577
+ const res = await threatHuntingValueCounts(sdk, {
578
+ searchValueCountsInputBody: {
579
+ andCountConditions: [
580
+ {
581
+ fieldValuePairs: [
582
+ {
583
+ field: "host.services.port",
584
+ value: "80",
585
+ },
586
+ ],
587
+ },
588
+ {
589
+ fieldValuePairs: [],
590
+ },
591
+ ],
592
+ },
593
+ });
594
+ if (res.ok) {
595
+ const { value: result } = res;
596
+ console.log(result);
597
+ } else {
598
+ console.log("threatHuntingValueCounts failed:", res.error);
599
+ }
600
+ }
601
+
602
+ run();
603
+ ```
604
+
605
+ ### Parameters
606
+
607
+ | Parameter | Type | Required | Description |
608
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
609
+ | `request` | [operations.V3ThreathuntingValueCountsRequest](../../models/operations/v3threathuntingvaluecountsrequest.md) | :heavy_check_mark: | The request object to use for the request. |
610
+ | `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
611
+ | `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
612
+ | `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
613
+
614
+ ### Response
615
+
616
+ **Promise\<[operations.V3ThreathuntingValueCountsResponse](../../models/operations/v3threathuntingvaluecountsresponse.md)\>**
617
+
618
+ ### Errors
619
+
620
+ | Error Type | Status Code | Content Type |
621
+ | -------------------------- | -------------------------- | -------------------------- |
622
+ | errors.AuthenticationError | 401 | application/json |
623
+ | errors.ErrorModel | 400, 403, 422 | application/problem+json |
624
+ | errors.ErrorModel | 500 | application/problem+json |
625
+ | errors.SDKError | 4XX, 5XX | \*/\* |