@censys/platform-sdk 0.12.12 → 0.12.13

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 (142) hide show
  1. package/docs/sdks/adversaryinvestigation/README.md +8 -8
  2. package/docs/sdks/collections/README.md +5 -5
  3. package/docs/sdks/globaldata/README.md +19 -19
  4. package/docs/sdks/tagsandcomments/README.md +1 -1
  5. package/docs/sdks/threathunting/README.md +9 -9
  6. package/funcs/collectionsAggregate.d.ts +1 -1
  7. package/funcs/collectionsAggregate.js +1 -1
  8. package/funcs/collectionsCreate.d.ts +1 -1
  9. package/funcs/collectionsCreate.js +1 -1
  10. package/funcs/collectionsGet.d.ts +1 -1
  11. package/funcs/collectionsGet.js +1 -1
  12. package/funcs/collectionsListEvents.d.ts +1 -1
  13. package/funcs/collectionsListEvents.js +1 -1
  14. package/funcs/collectionsSearch.d.ts +1 -1
  15. package/funcs/collectionsSearch.js +1 -1
  16. package/funcs/globalDataAggregate.d.ts +1 -1
  17. package/funcs/globalDataAggregate.js +1 -1
  18. package/funcs/globalDataCreateTrackedScan.d.ts +1 -1
  19. package/funcs/globalDataCreateTrackedScan.js +1 -1
  20. package/funcs/globalDataGetCertificate.d.ts +1 -1
  21. package/funcs/globalDataGetCertificate.js +1 -1
  22. package/funcs/globalDataGetCertificateRaw.d.ts +1 -1
  23. package/funcs/globalDataGetCertificateRaw.js +1 -1
  24. package/funcs/globalDataGetCertificates.d.ts +1 -1
  25. package/funcs/globalDataGetCertificates.js +1 -1
  26. package/funcs/globalDataGetCertificatesRaw.d.ts +1 -1
  27. package/funcs/globalDataGetCertificatesRaw.js +1 -1
  28. package/funcs/globalDataGetHost.d.ts +1 -1
  29. package/funcs/globalDataGetHost.js +1 -1
  30. package/funcs/globalDataGetHostEnrichment.d.ts +1 -1
  31. package/funcs/globalDataGetHostEnrichment.js +1 -1
  32. package/funcs/globalDataGetHostTimeline.d.ts +1 -1
  33. package/funcs/globalDataGetHostTimeline.js +1 -1
  34. package/funcs/globalDataGetHosts.d.ts +1 -1
  35. package/funcs/globalDataGetHosts.js +1 -1
  36. package/funcs/globalDataGetTrackedScan.d.ts +1 -1
  37. package/funcs/globalDataGetTrackedScan.js +1 -1
  38. package/funcs/globalDataGetWebProperties.d.ts +1 -1
  39. package/funcs/globalDataGetWebProperties.js +1 -1
  40. package/funcs/globalDataGetWebProperty.d.ts +1 -1
  41. package/funcs/globalDataGetWebProperty.js +1 -1
  42. package/funcs/globalDataListDnsIpResolutionBounds.d.ts +1 -1
  43. package/funcs/globalDataListDnsIpResolutionBounds.js +1 -1
  44. package/funcs/globalDataListDnsIpResolutionRanges.d.ts +1 -1
  45. package/funcs/globalDataListDnsIpResolutionRanges.js +1 -1
  46. package/funcs/globalDataListDnsNameResolutionBounds.d.ts +1 -1
  47. package/funcs/globalDataListDnsNameResolutionBounds.js +1 -1
  48. package/funcs/globalDataListDnsNameResolutionRanges.d.ts +1 -1
  49. package/funcs/globalDataListDnsNameResolutionRanges.js +1 -1
  50. package/funcs/globalDataListServicesOnHost.d.ts +1 -1
  51. package/funcs/globalDataListServicesOnHost.js +1 -1
  52. package/funcs/globalDataSearch.d.ts +1 -1
  53. package/funcs/globalDataSearch.js +1 -1
  54. package/funcs/tagsAndCommentsUpdateTag.d.ts +1 -1
  55. package/funcs/tagsAndCommentsUpdateTag.js +1 -1
  56. package/funcs/threatHuntingCreateCenseyeJob.d.ts +1 -1
  57. package/funcs/threatHuntingCreateCenseyeJob.js +1 -1
  58. package/funcs/threatHuntingCreateInvestigationFileUpload.d.ts +1 -1
  59. package/funcs/threatHuntingCreateInvestigationFileUpload.js +1 -1
  60. package/funcs/threatHuntingCreateInvestigationJob.d.ts +1 -1
  61. package/funcs/threatHuntingCreateInvestigationJob.js +1 -1
  62. package/funcs/threatHuntingCreateTrackedScan.d.ts +1 -1
  63. package/funcs/threatHuntingCreateTrackedScan.js +1 -1
  64. package/funcs/threatHuntingGetCenseyeJobResults.d.ts +1 -1
  65. package/funcs/threatHuntingGetCenseyeJobResults.js +1 -1
  66. package/funcs/threatHuntingGetHostObservationsWithCertificate.d.ts +1 -1
  67. package/funcs/threatHuntingGetHostObservationsWithCertificate.js +1 -1
  68. package/funcs/threatHuntingGetTrackedScanThreatHunting.d.ts +1 -1
  69. package/funcs/threatHuntingGetTrackedScanThreatHunting.js +1 -1
  70. package/funcs/threatHuntingListThreats.d.ts +1 -1
  71. package/funcs/threatHuntingListThreats.js +1 -1
  72. package/funcs/threatHuntingValueCounts.d.ts +1 -1
  73. package/funcs/threatHuntingValueCounts.js +1 -1
  74. package/jsr.json +1 -1
  75. package/lib/config.d.ts +4 -4
  76. package/lib/config.js +4 -4
  77. package/models/components/http.d.ts +6 -0
  78. package/models/components/http.d.ts.map +1 -1
  79. package/models/components/http.js +4 -0
  80. package/models/components/http.js.map +1 -1
  81. package/models/components/httpcopyright.d.ts +17 -0
  82. package/models/components/httpcopyright.d.ts.map +1 -0
  83. package/models/components/httpcopyright.js +51 -0
  84. package/models/components/httpcopyright.js.map +1 -0
  85. package/models/components/index.d.ts +1 -0
  86. package/models/components/index.d.ts.map +1 -1
  87. package/models/components/index.js +1 -0
  88. package/models/components/index.js.map +1 -1
  89. package/package.json +1 -1
  90. package/sdk/adversaryinvestigation.d.ts +8 -8
  91. package/sdk/adversaryinvestigation.js +8 -8
  92. package/sdk/collections.d.ts +5 -5
  93. package/sdk/collections.js +5 -5
  94. package/sdk/globaldata.d.ts +19 -19
  95. package/sdk/globaldata.js +19 -19
  96. package/sdk/tagsandcomments.d.ts +1 -1
  97. package/sdk/tagsandcomments.js +1 -1
  98. package/sdk/threathunting.d.ts +9 -9
  99. package/sdk/threathunting.js +9 -9
  100. package/src/funcs/collectionsAggregate.ts +1 -1
  101. package/src/funcs/collectionsCreate.ts +1 -1
  102. package/src/funcs/collectionsGet.ts +1 -1
  103. package/src/funcs/collectionsListEvents.ts +1 -1
  104. package/src/funcs/collectionsSearch.ts +1 -1
  105. package/src/funcs/globalDataAggregate.ts +1 -1
  106. package/src/funcs/globalDataCreateTrackedScan.ts +1 -1
  107. package/src/funcs/globalDataGetCertificate.ts +1 -1
  108. package/src/funcs/globalDataGetCertificateRaw.ts +1 -1
  109. package/src/funcs/globalDataGetCertificates.ts +1 -1
  110. package/src/funcs/globalDataGetCertificatesRaw.ts +1 -1
  111. package/src/funcs/globalDataGetHost.ts +1 -1
  112. package/src/funcs/globalDataGetHostEnrichment.ts +1 -1
  113. package/src/funcs/globalDataGetHostTimeline.ts +1 -1
  114. package/src/funcs/globalDataGetHosts.ts +1 -1
  115. package/src/funcs/globalDataGetTrackedScan.ts +1 -1
  116. package/src/funcs/globalDataGetWebProperties.ts +1 -1
  117. package/src/funcs/globalDataGetWebProperty.ts +1 -1
  118. package/src/funcs/globalDataListDnsIpResolutionBounds.ts +1 -1
  119. package/src/funcs/globalDataListDnsIpResolutionRanges.ts +1 -1
  120. package/src/funcs/globalDataListDnsNameResolutionBounds.ts +1 -1
  121. package/src/funcs/globalDataListDnsNameResolutionRanges.ts +1 -1
  122. package/src/funcs/globalDataListServicesOnHost.ts +1 -1
  123. package/src/funcs/globalDataSearch.ts +1 -1
  124. package/src/funcs/tagsAndCommentsUpdateTag.ts +1 -1
  125. package/src/funcs/threatHuntingCreateCenseyeJob.ts +1 -1
  126. package/src/funcs/threatHuntingCreateInvestigationFileUpload.ts +1 -1
  127. package/src/funcs/threatHuntingCreateInvestigationJob.ts +1 -1
  128. package/src/funcs/threatHuntingCreateTrackedScan.ts +1 -1
  129. package/src/funcs/threatHuntingGetCenseyeJobResults.ts +1 -1
  130. package/src/funcs/threatHuntingGetHostObservationsWithCertificate.ts +1 -1
  131. package/src/funcs/threatHuntingGetTrackedScanThreatHunting.ts +1 -1
  132. package/src/funcs/threatHuntingListThreats.ts +1 -1
  133. package/src/funcs/threatHuntingValueCounts.ts +1 -1
  134. package/src/lib/config.ts +4 -4
  135. package/src/models/components/http.ts +9 -0
  136. package/src/models/components/httpcopyright.ts +39 -0
  137. package/src/models/components/index.ts +1 -0
  138. package/src/sdk/adversaryinvestigation.ts +8 -8
  139. package/src/sdk/collections.ts +5 -5
  140. package/src/sdk/globaldata.ts +19 -19
  141. package/src/sdk/tagsandcomments.ts +1 -1
  142. package/src/sdk/threathunting.ts +9 -9
@@ -30,7 +30,7 @@ import { Result } from "../types/fp.js";
30
30
  * List active threats
31
31
  *
32
32
  * @remarks
33
- * 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.
33
+ * Retrieve a list of active threats observed by Censys by aggregating threat IDs across hosts and web properties. Use this endpoint to see currently active threats so you can prioritize which malicious infrastructure to hunt or block first.<br><br>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.
34
34
  */
35
35
  export function threatHuntingListThreats(
36
36
  client: SDKCore,
@@ -30,7 +30,7 @@ import { Result } from "../types/fp.js";
30
30
  * CensEye: Retrieve value counts to discover pivots
31
31
  *
32
32
  * @remarks
33
- * 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.
33
+ * 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>Use this endpoint to see how many assets share a given field value, so you can tell which attributes are rare enough to pivot on and which are too common to be useful.<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.
34
34
  */
35
35
  export function threatHuntingValueCounts(
36
36
  client: SDKCore,
package/src/lib/config.ts CHANGED
@@ -65,9 +65,9 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
65
65
 
66
66
  export const SDK_METADATA = {
67
67
  language: "typescript",
68
- openapiDocVersion: "1.0.157",
69
- sdkVersion: "0.12.12",
70
- genVersion: "2.954.8",
68
+ openapiDocVersion: "1.0.161",
69
+ sdkVersion: "0.12.13",
70
+ genVersion: "2.956.1",
71
71
  userAgent:
72
- "speakeasy-sdk/typescript 0.12.12 2.954.8 1.0.157 @censys/platform-sdk",
72
+ "speakeasy-sdk/typescript 0.12.13 2.956.1 1.0.161 @censys/platform-sdk",
73
73
  } as const;
@@ -7,6 +7,7 @@ import { remap as remap$ } from "../../lib/primitives.js";
7
7
  import { safeParse } from "../../lib/schemas.js";
8
8
  import { Result as SafeParseResult } from "../../types/fp.js";
9
9
  import { SDKValidationError } from "../errors/sdkvalidationerror.js";
10
+ import { HttpCopyright, HttpCopyright$inboundSchema } from "./httpcopyright.js";
10
11
  import { HttpFavicon, HttpFavicon$inboundSchema } from "./httpfavicon.js";
11
12
  import {
12
13
  HttpRedirectChainLink,
@@ -30,7 +31,12 @@ export type Http = {
30
31
  * The length, in bytes, of services.http.response.body; at most, 64KB.
31
32
  */
32
33
  bodySize?: number | undefined;
34
+ /**
35
+ * Copyright notices declared by or found in the page, the one most likely to be the site's own first.
36
+ */
37
+ copyrights?: Array<HttpCopyright> | null | undefined;
33
38
  favicons?: Array<HttpFavicon> | null | undefined;
39
+ googleSiteVerification?: Array<string> | null | undefined;
34
40
  /**
35
41
  * The key-value header pairs included in the response.
36
42
  */
@@ -75,7 +81,9 @@ export const Http$inboundSchema: z.ZodType<Http, z.ZodTypeDef, unknown> = z
75
81
  body_hash_sha256: z.string().optional(),
76
82
  body_hash_tlsh: z.string().optional(),
77
83
  body_size: z.number().int().optional(),
84
+ copyrights: z.nullable(z.array(HttpCopyright$inboundSchema)).optional(),
78
85
  favicons: z.nullable(z.array(HttpFavicon$inboundSchema)).optional(),
86
+ google_site_verification: z.nullable(z.array(z.string())).optional(),
79
87
  headers: z.record(HttpRepeatedHeaders$inboundSchema).optional(),
80
88
  html_tags: z.nullable(z.array(z.string())).optional(),
81
89
  html_title: z.string().optional(),
@@ -93,6 +101,7 @@ export const Http$inboundSchema: z.ZodType<Http, z.ZodTypeDef, unknown> = z
93
101
  "body_hash_sha256": "bodyHashSha256",
94
102
  "body_hash_tlsh": "bodyHashTlsh",
95
103
  "body_size": "bodySize",
104
+ "google_site_verification": "googleSiteVerification",
96
105
  "html_tags": "htmlTags",
97
106
  "html_title": "htmlTitle",
98
107
  "network_log": "networkLog",
@@ -0,0 +1,39 @@
1
+ /*
2
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
3
+ */
4
+
5
+ import * as z from "zod/v3";
6
+ import { safeParse } from "../../lib/schemas.js";
7
+ import { Result as SafeParseResult } from "../../types/fp.js";
8
+ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
9
+
10
+ export type HttpCopyright = {
11
+ /**
12
+ * Where in the response the notice was found: meta (a copyright meta tag) or body (text matched in the response body).
13
+ */
14
+ source?: string | undefined;
15
+ /**
16
+ * The copyright notice as it appears in the response.
17
+ */
18
+ text?: string | undefined;
19
+ };
20
+
21
+ /** @internal */
22
+ export const HttpCopyright$inboundSchema: z.ZodType<
23
+ HttpCopyright,
24
+ z.ZodTypeDef,
25
+ unknown
26
+ > = z.object({
27
+ source: z.string().optional(),
28
+ text: z.string().optional(),
29
+ });
30
+
31
+ export function httpCopyrightFromJSON(
32
+ jsonString: string,
33
+ ): SafeParseResult<HttpCopyright, SDKValidationError> {
34
+ return safeParse(
35
+ jsonString,
36
+ (x) => HttpCopyright$inboundSchema.parse(JSON.parse(x)),
37
+ `Failed to parse 'HttpCopyright' from JSON`,
38
+ );
39
+ }
@@ -251,6 +251,7 @@ export * from "./hosttimeline.js";
251
251
  export * from "./hosttimelineevent.js";
252
252
  export * from "./hosttimelineeventasset.js";
253
253
  export * from "./http.js";
254
+ export * from "./httpcopyright.js";
254
255
  export * from "./httpfavicon.js";
255
256
  export * from "./httpredirectchainlink.js";
256
257
  export * from "./httpredirectchainlinkhttpstatus.js";
@@ -24,7 +24,7 @@ export class AdversaryInvestigation extends ClientSDK {
24
24
  * CensEye: Create a pivot analysis job
25
25
  *
26
26
  * @remarks
27
- * Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate. The job extracts [default pivot fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#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.<br><br>This endpoint costs 44 credits to execute for a host, 28 credits to execute for a web property, and 7 credits to execute for a certificate.
27
+ * Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate. The job extracts [default pivot fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#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>Use this endpoint to start an analysis of a suspicious host, web property, or certificate that finds the rare attributes it shares with other assets, so you can uncover related attacker infrastructure.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint costs 44 credits to execute for a host, 28 credits to execute for a web property, and 7 credits to execute for a certificate.
28
28
  */
29
29
  async createCenseyeJob(
30
30
  request: operations.V3ThreathuntingCenseyeJobsCreateRequest,
@@ -58,7 +58,7 @@ export class AdversaryInvestigation extends ClientSDK {
58
58
  * CensEye: Get job results
59
59
  *
60
60
  * @remarks
61
- * 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.
61
+ * Retrieve the results of a completed CensEye pivot analysis job. Use this endpoint to retrieve the pivots from a finished job, then turn the most distinctive ones into searches or blocklist candidates.<br><br>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.
62
62
  */
63
63
  async getCenseyeJobResults(
64
64
  request: operations.V3ThreathuntingCenseyeJobResultsRequest,
@@ -75,7 +75,7 @@ export class AdversaryInvestigation extends ClientSDK {
75
75
  * Get host history for a certificate
76
76
  *
77
77
  * @remarks
78
- * 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.<br><br>For workspaces with a history limit, the API returns observation ranges that overlap the allowed history window. The window starts at 00:00 UTC the allowed number of days ago and ends at the time of the request. Ranges are returned in full, with their original start and end times, even if they extend outside the window.<br><br>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. This endpoint costs one credit per page of results.
78
+ * Retrieve the historical observations of hosts associated with a certificate. Use this endpoint to see every host that has presented a given certificate over time, so you can build a timeline and find other infrastructure using it.<br><br>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.<br><br>For workspaces with a history limit, the API returns observation ranges that overlap the allowed history window. The window starts at 00:00 UTC the allowed number of days ago and ends at the time of the request. Ranges are returned in full, with their original start and end times, even if they extend outside the window.<br><br>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. This endpoint costs one credit per page of results.
79
79
  */
80
80
  async getHostObservationsWithCertificate(
81
81
  request:
@@ -95,7 +95,7 @@ export class AdversaryInvestigation extends ClientSDK {
95
95
  * Investigations: Create file upload
96
96
  *
97
97
  * @remarks
98
- * Prepare to attach an evidence file to an investigation. This endpoint does not accept the file. It returns a URL to send the file to and an identifier to pass to the [create job endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-jobs-create) afterwards.<br><br>Upload the file with an HTTP PUT to `upload_url` and send `upload_headers` exactly as returned by this endpoint. The URL grants access to that one file and stops working at `expire_time`; a file uploaded before that stays usable afterwards. Prepare one upload per file.<br><br>Start the investigation promptly after uploading. There is a limit on how many uploaded files you may hold without using them and starting an investigation from a file releases its slot. A file that no investigation references is discarded once it passes the service's retention window for unused uploads. A file an investigation does reference is kept with that investigation for as long as the investigation itself.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint does not cost any credits to execute.
98
+ * Prepare to attach an evidence file to an investigation. Use this endpoint to stage evidence, such as logs, malware reports, or alert exports, so an AI investigation can use it.<br><br>This endpoint does not accept the file. It returns a URL to send the file to and an identifier to pass to the [create job endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-jobs-create) afterwards.<br><br>Upload the file with an HTTP PUT to `upload_url` and send `upload_headers` exactly as returned by this endpoint. The URL grants access to that one file and stops working at `expire_time`; a file uploaded before that stays usable afterwards. Prepare one upload per file.<br><br>Start the investigation promptly after uploading. There is a limit on how many uploaded files you may hold without using them and starting an investigation from a file releases its slot. A file that no investigation references is discarded once it passes the service's retention window for unused uploads. A file an investigation does reference is kept with that investigation for as long as the investigation itself.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint does not cost any credits to execute.
99
99
  */
100
100
  async createInvestigationFileUpload(
101
101
  request: operations.V3ThreathuntingInvestigationsFilesCreateRequest,
@@ -129,7 +129,7 @@ export class AdversaryInvestigation extends ClientSDK {
129
129
  * Investigations: Create job
130
130
  *
131
131
  * @remarks
132
- * Start an [AI investigation](https://docs.censys.com/docs/platform-ai-investigations) from a set of indicators, a set of previously uploaded evidence files, or both. Supply at least one `indicators` or `file_ids`. To use files, upload them first with the [create file upload endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-files-create).<br><br>This endpoint returns a `job_id` that you can poll to retrieve its status and results.<br><br>Provide `start_time` and `end_time` to scope the investigation to a time frame, or `start_time` alone to scope it from that time up to now. Omit both to investigate current data.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
132
+ * Start an [AI investigation](https://docs.censys.com/docs/platform-ai-investigations) from a set of indicators, a set of previously uploaded evidence files, or both to obtain a report on suspect infrastructure without doing the pivots by hand.<br><br>Supply at least one `indicators` or `file_ids`. To use files, upload them first with the [create file upload endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-files-create).<br><br>This endpoint returns a `job_id` that you can poll to retrieve its status and results.<br><br>Provide `start_time` and `end_time` to scope the investigation to a time frame, or `start_time` alone to scope it from that time up to now. Omit both to investigate current data.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
133
133
  */
134
134
  async createInvestigationJob(
135
135
  request: operations.V3ThreathuntingInvestigationsJobsCreateRequest,
@@ -197,7 +197,7 @@ export class AdversaryInvestigation extends ClientSDK {
197
197
  * Live Discovery: Initiate a new scan
198
198
  *
199
199
  * @remarks
200
- * 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.
200
+ * 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>Use this endpoint to scan for a service at an `ip:port` or `hostname:port`, such as a new IOC from an incident, so you can get data on it right away.<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module. It costs 15 credits to execute this endpoint.
201
201
  */
202
202
  async createTrackedScan(
203
203
  request: operations.V3ThreathuntingScansDiscoveryRequest,
@@ -214,7 +214,7 @@ export class AdversaryInvestigation extends ClientSDK {
214
214
  * List active threats
215
215
  *
216
216
  * @remarks
217
- * 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.
217
+ * Retrieve a list of active threats observed by Censys by aggregating threat IDs across hosts and web properties. Use this endpoint to see currently active threats so you can prioritize which malicious infrastructure to hunt or block first.<br><br>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.
218
218
  */
219
219
  async listThreats(
220
220
  request: operations.V3ThreathuntingThreatsListRequest,
@@ -231,7 +231,7 @@ export class AdversaryInvestigation extends ClientSDK {
231
231
  * CensEye: Retrieve value counts to discover pivots
232
232
  *
233
233
  * @remarks
234
- * 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.
234
+ * 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>Use this endpoint to see how many assets share a given field value, so you can tell which attributes are rare enough to pivot on and which are too common to be useful.<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.
235
235
  */
236
236
  async valueCounts(
237
237
  request: operations.V3ThreathuntingValueCountsRequest,
@@ -41,7 +41,7 @@ export class Collections extends ClientSDK {
41
41
  * Create a collection
42
42
  *
43
43
  * @remarks
44
- * Create a new collection.<br><br>This endpoint does not cost credits to execute.
44
+ * Create a new [collection](https://docs.censys.com/docs/platform-collections).<br><br>In a SOC environment, use this endpoint to save a query as a dynamic asset group, such as all internet-facing RDP hosts or a threat's footprint, so SOC monitoring and reporting stay scoped as assets change.<br><br>This endpoint does not cost credits to execute.
45
45
  */
46
46
  async create(
47
47
  request: operations.V3CollectionsCrudCreateRequest,
@@ -75,7 +75,7 @@ export class Collections extends ClientSDK {
75
75
  * Get a collection
76
76
  *
77
77
  * @remarks
78
- * Retrieve information about a collection. Retrieved information includes its name, query, description, status, and asset count.<br><br>This endpoint does not cost credits to execute.
78
+ * Retrieve information about a collection. Retrieved information includes its name, query, description, status, and asset count. Use it to confirm it still reflects the scope you intend to monitor.<br><br>This endpoint does not cost credits to execute.
79
79
  */
80
80
  async get(
81
81
  request: operations.V3CollectionsCrudGetRequest,
@@ -109,7 +109,7 @@ export class Collections extends ClientSDK {
109
109
  * Get a collection's events
110
110
  *
111
111
  * @remarks
112
- * Retrieve the event history for a collection. This includes the addition or removal of assets as well as collection status changes.<br><br>This endpoint does not cost credits to execute.
112
+ * Retrieve the event history for a collection. This includes the addition or removal of assets as well as collection status changes.<br><br>In a SOC environment, use this endpoint to see which assets were added or removed and when, to catch new exposure or unexpected changes in a monitored scope.<br><br>This endpoint does not cost credits to execute.
113
113
  */
114
114
  async listEvents(
115
115
  request: operations.V3CollectionsListEventsRequest,
@@ -126,7 +126,7 @@ export class Collections extends ClientSDK {
126
126
  * Aggregate results for a search query within a collection
127
127
  *
128
128
  * @remarks
129
- * Aggregate results for a Platform search query that targets a collection's assets. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.
129
+ * Aggregate results for a Platform search query that targets a collection's assets. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.<br><br>In a SOC environment, use this endpoint to count and bucket matches by field, such as port, country, or software, inside a collection so you can spot exposure trends without pulling every asset.
130
130
  */
131
131
  async aggregate(
132
132
  request: operations.V3CollectionsSearchAggregateRequest,
@@ -143,7 +143,7 @@ export class Collections extends ClientSDK {
143
143
  * Run a search query within a collection
144
144
  *
145
145
  * @remarks
146
- * Run a search query across a collection's assets. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax. Host services that match your search criteria will be returned in a `matched_services` object.
146
+ * Run a search query across a collection's assets. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax. Host services that match your search criteria will be returned in a `matched_services` object.<br><br>In a SOC environment, use this endpoint to search only within the defined scope of a collection, so triage and hunting results stay relevant instead of covering the whole internet.
147
147
  */
148
148
  async search(
149
149
  request: operations.V3CollectionsSearchQueryRequest,
@@ -32,7 +32,7 @@ export class GlobalData extends ClientSDK {
32
32
  * Retrieve multiple certificates
33
33
  *
34
34
  * @remarks
35
- * Retrieve information about multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
35
+ * Retrieve information about multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint.<br><br>In a SOC environment, use this endpoint to bulk-check multiple certificates from network telemetry for self-signed, newly issued, or lookalike certs.
36
36
  */
37
37
  async getCertificates(
38
38
  request: operations.V3GlobaldataAssetCertificateListPostRequest,
@@ -49,7 +49,7 @@ export class GlobalData extends ClientSDK {
49
49
  * Retrieve multiple certificates in PEM format
50
50
  *
51
51
  * @remarks
52
- * Retrieve the raw PEM-encoded format for multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
52
+ * Retrieve the raw PEM-encoded format for multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint.<br><br>Use this endpoint to export raw PEMs for multiple certificates at once, for bulk analysis or sharing with your detection pipeline.
53
53
  */
54
54
  async getCertificatesRaw(
55
55
  request: operations.V3GlobaldataAssetCertificateListRawPostRequest,
@@ -66,7 +66,7 @@ export class GlobalData extends ClientSDK {
66
66
  * Get a certificate
67
67
  *
68
68
  * @remarks
69
- * Retrieve information about a single certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
69
+ * Retrieve information about a single certificate. A certificate ID is its SHA-256 fingerprint.<br><br>In a SOC environment, use this endpoint to look up a certificate by SHA-256 fingerprint to see its subject, issuer, and validity, so you can vet certs seen in TLS logs or alerts.
70
70
  */
71
71
  async getCertificate(
72
72
  request: operations.V3GlobaldataAssetCertificateRequest,
@@ -83,7 +83,7 @@ export class GlobalData extends ClientSDK {
83
83
  * Get a certificate in PEM format
84
84
  *
85
85
  * @remarks
86
- * Retrieve the raw PEM-encoded format of a certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
86
+ * Retrieve the raw PEM-encoded format of a certificate. A certificate ID is its SHA-256 fingerprint.<br><br>Use this endpoint to retrieve the raw PEM of a suspicious certificate for offline analysis or to feed other tooling.
87
87
  */
88
88
  async getCertificateRaw(
89
89
  request: operations.V3GlobaldataAssetCertificateRawRequest,
@@ -100,7 +100,7 @@ export class GlobalData extends ClientSDK {
100
100
  * Get host enrichment
101
101
  *
102
102
  * @remarks
103
- * Retrieve enrichment data for a single host. This endpoint is optimized for high-volume SOC enrichment use cases.<br><br>This endpoint does not consume standard Censys credits. Core organizations may perform up to 20,000 enrichment calls per day. Core + Unlimited Enrichment organizations may perform an unlimited amount of enrichment calls per day.<br><br>[Learn more about the enrichment API here](https://docs.censys.com/docs/host-enrichment).
103
+ * Retrieve enrichment data for a single host. This endpoint is optimized for high-volume SOC enrichment use cases.<br><br>Use this endpoint to add Censys context (location, ASN, labels, reputation, and more) to IPs in your SIEM or SOAR at high volume, without spending standard credits.<br><br>This endpoint does not consume standard Censys credits. Core organizations may perform up to 20,000 enrichment calls per day. Core + Unlimited Enrichment organizations may perform an unlimited amount of enrichment calls per day.<br><br>[Learn more about the enrichment API here](https://docs.censys.com/docs/host-enrichment).
104
104
  */
105
105
  async getHostEnrichment(
106
106
  request: operations.V3GlobaldataAssetHostEnrichmentRequest,
@@ -117,7 +117,7 @@ export class GlobalData extends ClientSDK {
117
117
  * Retrieve multiple hosts
118
118
  *
119
119
  * @remarks
120
- * Retrieve information about multiple hosts. You can retrieve up to 100 hosts per call. A host ID is its IP address.
120
+ * Retrieve information about multiple hosts. You can retrieve up to 100 hosts per call. A host ID is its IP address.<br><br>In a SOC environment, use this endpoint to look up multiple IPs from an alert, log, or threat feed in one call, so you can triage a whole indicator list quickly.
121
121
  */
122
122
  async getHosts(
123
123
  request: operations.V3GlobaldataAssetHostListPostRequest,
@@ -134,7 +134,7 @@ export class GlobalData extends ClientSDK {
134
134
  * Get a host
135
135
  *
136
136
  * @remarks
137
- * Retrieve information about a single host. A host ID is its IP address.
137
+ * Retrieve information about a single host. A host ID is its IP address.<br><br>In a SOC environment, use this endpoint to pull the current services, software, certificates, and labels on an IP from an alert, so you can quickly judge whether it is malicious or benign.
138
138
  */
139
139
  async getHost(
140
140
  request: operations.V3GlobaldataAssetHostRequest,
@@ -151,7 +151,7 @@ export class GlobalData extends ClientSDK {
151
151
  * Get service history for a host
152
152
  *
153
153
  * @remarks
154
- * Retrieve historical service observations for a host. This endpoint returns time ranges during which services were detected on the host.<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.<br><br>You can filter by port number, protocol, and transport protocol.
154
+ * Retrieve historical service observations for a host. This endpoint returns time ranges during which services were detected on the host.<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.<br><br>You can filter by port number, protocol, and transport protocol.<br><br>In a SOC environment, use this endpoint to see when a specific service was exposed on an IP, so you can check whether it was live during the window of a suspected incident.
155
155
  */
156
156
  async listServicesOnHost(
157
157
  request: operations.V3GlobaldataServiceOnHostRequest,
@@ -168,7 +168,7 @@ export class GlobalData extends ClientSDK {
168
168
  * Get host event history
169
169
  *
170
170
  * @remarks
171
- * Retrieve event history for a host. A host ID is its IP address.<br><br>Note that when a service protocol changes after a new scan (for example, from `UNKNOWN` to `NETBIOS`), this information will be reflected in the `scan` object.
171
+ * Retrieve event history for a host. A host ID is its IP address.<br><br>Note that when a service protocol changes after a new scan (for example, from `UNKNOWN` to `NETBIOS`), this information will be reflected in the `scan` object.<br><br>In a SOC environment, use this endpoint to see what changed on an IP over time, such as new services, certificate swaps, and software changes, to reconstruct when attacker infrastructure was stood up or modified.
172
172
  */
173
173
  async getHostTimeline(
174
174
  request: operations.V3GlobaldataAssetHostTimelineRequest,
@@ -185,7 +185,7 @@ export class GlobalData extends ClientSDK {
185
185
  * Retrieve multiple web properties
186
186
  *
187
187
  * @remarks
188
- * Retrieve information about multiple web properties. You can retrieve up to 100 web properties per call. Web properties are identified using a combination of a hostname and port joined with a colon, such as `platform.censys.io:80`.
188
+ * Retrieve information about multiple web properties. You can retrieve up to 100 web properties per call. Web properties are identified using a combination of a hostname and port joined with a colon, such as `platform.censys.io:80`.<br><br>In a SOC environment, use this endpoint to check up to 100 suspicious hostnames at once, such as domains from phishing reports or proxy logs, to find the live and malicious ones.
189
189
  */
190
190
  async getWebProperties(
191
191
  request: operations.V3GlobaldataAssetWebpropertyListPostRequest,
@@ -202,7 +202,7 @@ export class GlobalData extends ClientSDK {
202
202
  * Get a web property
203
203
  *
204
204
  * @remarks
205
- * Retrieve information about a single web property. Web properties are identified using a combination of a hostname and port joined with a colon, such as `platform.censys.io:80`.
205
+ * Retrieve information about a single web property. Web properties are identified using a combination of a hostname and port joined with a colon, such as `platform.censys.io:80`.<br><br>In a SOC environment, use this endpoint to inspect the current content, technologies, and certificate for a hostname and port from a phishing or C2 alert.
206
206
  */
207
207
  async getWebProperty(
208
208
  request: operations.V3GlobaldataAssetWebpropertyRequest,
@@ -236,7 +236,7 @@ export class GlobalData extends ClientSDK {
236
236
  * Get DNS names that resolved to an IP (aggregated bounds)
237
237
  *
238
238
  * @remarks
239
- * Retrieve the domain names that resolved to an IP during a time frame. You can narrow results with `record_types` (A or AAAA).<br><br>Results are aggregated per domain name and multiple distinct ranges for a name will be grouped into one row of results. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will group those ranges into one entry for `censys.com` in the response.<br><br>To retrieve domain names for an IP with each record broken down by time range, use the [ranges endpoint](https://docs.censys.com/reference/v3-globaldata-dns-ip-resolution-ranges)<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
239
+ * Retrieve the domain names that resolved to an IP during a time frame. You can narrow results with `record_types` (A or AAAA).<br><br>Results are aggregated per domain name and multiple distinct ranges for a name will be grouped into one row of results. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will group those ranges into one entry for `censys.com` in the response.<br><br>To retrieve domain names for an IP with each record broken down by time range, use the [ranges endpoint](https://docs.censys.com/reference/v3-globaldata-dns-ip-resolution-ranges)<br><br>In a SOC environment, use this endpoint to find every domain that has pointed at a malicious IP, with first- and last-seen bounds per name, so you can discover related domains and block them.<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
240
240
  */
241
241
  async listDnsIpResolutionBounds(
242
242
  request: operations.V3GlobaldataDnsIpResolutionBoundRequest,
@@ -253,7 +253,7 @@ export class GlobalData extends ClientSDK {
253
253
  * Get DNS names that resolved to an IP (ranges)
254
254
  *
255
255
  * @remarks
256
- * Retrieve the domain names that resolved to an IP during a time frame. You can narrow results with `record_types` (A or AAAA).<br><br>Record results are broken down based on time range. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will return one row for each of those distinct ranges.<br><br>To retrieve domain names for an IP with each result aggregated by name, use the [bounds endpoint endpoint](https://docs.censys.com/reference/v3-globaldata-dns-ip-resolution-bound).<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
256
+ * Retrieve the domain names that resolved to an IP during a time frame. You can narrow results with `record_types` (A or AAAA).<br><br>Record results are broken down based on time range. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will return one row for each of those distinct ranges.<br><br>To retrieve domain names for an IP with each result aggregated by name, use the [bounds endpoint endpoint](https://docs.censys.com/reference/v3-globaldata-dns-ip-resolution-bound).<br><br>In a SOC environment, use this endpoint to see the exact time ranges a domain resolved to an IP, to confirm it was active during the incident window or to spot infrastructure reuse.<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
257
257
  */
258
258
  async listDnsIpResolutionRanges(
259
259
  request: operations.V3GlobaldataDnsIpResolutionRangesRequest,
@@ -270,7 +270,7 @@ export class GlobalData extends ClientSDK {
270
270
  * Get DNS resolution records for a name (aggregated bounds)
271
271
  *
272
272
  * @remarks
273
- * Retrieve the DNS resolution records for a name. This endpoint returns observed A, AAAA, MX, NS, SOA, and TXT records for the name you provide. You can filter by one or more record types using record_types.<br><br>Results are aggregated per record distinct ranges for a record will be grouped into one row of results. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will group those ranges into one entry for the `1.1.1.1` A record in the response.<br><br>To retrieve records for a name with each record broken down by time range, use the [ranges endpoint](https://docs.censys.com/reference/v3-globaldata-dns-name-resolution-ranges).<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
273
+ * Retrieve the DNS resolution records for a name. This endpoint returns observed A, AAAA, MX, NS, SOA, and TXT records for the name you provide. You can filter by one or more record types using record_types.<br><br>Results are aggregated per record distinct ranges for a record will be grouped into one row of results. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will group those ranges into one entry for the `1.1.1.1` A record in the response.<br><br>To retrieve records for a name with each record broken down by time range, use the [ranges endpoint](https://docs.censys.com/reference/v3-globaldata-dns-name-resolution-ranges).<br><br>In a SOC environment, use this endpoint to see the A, AAAA, MX, NS, SOA, and TXT records observed for a suspicious domain, to pivot to its hosting and mail infrastructure.<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
274
274
  */
275
275
  async listDnsNameResolutionBounds(
276
276
  request: operations.V3GlobaldataDnsNameResolutionBoundRequest,
@@ -287,7 +287,7 @@ export class GlobalData extends ClientSDK {
287
287
  * Get DNS resolution records for a name (ranges)
288
288
  *
289
289
  * @remarks
290
- * Retrieve the records that resolved for a name during a time frame. This endpoint returns observed A, AAAA, MX, NS, SOA, and TXT records for the name you provide. You can filter by one or more record types using `record_types`.<br><br>Record results are broken down based on time range. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will return one row for each of those distinct ranges for the `1.1.1.1` A record.<br><br>To retrieve records for a name with each result aggregated per record, use the [bounds endpoint endpoint](https://docs.censys.com/reference/v3-globaldata-dns-name-resolution-bound).<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
290
+ * Retrieve the records that resolved for a name during a time frame. This endpoint returns observed A, AAAA, MX, NS, SOA, and TXT records for the name you provide. You can filter by one or more record types using `record_types`.<br><br>Record results are broken down based on time range. For example, if `censys.com` resolved to `1.1.1.1` from January 1 to January 7 during two different ranges of January 1 to January 3 and January 5 to January 7, and you targeted January 1 through January 7 with your API call, then this endpoint will return one row for each of those distinct ranges for the `1.1.1.1` A record.<br><br>To retrieve records for a name with each result aggregated per record, use the [bounds endpoint endpoint](https://docs.censys.com/reference/v3-globaldata-dns-name-resolution-bound).<br><br>In a SOC environment, use this endpoint to see when a domain's records changed over time, such as a sudden hosting move after takedown.<br><br>This endpoint is only available to organizations on the Censys Search and Censys Core plans.<br><br>[Learn more about Censys Active DNS](https://docs.censys.com/docs/platform-active-dns).
291
291
  */
292
292
  async listDnsNameResolutionRanges(
293
293
  request: operations.V3GlobaldataDnsNameResolutionRangesRequest,
@@ -304,7 +304,7 @@ export class GlobalData extends ClientSDK {
304
304
  * Live Rescan: Initiate a new rescan
305
305
  *
306
306
  * @remarks
307
- * Initiate a rescan for a known host service at a specific IP and port (`ip:port`) or hostname and port (`hostname:port`). This is equivalent to the [Live Rescan](https://docs.censys.com/docs/platform-live-rescan#/) 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-globaldata-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 all Enterprise customers. It costs 10 credits to execute.
307
+ * Initiate a rescan for a known host service at a specific IP and port (`ip:port`) or hostname and port (`hostname:port`). This is equivalent to the [Live Rescan](https://docs.censys.com/docs/platform-live-rescan#/) 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-globaldata-scans-get#/). After the scan completes, perform a lookup on the target asset to retrieve detailed scan information.<br><br>In a SOC environment, rescan to ensure triage, an investigation, or a hunt has the most accurate and current state. This includes information like whether C2 servers are still operational, or whether an organization's asset is still exposed to the internet.<br><br>This endpoint is available to all Enterprise customers. It costs 10 credits to execute.
308
308
  */
309
309
  async createTrackedScan(
310
310
  request: operations.V3GlobaldataScansRescanRequest,
@@ -321,7 +321,7 @@ export class GlobalData extends ClientSDK {
321
321
  * Get scan status
322
322
  *
323
323
  * @remarks
324
- * Retrieve the current status of a scan by its ID. This endpoint works for both [Live Discovery scans](https://docs.censys.com/reference/v3-threathunting-scans-discovery#/) and [Live Rescans](https://docs.censys.com/reference/v3-globaldata-scans-rescan#/).<br><br>If the scan was successful, perform a lookup on the target asset to retrieve detailed scan information.<br><br>This endpoint is available to all Enterprise customers. This endpoint does not cost any credits to execute.
324
+ * Retrieve the current status of a scan by its ID. This endpoint works for both [Live Discovery scans](https://docs.censys.com/reference/v3-threathunting-scans-discovery#/) and [Live Rescans](https://docs.censys.com/reference/v3-globaldata-scans-rescan#/).<br><br>Use this endpoint to check whether a Live Discovery or Live Rescan scan has finished, so automation knows when fresh data is ready to pull.<br><br>If the scan was successful, perform a lookup on the target asset to retrieve detailed scan information.<br><br>This endpoint is available to all enterprise customers. This endpoint does not cost any credits to execute.
325
325
  */
326
326
  async getTrackedScan(
327
327
  request: operations.V3GlobaldataScansGetRequest,
@@ -338,7 +338,7 @@ export class GlobalData extends ClientSDK {
338
338
  * Aggregate results for a search query
339
339
  *
340
340
  * @remarks
341
- * 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.
341
+ * 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.<br><br>In a SOC environment, use this endpoint to count and bucket matches by field, such as country, ASN, or port, to size a campaign or spot where malicious infrastructure clusters without pulling every record.
342
342
  */
343
343
  async aggregate(
344
344
  request: operations.V3GlobaldataSearchAggregateRequest,
@@ -372,7 +372,7 @@ export class GlobalData extends ClientSDK {
372
372
  * Run a search query
373
373
  *
374
374
  * @remarks
375
- * Run a search query across Censys data. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax. Host services that match your search criteria will be returned in a `matched_services` object.
375
+ * Run a search query across Censys data. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax.<br><br>Host services that match your search criteria will be returned in a `matched_services` object.<br><br>In a SOC environment, use this endpoint to hunt for hosts, web properties, or certificates that match an indicator, such as a C2 banner, JARM, or favicon hash to scope infrastructure tied to an alert.
376
376
  */
377
377
  async search(
378
378
  request: operations.V3GlobaldataSearchQueryRequest,
@@ -181,7 +181,7 @@ export class TagsAndComments extends ClientSDK {
181
181
  * Update a tag
182
182
  *
183
183
  * @remarks
184
- * Update an existing tag in your organization. Only the fields provided in the request body will be updated; omitted fields are left unchanged.<br><br>Only the tag's creator or an organization admin can update a `private` tag. Tags with the `shared` setting can be updated by any organization member.<br><br>This endpoint does not cost any credits to execute.
184
+ * Update an existing tag in your organization. Only the fields provided in the request body will be updated; omitted fields are left unchanged.<br><br>Only the tag's creator or an organization admin can update a `private` tag. Tags with the `shared` setting can be updated by any organization member. A `shared` tag cannot be made `private`.<br><br>This endpoint does not cost any credits to execute.
185
185
  */
186
186
  async updateTag(
187
187
  request: operations.V3TagsUpdateTagRequest,
@@ -43,7 +43,7 @@ export class ThreatHunting extends ClientSDK {
43
43
  * CensEye: Create a pivot analysis job
44
44
  *
45
45
  * @remarks
46
- * Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate. The job extracts [default pivot fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#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.<br><br>This endpoint costs 44 credits to execute for a host, 28 credits to execute for a web property, and 7 credits to execute for a certificate.
46
+ * Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate. The job extracts [default pivot fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#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>Use this endpoint to start an analysis of a suspicious host, web property, or certificate that finds the rare attributes it shares with other assets, so you can uncover related attacker infrastructure.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint costs 44 credits to execute for a host, 28 credits to execute for a web property, and 7 credits to execute for a certificate.
47
47
  */
48
48
  async createCenseyeJob(
49
49
  request: operations.V3ThreathuntingCenseyeJobsCreateRequest,
@@ -77,7 +77,7 @@ export class ThreatHunting extends ClientSDK {
77
77
  * CensEye: Get job results
78
78
  *
79
79
  * @remarks
80
- * 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.
80
+ * Retrieve the results of a completed CensEye pivot analysis job. Use this endpoint to retrieve the pivots from a finished job, then turn the most distinctive ones into searches or blocklist candidates.<br><br>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.
81
81
  */
82
82
  async getCenseyeJobResults(
83
83
  request: operations.V3ThreathuntingCenseyeJobResultsRequest,
@@ -94,7 +94,7 @@ export class ThreatHunting extends ClientSDK {
94
94
  * Get host history for a certificate
95
95
  *
96
96
  * @remarks
97
- * 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.<br><br>For workspaces with a history limit, the API returns observation ranges that overlap the allowed history window. The window starts at 00:00 UTC the allowed number of days ago and ends at the time of the request. Ranges are returned in full, with their original start and end times, even if they extend outside the window.<br><br>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. This endpoint costs one credit per page of results.
97
+ * Retrieve the historical observations of hosts associated with a certificate. Use this endpoint to see every host that has presented a given certificate over time, so you can build a timeline and find other infrastructure using it.<br><br>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.<br><br>For workspaces with a history limit, the API returns observation ranges that overlap the allowed history window. The window starts at 00:00 UTC the allowed number of days ago and ends at the time of the request. Ranges are returned in full, with their original start and end times, even if they extend outside the window.<br><br>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. This endpoint costs one credit per page of results.
98
98
  */
99
99
  async getHostObservationsWithCertificate(
100
100
  request:
@@ -114,7 +114,7 @@ export class ThreatHunting extends ClientSDK {
114
114
  * Investigations: Create file upload
115
115
  *
116
116
  * @remarks
117
- * Prepare to attach an evidence file to an investigation. This endpoint does not accept the file. It returns a URL to send the file to and an identifier to pass to the [create job endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-jobs-create) afterwards.<br><br>Upload the file with an HTTP PUT to `upload_url` and send `upload_headers` exactly as returned by this endpoint. The URL grants access to that one file and stops working at `expire_time`; a file uploaded before that stays usable afterwards. Prepare one upload per file.<br><br>Start the investigation promptly after uploading. There is a limit on how many uploaded files you may hold without using them and starting an investigation from a file releases its slot. A file that no investigation references is discarded once it passes the service's retention window for unused uploads. A file an investigation does reference is kept with that investigation for as long as the investigation itself.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint does not cost any credits to execute.
117
+ * Prepare to attach an evidence file to an investigation. Use this endpoint to stage evidence, such as logs, malware reports, or alert exports, so an AI investigation can use it.<br><br>This endpoint does not accept the file. It returns a URL to send the file to and an identifier to pass to the [create job endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-jobs-create) afterwards.<br><br>Upload the file with an HTTP PUT to `upload_url` and send `upload_headers` exactly as returned by this endpoint. The URL grants access to that one file and stops working at `expire_time`; a file uploaded before that stays usable afterwards. Prepare one upload per file.<br><br>Start the investigation promptly after uploading. There is a limit on how many uploaded files you may hold without using them and starting an investigation from a file releases its slot. A file that no investigation references is discarded once it passes the service's retention window for unused uploads. A file an investigation does reference is kept with that investigation for as long as the investigation itself.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint does not cost any credits to execute.
118
118
  */
119
119
  async createInvestigationFileUpload(
120
120
  request: operations.V3ThreathuntingInvestigationsFilesCreateRequest,
@@ -148,7 +148,7 @@ export class ThreatHunting extends ClientSDK {
148
148
  * Investigations: Create job
149
149
  *
150
150
  * @remarks
151
- * Start an [AI investigation](https://docs.censys.com/docs/platform-ai-investigations) from a set of indicators, a set of previously uploaded evidence files, or both. Supply at least one `indicators` or `file_ids`. To use files, upload them first with the [create file upload endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-files-create).<br><br>This endpoint returns a `job_id` that you can poll to retrieve its status and results.<br><br>Provide `start_time` and `end_time` to scope the investigation to a time frame, or `start_time` alone to scope it from that time up to now. Omit both to investigate current data.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
151
+ * Start an [AI investigation](https://docs.censys.com/docs/platform-ai-investigations) from a set of indicators, a set of previously uploaded evidence files, or both to obtain a report on suspect infrastructure without doing the pivots by hand.<br><br>Supply at least one `indicators` or `file_ids`. To use files, upload them first with the [create file upload endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-files-create).<br><br>This endpoint returns a `job_id` that you can poll to retrieve its status and results.<br><br>Provide `start_time` and `end_time` to scope the investigation to a time frame, or `start_time` alone to scope it from that time up to now. Omit both to investigate current data.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
152
152
  */
153
153
  async createInvestigationJob(
154
154
  request: operations.V3ThreathuntingInvestigationsJobsCreateRequest,
@@ -216,7 +216,7 @@ export class ThreatHunting extends ClientSDK {
216
216
  * Live Discovery: Initiate a new scan
217
217
  *
218
218
  * @remarks
219
- * 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.
219
+ * 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>Use this endpoint to scan for a service at an `ip:port` or `hostname:port`, such as a new IOC from an incident, so you can get data on it right away.<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module. It costs 15 credits to execute this endpoint.
220
220
  */
221
221
  async createTrackedScan(
222
222
  request: operations.V3ThreathuntingScansDiscoveryRequest,
@@ -233,7 +233,7 @@ export class ThreatHunting extends ClientSDK {
233
233
  * Get scan status
234
234
  *
235
235
  * @remarks
236
- * Retrieve the current status of a scan by its ID. This endpoint works for both [Live Discovery scans](https://docs.censys.com/reference/v3-threathunting-scans-discovery#/) and [Live Rescans](https://docs.censys.com/reference/v3-globaldata-scans-rescan#/).<br><br>If the scan was successful, perform a lookup on the target asset to retrieve detailed scan information.<br><br>This endpoint is available to all Enterprise customers. This endpoint does not cost any credits to execute.
236
+ * Retrieve the current status of a scan by its ID. This endpoint works for both [Live Discovery scans](https://docs.censys.com/reference/v3-threathunting-scans-discovery#/) and [Live Rescans](https://docs.censys.com/reference/v3-globaldata-scans-rescan#/).<br><br>Use this endpoint to check whether a Live Discovery or Live Rescan scan has finished, so automation knows when fresh data is ready to pull.<br><br>If the scan was successful, perform a lookup on the target asset to retrieve detailed scan information.<br><br>This endpoint is available to all enterprise customers. This endpoint does not cost any credits to execute.
237
237
  */
238
238
  async getTrackedScanThreatHunting(
239
239
  request: operations.V3ThreathuntingScansGetRequest,
@@ -250,7 +250,7 @@ export class ThreatHunting extends ClientSDK {
250
250
  * List active threats
251
251
  *
252
252
  * @remarks
253
- * 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.
253
+ * Retrieve a list of active threats observed by Censys by aggregating threat IDs across hosts and web properties. Use this endpoint to see currently active threats so you can prioritize which malicious infrastructure to hunt or block first.<br><br>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.
254
254
  */
255
255
  async listThreats(
256
256
  request: operations.V3ThreathuntingThreatsListRequest,
@@ -267,7 +267,7 @@ export class ThreatHunting extends ClientSDK {
267
267
  * CensEye: Retrieve value counts to discover pivots
268
268
  *
269
269
  * @remarks
270
- * 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.
270
+ * 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>Use this endpoint to see how many assets share a given field value, so you can tell which attributes are rare enough to pivot on and which are too common to be useful.<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.
271
271
  */
272
272
  async valueCounts(
273
273
  request: operations.V3ThreathuntingValueCountsRequest,