# This file is part of the Prefix WhoIs plug-in for Rspamd.
#
# The software provided in this Distribution is
# Copyright (c) 2001-2026 VOSTROM Holdings, Inc.
#
# The full text of our legal notices is contained in the file called
# COPYING, included with this Distribution.


1) What it is

   The plug-in adds Prefix WhoIs enrichment to Rspamd.  For each message it
   identifies the originator (the first publicly routable hop in the Received
   chain, or X-Originating-IP) and the deliverer (the MTA that connected to
   you), asks Prefix WhoIs (https://pwhois.org/) about both from the live
   global routing table, and writes the answers as headers:

      X-PWhois-Origin: 4.2.2.1
      X-PWhois-Origin-AS: 3356
      X-PWhois-AS-Path: 8220 3356
      X-PWhois-Route-Originated-Date: 2026-08-11T15:08:25Z
      X-PWhois-Route-Originated-TS: 1786460905
      X-PWhois-AS-Org-Name: Level 3 Parent, LLC
      X-PWhois-Org-Name: Level 3 Parent, LLC
      X-PWhois-Net-Name: LVLT-ORG-4-8
      X-PWhois-City: Atlanta
      X-PWhois-Region: Georgia
      X-PWhois-Country: United States of America
      X-PWhois-Country-Code: US

   plus the same set under X-PWhois-Deliverer-* when the deliverer is a
   different address.  Same header set as the Prefix WhoIs Milter.  When no
   public address is found, X-PWhois-Status: No originator identified is
   written instead.

2) Symbols

      PWHOIS                     informational; options carry asn, prefix,
                                 country code and which header identified
                                 the originator.
      PWHOIS_DELIVERER_MISMATCH  originator and deliverer are in different
                                 autonomous systems.
      PWHOIS_FAIL                the server could not be queried in time;
                                 the message passed untouched.

   All three are scored 0 by default; build on them with Rspamd's
   composites, multimap and force_actions modules.  Addresses with no route
   in the table get no headers and no symbol.  PWHOIS_YOUNG_ROUTE is present
   in the source but disabled: route-origination dates are not yet reliable
   enough to score on.  The pwhois_route_age variable is still exported for
   your own rules.

3) Variables for other rules

      pwhois_asn, pwhois_prefix, pwhois_country (alpha-2), pwhois_as_org,
      pwhois_org, pwhois_route_age (days; -1 when unknown or older than the
      available history)

   By default the plug-in also sets asn, ipnet and country, the variables the
   stock asn module publishes, so multimap rules such as

      ASN_BLACKLIST { type = "asn"; map = "/etc/rspamd/asn.map"; }

   evaluate against Prefix WhoIs data with no change.  Set
   set_asn_vars = false to keep the asn module's values instead.

4) Route age

   X-PWhois-Route-Originated-Date is when Prefix WhoIs first saw the prefix
   announced by its current origin AS.  It describes the route, not the
   network: a provider move or a re-announcement makes an old network look
   new for a while.

5) Cost

   Prefix WhoIs is a free community service with a per-address allowance
   (5,000 queries a day by default).  Results are cached for an hour, in
   Redis when configured, so repeat senders cost one query per hour per
   address.  Authenticated submissions and private addresses are skipped.
   Higher limits: https://pwhois.org/contact/?contact=request

6) Installation and configuration are described in INSTALL and in the
   commented conf/pwhois.conf.  Bug reports:
   https://pwhois.org/contact/?contact=support
