@censys/platform-sdk 0.4.3 → 0.5.0

package/docs/sdks/globaldata/README.md

@@ -9,13 +9,17 @@ Endpoints related to the Global Data product
 
 * [getCertificates](#getcertificates) - Get multiple certificates
 * [getCertificate](#getcertificate) - Get a certificate
+* [getHostObservationsWithCertificate](#gethostobservationswithcertificate) - Get Host Observations With Certificate
 * [getHosts](#gethosts) - Get multiple hosts
 * [getHost](#gethost) - Get a host
 * [getHostTimeline](#gethosttimeline) - Get host event history
 * [getWebProperties](#getwebproperties) - Get multiple web properties
 * [getWebProperty](#getwebproperty) - Get a web property
+* [createTrackedScan](#createtrackedscan) - Create a tracked rescan
+* [getTrackedScan](#gettrackedscan) - Get tracked scan details
 * [aggregate](#aggregate) - Aggregate results for a search query
 * [search](#search) - Run a search query
+* [getTrackedScanThreatHunting](#gettrackedscanthreathunting) - Get tracked scan details
 
 ## getCertificates
 
@@ -23,6 +27,7 @@ Retrieve information about multiple certificates. A certificate ID is its SHA-25
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-certificate-list" method="get" path="/v3/global/asset/certificate" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -102,6 +107,7 @@ Retrieve information about a single certificate. A certificate ID is its SHA-256
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-certificate" method="get" path="/v3/global/asset/certificate/{certificate_id}" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -171,12 +177,99 @@ run();
 | errors.ErrorModel        | 401, 403                 | application/problem+json |
 | errors.SDKError          | 4XX, 5XX                 | \*/\*                    |
 
+## getHostObservationsWithCertificate
+
+Retrieve historical observations of hosts associated with a certificate fingerprint. Useful for threat hunting, detection engineering, and timeline generation.
+
+### Example Usage
+
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-get-host-observations-with-certificate" method="get" path="/v3/global/asset/certificate/{certificate_id}/observations/hosts" -->
+```typescript
+import { SDK } from "@censys/platform-sdk";
+
+const sdk = new SDK({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const result = await sdk.globalData.getHostObservationsWithCertificate({
+    certificateId: "55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46",
+    startTime: "2023-01-01T00:00:00Z",
+    endTime: "2023-12-31T23:59:59Z",
+    port: 443,
+    protocol: "TCP",
+    pageSize: 50,
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { SDKCore } from "@censys/platform-sdk/core.js";
+import { globalDataGetHostObservationsWithCertificate } from "@censys/platform-sdk/funcs/globalDataGetHostObservationsWithCertificate.js";
+
+// Use `SDKCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const sdk = new SDKCore({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const res = await globalDataGetHostObservationsWithCertificate(sdk, {
+    certificateId: "55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46",
+    startTime: "2023-01-01T00:00:00Z",
+    endTime: "2023-12-31T23:59:59Z",
+    port: 443,
+    protocol: "TCP",
+    pageSize: 50,
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("globalDataGetHostObservationsWithCertificate failed:", res.error);
+  }
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [operations.V3GlobaldataGetHostObservationsWithCertificateRequest](../../models/operations/v3globaldatagethostobservationswithcertificaterequest.md)                           | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `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. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[operations.V3GlobaldataGetHostObservationsWithCertificateResponse](../../models/operations/v3globaldatagethostobservationswithcertificateresponse.md)\>**
+
+### Errors
+
+| Error Type               | Status Code              | Content Type             |
+| ------------------------ | ------------------------ | ------------------------ |
+| errors.ErrorModel        | 401, 403                 | application/problem+json |
+| errors.SDKError          | 4XX, 5XX                 | \*/\*                    |
+
 ## getHosts
 
 Retrieve information about multiple hosts. A host ID is its IP address.
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-host-list" method="get" path="/v3/global/asset/host" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -256,6 +349,7 @@ Retrieve information about a single host. A host ID is its IP address.
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-host" method="get" path="/v3/global/asset/host/{host_id}" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -333,6 +427,7 @@ Retrieve event history for a host. A host ID is its IP address.
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-host-timeline" method="get" path="/v3/global/asset/host/{host_id}/timeline" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -412,6 +507,7 @@ Retrieve information about multiple web properties. Web properties are identifie
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-webproperty-list" method="get" path="/v3/global/asset/webproperty" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -491,6 +587,7 @@ Retrieve information about a single web property. Web properties are identified
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-asset-webproperty" method="get" path="/v3/global/asset/webproperty/{webproperty_id}" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -562,12 +659,180 @@ run();
 | errors.ErrorModel        | 401, 403                 | application/problem+json |
 | errors.SDKError          | 4XX, 5XX                 | \*/\*                    |
 
+## createTrackedScan
+
+Create a new tracked rescan for a known service or web property. Rescans are used to update information for previously discovered targets. The scan will be queued. The response will contain a scan ID that you can use with the [get tracked scan details endpoint](https://docs.censys.com/reference/v3-globaldata-scans-get#/) to monitor its status and results.<br><br>This endpoint is available to all Enterprise customers.
+
+### Example Usage
+
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-scans-rescan" method="post" path="/v3/global/scans/rescan" -->
+```typescript
+import { SDK } from "@censys/platform-sdk";
+
+const sdk = new SDK({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const result = await sdk.globalData.createTrackedScan({
+    scansRescanInputBody: {
+      target: {
+        webOrigin: {
+          hostname: "censys.io",
+          port: 443,
+        },
+      },
+    },
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { SDKCore } from "@censys/platform-sdk/core.js";
+import { globalDataCreateTrackedScan } from "@censys/platform-sdk/funcs/globalDataCreateTrackedScan.js";
+
+// Use `SDKCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const sdk = new SDKCore({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const res = await globalDataCreateTrackedScan(sdk, {
+    scansRescanInputBody: {
+      target: {
+        webOrigin: {
+          hostname: "censys.io",
+          port: 443,
+        },
+      },
+    },
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("globalDataCreateTrackedScan failed:", res.error);
+  }
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [operations.V3GlobaldataScansRescanRequest](../../models/operations/v3globaldatascansrescanrequest.md)                                                                         | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `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. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[operations.V3GlobaldataScansRescanResponse](../../models/operations/v3globaldatascansrescanresponse.md)\>**
+
+### Errors
+
+| Error Type               | Status Code              | Content Type             |
+| ------------------------ | ------------------------ | ------------------------ |
+| errors.ErrorModel        | 401, 403                 | application/problem+json |
+| errors.SDKError          | 4XX, 5XX                 | \*/\*                    |
+
+## getTrackedScan
+
+Retrieve the current status and results of a tracked scan by its ID.
+        This endpoint works for both discovery scans and rescans.
+
+### Example Usage
+
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-scans-get" method="get" path="/v3/global/scans/{scan_id}" -->
+```typescript
+import { SDK } from "@censys/platform-sdk";
+
+const sdk = new SDK({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const result = await sdk.globalData.getTrackedScan({
+    scanId: "5f39588f-d4c5-48e5-8894-0bb5918c28fa",
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { SDKCore } from "@censys/platform-sdk/core.js";
+import { globalDataGetTrackedScan } from "@censys/platform-sdk/funcs/globalDataGetTrackedScan.js";
+
+// Use `SDKCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const sdk = new SDKCore({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const res = await globalDataGetTrackedScan(sdk, {
+    scanId: "5f39588f-d4c5-48e5-8894-0bb5918c28fa",
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("globalDataGetTrackedScan failed:", res.error);
+  }
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [operations.V3GlobaldataScansGetRequest](../../models/operations/v3globaldatascansgetrequest.md)                                                                               | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `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. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[operations.V3GlobaldataScansGetResponse](../../models/operations/v3globaldatascansgetresponse.md)\>**
+
+### Errors
+
+| Error Type               | Status Code              | Content Type             |
+| ------------------------ | ------------------------ | ------------------------ |
+| errors.ErrorModel        | 401, 403                 | application/problem+json |
+| errors.SDKError          | 4XX, 5XX                 | \*/\*                    |
+
 ## aggregate
 
 Aggregate results for a Platform search query. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-search-aggregate" method="post" path="/v3/global/search/aggregate" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -579,9 +844,9 @@ const sdk = new SDK({
 async function run() {
   const result = await sdk.globalData.aggregate({
     searchAggregateInputBody: {
-      field: "web.endpoints.http.html_title",
+      field: "host.services.port",
       numberOfBuckets: 100,
-      query: "web: *",
+      query: "host.services.protocol=SSH",
     },
   });
 
@@ -609,9 +874,9 @@ const sdk = new SDKCore({
 async function run() {
   const res = await globalDataAggregate(sdk, {
     searchAggregateInputBody: {
-      field: "web.endpoints.http.html_title",
+      field: "host.services.port",
       numberOfBuckets: 100,
-      query: "web: *",
+      query: "host.services.protocol=SSH",
     },
   });
   if (res.ok) {
@@ -651,6 +916,7 @@ Run a search query across Censys data. Reference the [documentation on Censys Qu
 
 ### Example Usage
 
+<!-- UsageSnippet language="typescript" operationID="v3-globaldata-search-query" method="post" path="/v3/global/search/query" -->
 ```typescript
 import { SDK } from "@censys/platform-sdk";
 
@@ -666,7 +932,6 @@ async function run() {
         "host.ip",
       ],
       pageSize: 1,
-      pageToken: "<next_page_token>",
       query: "host.services: (protocol=SSH and not port: 22)",
     },
   });
@@ -699,7 +964,6 @@ async function run() {
         "host.ip",
       ],
       pageSize: 1,
-      pageToken: "<next_page_token>",
       query: "host.services: (protocol=SSH and not port: 22)",
     },
   });
@@ -729,6 +993,83 @@ run();
 
 ### Errors
 
+| Error Type               | Status Code              | Content Type             |
+| ------------------------ | ------------------------ | ------------------------ |
+| errors.ErrorModel        | 401, 403                 | application/problem+json |
+| errors.SDKError          | 4XX, 5XX                 | \*/\*                    |
+
+## getTrackedScanThreatHunting
+
+Retrieve the current status and results of a tracked scan by its ID.
+        This endpoint works for both discovery scans and rescans.
+
+### Example Usage
+
+<!-- UsageSnippet language="typescript" operationID="v3-threathunting-scans-get" method="get" path="/v3/threat-hunting/scans/{scan_id}" -->
+```typescript
+import { SDK } from "@censys/platform-sdk";
+
+const sdk = new SDK({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const result = await sdk.globalData.getTrackedScanThreatHunting({
+    scanId: "cd62e794-9f12-4c2f-b5b3-153853aaf8d9",
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { SDKCore } from "@censys/platform-sdk/core.js";
+import { globalDataGetTrackedScanThreatHunting } from "@censys/platform-sdk/funcs/globalDataGetTrackedScanThreatHunting.js";
+
+// Use `SDKCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const sdk = new SDKCore({
+  organizationId: "11111111-2222-3333-4444-555555555555",
+  personalAccessToken: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const res = await globalDataGetTrackedScanThreatHunting(sdk, {
+    scanId: "cd62e794-9f12-4c2f-b5b3-153853aaf8d9",
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("globalDataGetTrackedScanThreatHunting failed:", res.error);
+  }
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [operations.V3ThreathuntingScansGetRequest](../../models/operations/v3threathuntingscansgetrequest.md)                                                                         | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `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. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[operations.V3ThreathuntingScansGetResponse](../../models/operations/v3threathuntingscansgetresponse.md)\>**
+
+### Errors
+
 | Error Type               | Status Code              | Content Type             |
 | ------------------------ | ------------------------ | ------------------------ |
 | errors.ErrorModel        | 401, 403                 | application/problem+json |