Crate synthient 

The Rust client for the Synthient API: IP and domain intelligence, account details, and the Synthient data feeds.

Create a Client with an API key and reuse it for every request:

use std::net::Ipv4Addr;

let client = synthient::Client::new(std::env::var("SYNTHIENT_API_KEY")?)?;

let info = client.lookup_ip(Ipv4Addr::new(8, 8, 8, 8)).await?;
if let Some(intelligence) = &info.intelligence {
    println!("{} {:?}", intelligence.risk_score, intelligence.categories);
}

The client is asynchronous and runs on Tokio. Cloning it is cheap, and every future and stream it returns is Send.

Errors

A request that fails with a non-success HTTP status returns Error::Api, whose ApiError holds the status, the problem detail, the request ID, and any Retry-After delay:

use synthient::{Error, StatusCode};

match client.lookup_ips(&["8.8.8.8".parse().unwrap()]).await {
    Err(Error::Api(err)) if err.status == StatusCode::PAYMENT_REQUIRED => {
        eprintln!("out of lookup credits");
    }
    Err(err) => eprintln!("lookup failed: {err}"),
    Ok(results) => println!("{} results", results.len()),
}

Error messages contain only the HTTP status. Server-provided details are in the fields of ApiError and can contain sensitive data. ClientBuilder::on_response exposes request IDs and rate limits for every API response.

Retries

Requests that cost no credits are retried on 500, 502, 503, and 504 responses, on transport errors, and on 429 responses that carry Retry-After. Billed lookups (Client::lookup_ip, Client::lookup_ips, and Client::lookup_domain) are retried only on 429 responses that carry Retry-After, which the rate limiter returns before doing any work. A 429 without Retry-After means the key’s monthly request budget is spent or it has too many open streams, so it is returned without a retry. Client::health is retried the same way as billed lookups, so it reports an unhealthy API right away.

Retries back off exponentially with jitter and honor Retry-After. A Retry-After over a minute, or one that would outlast the client’s timeout, is returned to the caller instead. Set the retry count with ClientBuilder::max_retries. The SDK turns off reqwest’s own retries, so no request is ever resent by the transport.

Feeds

Each Feed, such as Client::proxies, has a real-time stream and hourly parquet exports that roll up into daily exports:

let mut events = client.proxies().stream().await?;
while let Some(event) = events.next().await {
    let event = event?;
    println!("{:?} {:?}", event.ip, event.provider);
}

Feed::download fetches an export’s parquet file without sending the API key to the storage host.

Timeouts

By default, connecting gives up after 30 seconds and a read that stalls for 60 seconds fails. Streams send a keepalive line every 15 seconds, so they never stall that long. There is no overall limit, because streams and downloads are long-lived. Set one with ClientBuilder::timeout, or drop a future to cancel it.

Features

• rustls (default): TLS through rustls.
• native-tls: TLS through the platform’s native library.
• grpcschema: the grpcschema module, which fetches the protobuf schema of the Synthient gRPC API.

Re-exports

pub use reqwest;

Modules

grpcschemagrpcschema

Fetches the protobuf schema of the Synthient gRPC API using gRPC server reflection. It needs the grpcschema feature.

Structs

Account

The account that owns the API key.

AccountApiKey

An API key.

ActivityStats

The hourly activity pattern of a domain.

AnonymizerEvent

A VPN or anonymizer IP range from the anonymizers feed. The API may omit any field.

ApiError

A non-success HTTP response.

AsnCount

An autonomous system and its event count.

Client

A Synthient API client.

ClientBuilder

Configures a Client. Create one with Client::builder.

CountryCount

A source country and its counts.

Device

A device type seen behind an address.

DomainEvent

A single honeypot event for a domain.

DomainInfo

The honeypot traffic Synthient has observed for a domain.

DomainStats

Aggregate event counts for a domain.

Download

The contents of an export’s parquet file, read in chunks as they arrive. Create one with Feed::download. Dropping it closes the connection.

EventStream

A stream of a feed’s real-time events from Feed::stream, or of its exports from Feed::all_exports.

Export

A parquet export of a feed.

ExportMeta

A parquet export’s metadata.

ExportPage

One page of a feed’s exports, newest first.

Feed

A Synthient data feed. Each feed has a real-time stream of events of type T and hourly parquet exports that roll up into daily exports. Get one from a Client method such as Client::proxies.

HeliosAdbEvent

An Android Debug Bridge shell command captured by a Helios honeypot. It has no timestamp because the sensor sends none.

HeliosDnsEvent

A destination that a Helios honeypot tunnel was asked to reach. Names resolved inside a tunneled DNS session are not visible.

HeliosHttpEvent

An HTTP request captured by a Helios honeypot.

HeliosHttpsEvent

A TLS ClientHello captured by a Helios honeypot.

HeliosMeta

The Helios honeypot sensor that captured an event. The API may omit any field.

HttpRequestDetails

A parsed HTTP request. The API may omit any field.

Intelligence

Synthient’s assessment of an address.

IpInfo

The intelligence Synthient holds for an IP address. network, location, and intelligence are None when the API has no data for them.

Ja4tEvent

A JA4T TCP fingerprint sighting. The API may omit any field.

Location

The geolocation of an address.

LookupQuota

An account’s lookup credit balance.

Network

The network that announces an address.

Organization

The organization an account belongs to.

ParquetColumn

A column of a parquet export.

ParquetSchema

The columns of a parquet export.

PortCount

A port and its event count.

Provider

A proxy, VPN, or anonymizer service seen using an address.

ProxyEvent

A proxy sighting from the proxies feed. The API may omit any field.

RateLimit

The state of an operation’s rate limit, from the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Limits are shared by every key of a team.

ResponseMetadata

Describes one HTTP response from the Synthient API. See ClientBuilder::on_response.

StatusCode

An HTTP status code (status-code in RFC 9110 et al.).

SubdomainCount

A subdomain and its event count.

TimeSeriesPoint

The event counts for one day.

Timestamp

A Unix time exactly as the API encodes it.

TlsClientHello

A TLS ClientHello parsed by a Helios sensor. Fields the sensor could not parse are None.

TlsCodeName

A TLS registry code point and its name. GREASE values are named GREASE(0x....).

TlsExtension

An extension in a TLS ClientHello.

TorrentEvent

A torrent observed on the BitTorrent DHT or a tracker. The API may omit any field.

TorrentFile

A file in a torrent.

TorrentPeer

A peer seen sharing a torrent.

UniqueIps

Counts of the distinct source addresses seen for a domain.

Enums

Cadence

How a domain’s events are spread over time. The API sends each value as an English sentence.

DomainStatus

Whether a domain has recent activity.

Error

An error from the Synthient client.

ExportKind

Whether an export covers an hour or a day.

NetworkType

The kind of network that announces an address.

Os

A device operating system.

ParquetType

The type of a parquet column.

ProxyType

The kind of service seen on an address.

Relation

An account’s role in its organization.

Scope

A permission granted to an API key.

Constants

DEFAULT_BASE_URL

The base URL of the Synthient HTTP API.

VERSION

The version of this crate. It is sent in the User-Agent header.

Type Aliases

ExportStream

A stream of every export of a feed, newest first. Create one with Feed::all_exports.

Result

A Result whose error is Error.