Skip to content
Get Stalwart

ASN and GeoIP

Knowing where a connection comes from helps a mail server judge it. Mail from a network that is known for spam, or from a country the users never correspond with, deserves more suspicion than mail from a well-known provider. Stalwart looks up two facts about the address of every incoming SMTP connection: its network operator and its country.

The network operator is identified by its Autonomous System Number (ASN). An autonomous system is a network under one operator’s control, and its number appears in the routing announcements for the ranges of IP addresses the operator holds. GeoIP data, for its part, maps addresses to the country where they are used.

Several features use the result of these lookups:

  • The spam filter uses them as inputs to its rules and its classifier.
  • The expressions evaluated during an SMTP session can test them through the asn and country variables.
  • Sieve scripts that run during the SMTP session see them as env.asn and env.country.
  • The Received header that the server adds to each message includes them, for example (AS64496 Example Networks, DE).

Data sources

Section titled “Data sources”

The lookups are configured on the Asn singleton (found in the WebUI under Settings › Network › ASN & GeoIP). Its variant decides where the data comes from:

  • Resource downloads CSV files that map address ranges to ASNs and countries, and answers lookups from memory. It is the variant created at first start.
  • Dns queries, for each address, a DNS zone that publishes ASN data in TXT records, such as the one operated by Team Cymru. It needs no download, but it adds a DNS query for each new address.
  • Disabled turns the lookups off.

The choice between the first two is a tradeoff between a periodic download and a query per address. Turning the lookups off has a cost of its own, because everything that uses them loses its data: the asn and country variables are empty, the Received header carries no network information, and the spam filter rules and classifier features that depend on the sending network have nothing to work with.

Downloaded lists

Section titled “Downloaded lists”

At first start, the server creates a Resource source. It downloads the IP-to-ASN and IP-to-country lists of the ip-location-db project from GitHub, for IPv4 and IPv6. A server without outbound access to GitHub, or one that should use other data, needs other URLs or another variant, as described in Outbound network requirements.

The Resource variant has settings for what to download, how often, and how to reach the server that hosts the files:

  • asnUrls and geoUrls list the CSV files with ASN and country data.
  • refreshInterval sets how often the files are downloaded again.
  • timeout limits the time for one download.
  • maxSize is the largest file size accepted, in bytes.
  • httpAuth and httpHeaders supply authentication and additional headers, for servers that require them.
  • allowInvalidCerts accepts a server certificate that fails validation. It is meant only for an internal server with a private certificate.

The source created at first start is equivalent to the following object:

{
  "@type": "Resource",
  "refreshInterval": 86400000,
  "timeout": 300000,
  "maxSize": 104857600,
  "asnUrls": {
    "https://github.com/sapics/ip-location-db/releases/download/latest/origin-asn-ipv4.csv": true,
    "https://github.com/sapics/ip-location-db/releases/download/latest/origin-asn-ipv6.csv": true
  },
  "geoUrls": {
    "https://github.com/sapics/ip-location-db/releases/download/latest/user-country-ipv4.csv": true,
    "https://github.com/sapics/ip-location-db/releases/download/latest/user-country-ipv6.csv": true
  },
  "httpAuth": {"@type": "Unauthenticated"}
}

DNS lookups

Section titled “DNS lookups”

The Dns variant sends a TXT query for each address, to zoneIpV4 for IPv4 addresses or zoneIpV6 for IPv6 addresses. The answer is a single string with several fields, which the server splits at separator. indexAsn, indexAsnName and indexCountry then give the zero-based positions of the ASN, the operator name and the country code among those fields.

The following configuration uses the Team Cymru zones:

{
  "@type": "Dns",
  "zoneIpV4": "origin.asn.cymru.com",
  "zoneIpV6": "origin6.asn.cymru.com",
  "separator": "|",
  "indexAsn": 0,
  "indexCountry": 2
}