# Types The fields of every response and event type, and the enumerations they use. ## Lookup types Every response type is an immutable `Data` class, as are `ResponseMetadata`, `RateLimit`, and `GRPCSchema::Schema`. - **Fields:** Read fields with the methods named after them. `to_h`, `with`, `==`, and pattern matching work as for any `Data`, and arrays and hashes decoded from a response are frozen. - **Optional fields:** A field typed with a trailing `?` is `nil` when the API omits it or sends `null`. - **Decoding:** A response with a required field missing or of the wrong type raises `DecodeError`. Unknown fields are ignored so that additive API changes don't break decoding. - **Timestamps:** Unix timestamps from the API become `Time` values in UTC, whether the API sends seconds or milliseconds. ### IPInfo The intelligence Synthient holds for an IP address. See the [IP API](https://docs.synthient.com/ipapi) for how each field is derived. - `ip` `IPAddr` — The address that was looked up. - `network` `Network?` — The network that announces the address, or `nil` if the API has no network data. - `location` `Location?` — The geolocation of the address, or `nil` if the API has no location data. - `intelligence` `Intelligence?` — The risk score and the proxy, VPN, and device observations for the address, or `nil` if the API has no intelligence data. ### Network - `asn` `Integer` — The autonomous system number, or `0` if the address is not routed. - `isp` `String` — The internet service provider that operates the network. - `org` `String?` — The organization the address is registered to, or `nil` if unknown. - `domain` `String?` — The network operator's domain, or `nil` if unknown. - `type` `String` — The kind of network, such as `NetworkType::RESIDENTIAL`. See [Enumerations](#enumerations). - `abuse_email` `String?` — The operator's abuse contact email, or `nil` if unknown. - `abuse_phone` `String?` — The operator's abuse contact phone number, or `nil` if unknown. ### Location - `country` `String` — The ISO 3166-1 alpha-2 country code. - `state` `String` — The state or region. - `city` `String` — The city. - `timezone` `String` — The IANA time zone name. - `latitude` `Float` — The latitude in degrees. - `longitude` `Float` — The longitude in degrees. - `geo_hash` `String` — The geohash of the coordinates. ### Intelligence Synthient's assessment of an address. See [Methodology](https://docs.synthient.com/methodology) for how it is built. - `risk_score` `Integer` — The risk of the address, from 0 to 100. - `categories` `Array[String]` — The kinds of services seen on the address. New values may be added. - `behavior` `Array[String]` — Behaviors observed from the address. New values may be added. - `providers` `Array[Provider]` — The proxy, VPN, and anonymizer services seen using the address. An empty list does not mean the address is clean. - `devices` `Array[Device]` — The device types seen behind the address. ### Provider A proxy, VPN, or anonymizer service seen using an address. - `name` `String` — The service tag, such as `"BRIGHTDATA"`. The API names this field `provider`. See [Service Tags](https://docs.synthient.com/service-tags). - `type` `String` — The service category. - `last_seen` `Time` — When the service was last seen on the address. ### Device A device type seen behind an address. - `os` `String` — The operating system, such as `OS::ANDROID`. See [Enumerations](#enumerations). - `version` `String` — The operating system version. - `last_seen` `Time` — When the device was last seen. ## Domain types ### DomainInfo The honeypot traffic Synthient has observed for a domain. - `domain` `String` — The domain that was looked up. - `status` `String` — Whether the domain had events in the last 24 hours, as a `DomainStatus` value. - `stats` `DomainStats` — Aggregate event counts. - `unique_ips` `UniqueIPs` — Counts of the distinct source addresses. - `time_series` `Array[TimeSeriesPoint]` — Daily event counts. - `top_asn` `ASNCount?` — The network that sent the most events, or `nil` when there were no events. - `top_subdomains` `Array[SubdomainCount]` — The most targeted subdomains. - `top_ports` `Array[PortCount]` — The most targeted ports. - `geo_distribution` `Array[CountryCount]` — Event counts by source country. - `hour_dow_heatmap` `Array[Array[Integer]]` — The last 30 days of events as 7 rows, Monday first, of 24 UTC hourly counts, indexed as `hour_dow_heatmap[day][hour]`. Day 0 is Monday, unlike `Time#wday`, where 0 is Sunday. - `activity_stats` `ActivityStats` — The hourly activity pattern. - `recent_events` `Array[DomainEvent]` — The most recent events, capped by the `limit:` passed to `lookup_domain`. ### DomainStats - `events_24h` `Integer` — Events in the last 24 hours. - `total_events_30d` `Integer` — Events in the last 30 days. ### UniqueIPs The distinct source addresses seen for a domain. - `value_24h` `Integer` — Distinct source addresses in the last 24 hours. - `value_30d` `Integer` — Distinct source addresses in the last 30 days. - `sparkline_24h` `Array[Integer]` — Hourly counts for the last 24 hours, oldest first. ### TimeSeriesPoint The event counts for one day. - `date` `Time` — The start of the day. - `events` `Integer` — Events that day. - `unique_ips` `Integer` — The number of distinct source addresses that day. ### ASNCount - `asn` `Integer` — The autonomous system number. - `events` `Integer` — Events from that network. ### SubdomainCount - `subdomain` `String` — The subdomain. - `count` `Integer` — The number of events that targeted it. ### PortCount - `port` `Integer` — The port. - `count` `Integer` — The number of events that targeted it. ### CountryCount - `country_code` `String` — The ISO 3166-1 alpha-2 country code. - `events` `Integer` — Events from that country. - `unique_ips` `Integer` — Distinct source addresses from that country. ### ActivityStats The hourly activity pattern of a domain. - `cadence` `String` — How events are spread over the last 30 days, as a `Cadence` sentence. See [Enumerations](#enumerations). - `median_per_hour` `Integer` — The median number of events per hour. - `p95_per_hour` `Integer` — The 95th percentile of events per hour. - `peak_hour` `Integer` — The busiest UTC hour of the day. - `quiet_hour` `Integer` — The quietest UTC hour of the day. ### DomainEvent A single honeypot event for a domain. - `timestamp` `Time` — When the event happened. - `source_ip` `String` — The full proxy exit address that carried the event. The API names the field `source_ip_masked`, but the address is not masked. - `target_subdomain` `String` — The subdomain that was targeted. - `country_code` `String` — The source country. - `port` `Integer` — The destination port. ## Account types ### Account The account that owns the API key. - `email` `String` — The account's email address. - `first_name` `String` — The account holder's first name. - `last_name` `String` — The account holder's last name. - `organization` `Organization` — The organization the account belongs to. - `scopes` `Array[String]` — The permissions granted to the API key, as `Scope` values. See [Enumerations](#enumerations). - `lookup_quota` `LookupQuota` — The remaining lookup credit balance. - `api_key` `AccountAPIKey?` — The API key used for the request, or `nil` if the API omits it. ### Organization - `id` `String` — The organization's ID. - `name` `String` — The organization's name. - `relation` `String` — The account's role in the organization, as a `Relation` value. See [Enumerations](#enumerations). ### LookupQuota An account's lookup credit balance. - `credits` `Integer` — The number of lookup credits remaining. - `resets_in` `Integer` — The number of seconds until the credits reset. ### AccountAPIKey - `id` `String` — The key's ID. - `name` `String` — The key's display name. - `created_at` `Time` — When the key was created, parsed from the API's RFC 3339 string. ## Export types ### ExportPage One page of a feed's exports, newest first. - `stream` `String` — The feed's stream identifier, such as `"proxies"`. - `exports` `Array[Export]` — The exports on this page. The API names this field `feeds`. - `next_cursor` `String?` — Fetches the next page when passed as `cursor:`. It is `nil` on the last page. ### Export A Parquet export of a feed. - `id` `String` — Identifies the export for `export_meta`, `download_url`, and `download`, which accept it as is. On the first page, the newest hourly export may have the ID `"latest"`. - `kind` `String` — Whether the export covers an hour or a day, as an `ExportKind` value. - `date` `Date` — The UTC day of the export. - `hour` `Integer?` — The UTC hour of an hourly export, or `nil` for a daily export. - `size_bytes` `Integer` — The size of the Parquet file in bytes. - `row_count` `Integer` — The number of rows in the file. - `checksum` `String` — The hex-encoded SHA-256 of the Parquet file. - `created_at` `Time` — When the export was created. - `download_path` `String` — The API path of the export's download, including the `/api/v4` prefix. ### ExportMeta A Parquet export without its contents. - `id` `String` — The export ID. - `stream` `String` — The feed's stream identifier. - `kind` `String` — Whether the export covers an hour or a day, as an `ExportKind` value. - `format` `String` — The file format. - `date` `Time` — The start of the export's UTC day or hour. - `hour` `Integer?` — The UTC hour of an hourly export, or `nil` for a daily export. - `rows` `Integer` — The number of rows in the file. - `size` `Integer` — The size of the Parquet file in bytes. - `checksum` `String` — The hex-encoded SHA-256 of the Parquet file. - `created_at` `Time` — When the export was created. - `schema` `ParquetSchema` — The Parquet columns. ### ParquetSchema - `fields` `Array[ParquetColumn]` — The columns of the export. ### ParquetColumn - `name` `String` — The column name. - `type` `String` — The column type, as a `ParquetType` value. See [Enumerations](#enumerations). ## Event types Stream payloads match the [Firehose](https://docs.synthient.com/enterprise/firehose) and [Helios](https://docs.synthient.com/enterprise/helios) documentation field for field, except where a field is renamed below. Fields typed with a trailing `?` are `nil` when the API omits them. ### ProxyEvent A proxy sighting from the `proxies` feed. - `ip` `String?` — The proxy exit address. - `provider` `String?` — The proxy service tag. - `type` `String?` — The service category, as a `ProxyType` value. See [Enumerations](#enumerations). - `country_code` `String?` — The ISO 3166-1 alpha-2 country of the address. - `asn` `Integer?` — The autonomous system number of the address. - `timestamp` `Time?` — When the proxy was seen. ### AnonymizerEvent A VPN or anonymizer address range from the `anonymizers` feed. - `range_start` `String?` — The first address of the range. - `range_end` `String?` — The last address of the range. - `provider` `String?` — The service tag. - `type` `String?` — The service category, such as `ProxyType::COMMERCIAL_VPN`. - `country_code` `String?` — The ISO 3166-1 alpha-2 country of `range_start`. - `asn` `Integer?` — The autonomous system number of `range_start`. - `timestamp` `Time?` — When the range was seen. ### TorrentEvent A torrent observed on the BitTorrent DHT or a tracker. - `info_hash` `String?` — The hex-encoded SHA-1 info hash. - `name` `String?` — The torrent's name. - `magnet_uri` `String?` — The torrent's magnet link. - `total_size` `Integer?` — The total size of the torrent's files in bytes. - `piece_length` `Integer?` — The piece size in bytes. - `file_count` `Integer?` — The number of files in the torrent. - `files` `Array[TorrentFile]?` — The files in the torrent. - `peers` `Array[TorrentPeer]?` — The peers seen sharing the torrent. - `timestamp` `Time?` — When the torrent was seen. ### TorrentFile - `path` `String?` — The file path within the torrent. - `length` `Integer?` — The file size in bytes. ### TorrentPeer - `ip` `String?` — The peer's address. - `port` `Integer?` — The peer's port. - `source` `String?` — Where the peer was found, such as `"DHT"`, `"PEX"`, or `"tracker"`. - `encrypted` `bool?` — Whether the peer supports encrypted connections. ### JA4TEvent A JA4T TCP fingerprint sighting. - `ip` `String?` — The address the fingerprint was seen from. - `ja4t` `String?` — The JA4T fingerprint. - `provider` `String?` — The service tag of the address. - `type` `String?` — The service category, such as `ProxyType::DATACENTER_PROXY`. - `country_code` `String?` — The ISO 3166-1 alpha-2 country of the address. - `asn` `Integer?` — The autonomous system number of the address. - `timestamp` `Time?` — When the fingerprint was seen. ### HeliosMeta The Helios honeypot sensor that captured an event. - `proxy_ip` `String?` — The proxy exit address the traffic arrived through. - `server` `String?` — The sensor that captured the traffic. - `pool_id` `String?` — The sensor pool. - `provider` `String?` — The proxy service the traffic arrived through. ### HeliosHTTPEvent An HTTP request captured by a Helios honeypot. - `timestamp` `Time` — When the request was captured. - `tunnel_id` `Integer` — Identifies the proxy tunnel the request arrived through. Live values use the full unsigned 64-bit range. - `domain` `String` — The host the tunnel was opened to. - `port` `Integer` — The destination port. - `protocol` `String` — Always `"http"`. - `meta` `HeliosMeta` — The capturing sensor. - `details` `HTTPRequestDetails?` — The parsed request. - `raw` `String?` — The raw request bytes as a binary `String`, decoded from the API's base64. ### HTTPRequestDetails A parsed HTTP request. - `http_method` `String?` — The request method. The API names this field `method`. - `uri` `String?` — The request target. - `version` `String?` — The HTTP version, such as `"HTTP/1.1"`. - `headers` `Hash[String, String]?` — The request headers. ### HeliosHTTPSEvent A TLS ClientHello captured by a Helios honeypot. - `timestamp` `Time` — When the handshake was captured. - `tunnel_id` `Integer` — Identifies the proxy tunnel the handshake arrived through. Live values use the full unsigned 64-bit range. - `domain` `String` — The host the tunnel was opened to. - `port` `Integer` — The destination port. - `protocol` `String` — Always `"https"`. - `meta` `HeliosMeta` — The capturing sensor. - `details` `TLSClientHello?` — The parsed ClientHello, or `nil` if the sensor could not parse the handshake. - `raw` `String?` — Always `nil`, because the sensors do not capture handshake bytes. ### TLSClientHello A TLS ClientHello parsed by a Helios sensor. Fields the sensor could not parse are `nil`. - `record_version` `String?` — The record layer version, such as `"TLS 1.0"`. - `handshake_version` `String?` — The ClientHello version, such as `"TLS 1.2"`. - `client_random` `String?` — The hex-encoded 32-byte client random. - `session_id` `String?` — The hex-encoded session ID. - `session_id_length` `Integer?` — The length of the session ID in bytes. - `cipher_suites` `Array[TLSCodeName]?` — The offered cipher suites. - `compression_methods` `Array[Integer]?` — The offered compression methods. - `extensions` `Array[TLSExtension]?` — The extensions in wire order. - `sni` `String?` — The `server_name` extension value. - `alpn` `Array[String]?` — The offered application protocols. - `supported_versions` `Array[String]?` — The offered TLS versions. - `supported_groups` `Array[TLSCodeName]?` — The offered key exchange groups. - `signature_algorithms` `Array[TLSCodeName]?` — The offered signature algorithms. - `ec_point_formats` `Array[String]?` — The offered elliptic curve point formats. - `key_share_groups` `Array[String]?` — The groups the client sent key shares for. - `psk_key_exchange_modes` `Array[String]?` — The offered pre-shared key exchange modes. - `compress_certificate` `Array[String]?` — The offered certificate compression algorithms. - `has_grease` `bool?` — Whether the ClientHello contains GREASE values. - `application_settings` `bool?` — Whether the client offered application settings (ALPS). - `delegated_credentials` `bool?` — Whether the client offered the `delegated_credentials` extension. - `encrypt_then_mac` `bool?` — Whether the client offered the `encrypt_then_mac` extension. - `extended_master_secret` `bool?` — Whether the client offered the `extended_master_secret` extension. - `post_handshake_auth` `bool?` — Whether the client offered the `post_handshake_auth` extension. - `renegotiation_info` `bool?` — Whether the client offered the `renegotiation_info` extension. - `signed_certificate_timestamps` `bool?` — Whether the client offered the `signed_certificate_timestamp` extension. - `status_request` `bool?` — Whether the client requested OCSP stapling. ### TLSCodeName A TLS registry code point and its name. GREASE values are named `"GREASE(0x....)"`. - `code` `Integer?` — The code point. - `name` `String?` — The code point's registered name. ### TLSExtension An extension in a TLS ClientHello. - `code` `Integer?` — The extension type. - `name` `String?` — The extension's registered name. - `length` `Integer?` — The extension body length in bytes. ### HeliosDNSEvent A destination that a Helios honeypot tunnel was asked to reach. Despite the feed's name, it is not a DNS query: names resolved inside a tunneled DNS session are not visible. - `timestamp` `Time` — When the event was captured. - `tunnel_id` `Integer` — Identifies the proxy tunnel. Live values use the full unsigned 64-bit range. - `domain` `String` — The host name or address literal the tunnel was opened to. - `port` `Integer` — The destination port. - `protocol` `String` — Always `"dns"`. - `meta` `HeliosMeta` — The capturing sensor. ### HeliosADBEvent An Android Debug Bridge shell command captured by a Helios honeypot. It has no timestamp because the sensor sends none. - `session` `String` — Identifies the ADB session as 32 hex characters. - `sequential_id` `Integer` — The 1-based position of the command within its session. - `command` `String` — The shell command. Invalid UTF-8 bytes are replaced with U+FFFD. - `payload_hash` `String` — The hex-encoded SHA-256 the sensor assigns to the session's payload. The API names this field `hash`. It is not a hash of `command`: every command in a session shares it, and sessions that replay the same script share it too. ## Enumerations Each value set is a module of `String` constants under `Synthient`. Model fields hold plain strings, so compare them with the constants. Values the SDK does not know are kept as they are. The API may add values to the sets marked open, so handle unknown values instead of assuming a closed `case`. ### NetworkType The kind of network that announces an address. Open. | Constant | Value | | ----------------------------- | ---------------- | | `NetworkType::MOBILE` | `MOBILE` | | `NetworkType::SATELLITE` | `SATELLITE` | | `NetworkType::IN_FLIGHT_WIFI` | `IN_FLIGHT_WIFI` | | `NetworkType::RESIDENTIAL` | `RESIDENTIAL` | | `NetworkType::CORPORATE` | `CORPORATE` | | `NetworkType::ACADEMIC` | `ACADEMIC` | | `NetworkType::DATACENTER` | `DATACENTER` | | `NetworkType::GOVERNMENT` | `GOVERNMENT` | ### ProxyType The kind of service seen on an address. Open. | Constant | Value | | ------------------------------ | ------------------- | | `ProxyType::FREE_VPN` | `FREE_VPN` | | `ProxyType::COMMERCIAL_VPN` | `COMMERCIAL_VPN` | | `ProxyType::ENTERPRISE_VPN` | `ENTERPRISE_VPN` | | `ProxyType::MOBILE_PROXY` | `MOBILE_PROXY` | | `ProxyType::BLOCKCHAIN_PROXY` | `BLOCKCHAIN_PROXY` | | `ProxyType::RESIDENTIAL_PROXY` | `RESIDENTIAL_PROXY` | | `ProxyType::PUBLIC_PROXY` | `PUBLIC_PROXY` | | `ProxyType::DATACENTER_PROXY` | `DATACENTER_PROXY` | | `ProxyType::TOR_NODE` | `TOR_NODE` | | `ProxyType::PRIVATE_RELAY` | `PRIVATE_RELAY` | | `ProxyType::BOTNET` | `BOTNET` | | `ProxyType::SEARCH_ENGINE` | `SEARCH_ENGINE` | | `ProxyType::AI_CRAWLER` | `AI_CRAWLER` | | `ProxyType::SOCIAL_MEDIA` | `SOCIAL_MEDIA` | | `ProxyType::UPTIME_MONITOR` | `UPTIME_MONITOR` | | `ProxyType::LINK_PREVIEW` | `LINK_PREVIEW` | | `ProxyType::SEO_CRAWLER` | `SEO_CRAWLER` | | `ProxyType::WEB_ARCHIVER` | `WEB_ARCHIVER` | | `ProxyType::WEBHOOK_PROVIDER` | `WEBHOOK_PROVIDER` | | `ProxyType::PAYMENT_PROCESSOR` | `PAYMENT_PROCESSOR` | | `ProxyType::INTERNET_SCANNER` | `INTERNET_SCANNER` | ### OS A device operating system. Open. | Constant | Value | | --------------- | ----------- | | `OS::ANDROID` | `Android` | | `OS::CHROME_OS` | `Chrome OS` | | `OS::FREEBSD` | `FreeBSD` | | `OS::IOS` | `iOS` | | `OS::LINUX` | `Linux` | | `OS::MAC_OS_X` | `Mac OS X` | | `OS::WINDOWS` | `Windows` | ### Scope A permission granted to an API key. Open. `Scope::BASIC` authorizes lookups and `account`. Each feed has one scope for its exports and one for its stream, as listed under [Feeds](https://docs.synthient.com/sdks/ruby/feeds). See [Authentication](https://docs.synthient.com/authentication) for how scopes are granted. | Constant | Value | | ------------------------------ | ----------------------- | | `Scope::BASIC` | `BASIC` | | `Scope::PROXY_FEEDS` | `PROXY_FEEDS` | | `Scope::PROXY_FIREHOSE` | `PROXY_FIREHOSE` | | `Scope::ANONYMIZERS_FEED` | `ANONYMIZERS_FEED` | | `Scope::ANONYMIZERS_STREAM` | `ANONYMIZERS_STREAM` | | `Scope::JA3_FEED` | `JA3_FEED` | | `Scope::JA3_STREAM` | `JA3_STREAM` | | `Scope::TORRENTS_FEED` | `TORRENTS_FEED` | | `Scope::TORRENTS_STREAM` | `TORRENTS_STREAM` | | `Scope::HONEYPOT_HTTP_FEED` | `HONEYPOT_HTTP_FEED` | | `Scope::HONEYPOT_HTTP_STREAM` | `HONEYPOT_HTTP_STREAM` | | `Scope::HONEYPOT_HTTPS_FEED` | `HONEYPOT_HTTPS_FEED` | | `Scope::HONEYPOT_HTTPS_STREAM` | `HONEYPOT_HTTPS_STREAM` | | `Scope::HONEYPOT_ADB_FEED` | `HONEYPOT_ADB_FEED` | | `Scope::HONEYPOT_ADB_STREAM` | `HONEYPOT_ADB_STREAM` | | `Scope::HONEYPOT_DNS_FEED` | `HONEYPOT_DNS_FEED` | | `Scope::HONEYPOT_DNS_STREAM` | `HONEYPOT_DNS_STREAM` | | `Scope::JA4_FEED` | `JA4_FEED` | | `Scope::JA4_STREAM` | `JA4_STREAM` | | `Scope::JA4T_FEED` | `JA4T_FEED` | | `Scope::JA4T_STREAM` | `JA4T_STREAM` | | `Scope::ADMIN_PROXIES` | `ADMIN_PROXIES` | ### Relation An account's role in its organization. | Constant | Value | | ------------------ | -------- | | `Relation::OWNER` | `OWNER` | | `Relation::ADMIN` | `ADMIN` | | `Relation::MEMBER` | `MEMBER` | ### DomainStatus Whether a domain has recent activity. | Constant | Value | Meaning | | ------------------------ | ---------- | -------------------------------------------------------------------------- | | `DomainStatus::ACTIVE` | `active` | The domain had events in the last 24 hours. | | `DomainStatus::INACTIVE` | `inactive` | The domain had no events in the last 24 hours, or has never been observed. | ### Cadence A sentence describing a domain's activity over the last 30 days. | Constant | Value | | ----------------------------- | ---------------------------------------------------- | | `Cadence::NO_ACTIVITY` | `No activity in the last 30 days.` | | `Cadence::EVENLY_DISTRIBUTED` | `Activity is evenly distributed across the day.` | | `Cadence::BUSINESS_HOURS` | `Activity follows a weekday business-hours pattern.` | | `Cadence::WEEKEND` | `Activity follows a weekend pattern.` | | `Cadence::BURST_DRIVEN` | `Activity is burst-driven with significant peaks.` | ### ExportKind Whether an export covers an hour or a day. | Constant | Value | | -------------------- | -------- | | `ExportKind::HOURLY` | `hourly` | | `ExportKind::DAILY` | `daily` | ### ParquetType The type of a Parquet column. Open. | Constant | Value | | --------------------- | -------- | | `ParquetType::STRING` | `string` | | `ParquetType::INT64` | `int64` | | `ParquetType::UINT32` | `uint32` | | `ParquetType::UINT64` | `uint64` | | `ParquetType::BOOL` | `bool` | | `ParquetType::BYTES` | `bytes` |