Method Details

• initConfig

  private void initConfig()

  Initialize configurable properties. Reads from router config, falls back to defaults.

• reloadConfig

  public void reloadConfig()

  Reload configuration from properties. Called when settings are changed in the console.

• clearSessionBans

  public void clearSessionBans()

  Clear all session-based bans.

• getMaxOffenses

  public int getMaxOffenses()

  Get the current max offenses setting.

  Returns:

  the maximum offenses before auto-ban

• getOffenseWindow

  public long getOffenseWindow()

  Get the current offense window setting in ms.

  Returns:

  the offense window in milliseconds

• getStartupGrace

  public long getStartupGrace()

  Get the current startup grace period in ms.

  Returns:

  the startup grace period in milliseconds

• getBadPacketDuration

  public long getBadPacketDuration()

  Get the current bad packet ban duration in ms.

  Returns:

  the bad packet ban duration in milliseconds

• isBadPacketBanEnabled

  public boolean isBadPacketBanEnabled()

  Check if bad packet auto-ban is enabled.

  Returns:

  true if bad packet auto-ban is enabled

• isCorruptConnectionBanEnabled

  public boolean isCorruptConnectionBanEnabled()

  Check if corrupt connection auto-ban is enabled.

  Returns:

  true if corrupt connection auto-ban is enabled

• isPortHoppingBanEnabled

  public boolean isPortHoppingBanEnabled()

  Check if port hopping auto-ban is enabled.

  Returns:

  true if port hopping auto-ban is enabled

• isBlocklistEnabled

  public boolean isBlocklistEnabled()

  Check if IP blocklist is enabled.

  Returns:

  true if IP blocklist is enabled

• isTorBlocklistEnabled

  public boolean isTorBlocklistEnabled()

  Check if Tor exit node blocklist is enabled.

  Returns:

  true if Tor exit node blocklist is enabled

• isCountryBanEnabled

  public boolean isCountryBanEnabled()

  Check if country-based bans are enabled.

  Returns:

  true if country-based bans are enabled

• isXgBanEnabled

  public boolean isXgBanEnabled()

  Check if XG router bans are enabled. XG = unlimited bandwidth (X), no transit tunnels (G) - often botnet indicators.

  Returns:

  true if XG router bans are enabled

• isLuBanEnabled

  public boolean isLuBanEnabled()

  Check if LU router bans are enabled. LU = low bandwidth tier (L) + unreachable/firewalled (U).

  Returns:

  true if LU router bans are enabled

• isIntroducerBanEnabled

  public boolean isIntroducerBanEnabled()

  Check if introducer-cap router bans are enabled. An SSU2 address advertising more than the spec's five introducers is out of spec - usually a scanner or a modified client - so it can be banned when we learn of it, not only when we handshake.

  Returns:

  true if over-cap introducer bans are enabled

• isInvalidVersionBanEnabled

  public boolean isInvalidVersionBanEnabled()

  Check the invalid-RouterInfo-version ban is enabled. A RouterInfo publishing a version above every released version is fabricated, so it can be banned where it is seen rather than only at the handshake.

  Returns:

  true if fabricated-version bans are enabled

• isPubDateBanEnabled

  public boolean isPubDateBanEnabled()

  Check the invalid-publication-date ban is enabled.

  Returns:

  true if bad-publication-date bans are enabled

• isRUCapsBanEnabled

  public boolean isRUCapsBanEnabled()

  Check the contradictory-reachability-caps ban is enabled.

  Returns:

  true if routers publishing both R and U are banned

• isInvalidVersion

  public static boolean isInvalidVersion(String version)

  Whether a RouterInfo version is above every version that has been released, which makes the RouterInfo fabricated rather than merely old.

  Parameters:

  version - the version string from the RouterInfo, may be null

  Returns:

  true if the version is not a plausible released version

• publishesContradictoryCaps

  public static boolean publishesContradictoryCaps(String caps)

  Whether a capability string claims to be reachable and unreachable at once. The two flags are mutually exclusive by definition, so a router publishing both has assembled its own RouterInfo rather than run a router that measured its reachability.

  Parameters:

  caps - the capability string, may be null

  Returns:

  true if both the R and U flags are present

• shouldPurgeExistingRouters

  public boolean shouldPurgeExistingRouters()

  Check if a retroactive NetDb purge sweep is needed. True if LU/XG/introducer bans, the RouterInfo validation bans (version, publication date, reachability flags), or custom capability bans are enabled.

  Returns:

  true if existing routers should be purged

• getCustomCapabilityBans

  public String getCustomCapabilityBans()

  Get custom capability ban pattern. Format: string of capability letters (e.g., "DG", "UX").

  Returns:

  the custom capability ban pattern, or empty string if none

• shouldBanlistByCapability

  public String shouldBanlistByCapability(String capabilities)

  Check if router capabilities match any of the custom ban patterns.

  A pattern may carry an exclusion group after '!': "G!f" matches routers with G in their caps unless they are also floodfills. Exclusions require at least one required character.

  Comparison is case-sensitive throughout: capability letters are case-significant (lowercase 'f' is floodfill, uppercase letters are separate meanings), so neither the stored patterns nor the router's caps may be case-folded before matching.

  Parameters:

  capabilities - router capabilities string (e.g., "XfP")

  Returns:

  the matched pattern exactly as configured (e.g., "G!f") or null if no match

• matchCapabilityPattern

  static String matchCapabilityPattern(String capabilities, String patternsStr)

  Pure decision helper: match a capabilities string against a comma/space-separated list of capability ban patterns.

  Each pattern is a set of required characters, optionally followed by '!'. A router matches when it carries every required character and none of the excluded ones. A pattern with an empty required part can never match, so a bare exclusion cannot ban the entire network. Case-sensitive: see shouldBanlistByCapability(String).

  Parameters:

  capabilities - router capabilities string, may be null

  patternsStr - configured patterns, may be null or empty

  Returns:

  the first matching pattern as configured, or null if none match

• reduceDurations

  private void reduceDurations(long now)

  When the ban count exceeds BAN_COUNT_BASELINE, proportionally reduce remaining durations of eligible entries (between BAN_REDUCTION_MIN and BAN_REDUCTION_MAX) to keep the list manageable under memory pressure. Scaling: remaining *= max(MIN_BAN_SCALE, (double) BAN_COUNT_BASELINE / count).

  Parameters:

  now - the current time in ms, the reference for each entry's remaining duration

• badPacket

  public void badPacket(String ip, String version)

  Record a bad packet from an IP. If threshold exceeded, ban the IP.

  Parameters:

  ip - IP address (format: "1.2.3.4" or "1.2.3.4:port")

  version - router version info (may be null)

• badPacket

  public void badPacket(Hash hash, String version)

  Record a bad packet from a peer identified by its Router hash. Looks up the RouterInfo from the local netdb to extract the peer's IP address, caps, and version for threshold tracking and full-context BanLogger output. Silently returns if the RouterInfo is not in the netdb or has no reachable address.

  Prefer this overload when a Router hash is available at the call site; otherwise use badPacket(String, String) for IP-only tracking.

  Parameters:

  hash - Router hash (non-null, must exist in local netdb)

  version - router version info (may be null, falls back to RouterInfo version)

• corruptConnection

  public void corruptConnection(String ip, String version)

  Record a corrupt connection (EOF/no data during establishment) from an IP. If threshold exceeded, ban the IP.

  Parameters:

  ip - IP address (format: "1.2.3.4" or "1.2.3.4:port")

  version - router version info (may be null)

• corruptConnection

  public void corruptConnection(Hash hash, String version)

  Record a corrupt connection from a peer identified by its Router hash. Looks up the RouterInfo from the local netdb to extract the peer's IP address, caps, and version for threshold tracking and full-context BanLogger output. Silently returns if the RouterInfo is not in the netdb or has no reachable address.

  Prefer this overload when a Router hash is available at the call site; otherwise use corruptConnection(String, String) for IP-only tracking.

  Parameters:

  hash - Router hash (non-null, must exist in local netdb)

  version - router version info (may be null, falls back to RouterInfo version)

• portHopping

  public void portHopping(String ip)

  Record a port hopping attempt from an IP. If threshold exceeded, ban the IP.

  Parameters:

  ip - IP address (format: "1.2.3.4")

• portHopping

  public void portHopping(Hash hash)

  Record a port hopping attempt from a peer identified by its Router hash. Looks up the RouterInfo from the local netdb to extract the peer's IP address, caps, and version for threshold tracking and full-context BanLogger output. Silently returns if the RouterInfo is not in the netdb or has no reachable address.

  Prefer this overload when a Router hash is available at the call site; otherwise use portHopping(String) for IP-only tracking.

  Parameters:

  hash - Router hash (non-null, must exist in local netdb)

• getRouterIP

  private static String getRouterIP(RouterInfo ri)

  Extract the first reachable IP from a RouterInfo's address list. Iterates over all published addresses and returns the host portion of the first one that has a non-null host string. This is used by the Hash-based overloads to obtain an IP for threshold tracking when the caller only has a Router hash.

  Parameters:

  ri - RouterInfo to extract from (null-safe)

  Returns:

  the IP address string, or null if no address has a host

• getRouterCount

  public int getRouterCount()

  Number of currently banlisted routers.

  Returns:

  the size of the ban map

• getEntries

  public Map<Hash, Banlist.Entry> getEntries()

  Get the banlist entries. For BanlistRenderer in router console. Note - may contain expired entries.

  Returns:

  an unmodifiable map of router hashes to banlist entries

• banlistRouter

  public boolean banlistRouter(Hash peer)

  Ban a router with default duration.

  Parameters:

  peer - the router hash to ban

  Returns:

  true if it WAS previously on the list

• banlistRouter

  public boolean banlistRouter(Hash peer, String reason)

  Ban a router with default duration.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  Returns:

  true if it WAS previously on the list

• banlistRouter

  public boolean banlistRouter(String reasonCode, Hash peer, String reason)

  Ban a router with default duration.

  Parameters:

  reasonCode - separate code so cause can contain {0} for translation

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  Returns:

  true if it WAS previously on the list

• banlistRouter

  public boolean banlistRouter(Hash peer, String reason, String transport)

  Ban a router on a specific transport.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  transport - the transport name to restrict the ban to; null bans on every transport

  Returns:

  true if it WAS previously on the list

• banlistRouterForever

  public boolean banlistRouterForever(Hash peer, String reason)

  Permanently ban a router.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  Returns:

  true if it WAS previously on the list

• banlistRouterForever

  public boolean banlistRouterForever(Hash peer, String reason, String reasonCode)

  Permanently ban a router.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  reasonCode - separate code so cause can contain {0} for translation

  Returns:

  true if it WAS previously on the list

• banlistRouter

  public boolean banlistRouter(Hash peer, String reason, String transport, boolean forever)

  Ban a router with configurable duration and transport.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  transport - the transport name to restrict the ban to; null bans on every transport

  forever - if true, ban permanently

  Returns:

  true if it WAS previously on the list

• banlistRouter

  private boolean banlistRouter(Hash peer, String reason, String reasonCode, String transport, boolean forever)

  Ban a router with automatic duration calculation.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  reasonCode - separate code so cause can contain {0} for translation (may be null)

  transport - the transport name to restrict the ban to; null bans on every transport

  forever - if true, ban permanently

  Returns:

  true if it WAS previously on the list

• banlistRouter

  public boolean banlistRouter(Hash peer, String reason, String reasonCode, String transport, long expireOn)

  Ban a router with a specified expiration time.

  Parameters:

  peer - the router hash to ban

  reason - the human-readable cause of the ban, stored in the entry and shown in the console

  reasonCode - separate code so cause can contain {0} for translation (may be null)

  transport - the transport name to restrict the ban to; null bans on every transport

  expireOn - absolute time when the ban expires, not a duration

  Returns:

  true if it WAS previously on the list

  Throws:

  IllegalArgumentException - if expireOn is before the earliest valid time

• unbanlistRouter

  public void unbanlistRouter(Hash peer)

  Remove a router from the banlist.

  Parameters:

  peer - the router hash to remove from banlist

• unbanlistRouter

  private void unbanlistRouter(Hash peer, boolean realUnbanlist)

  Remove a peer from the banlist, optionally updating message history.

  Parameters:

  peer - the router hash to remove from banlist

  realUnbanlist - if true, update message history

• unbanlistRouter

  public void unbanlistRouter(Hash peer, String transport)

  Remove a router from the banlist for a specific transport.

  Parameters:

  peer - the router hash to remove from banlist

  transport - the transport name whose ban to lift; null lifts the ban on every transport

• unbanlistRouter

  private void unbanlistRouter(Hash peer, boolean realUnbanlist, String transport)

  Remove a router from the banlist.

  Parameters:

  peer - the router hash to remove from banlist

  realUnbanlist - if true, update message history

  transport - the transport name whose ban to lift; null lifts the ban on every transport

• isBanlisted

  public boolean isBanlisted(Hash peer)

  Check if a router is banlisted.

  Parameters:

  peer - the router hash to check

  Returns:

  true if the router is banlisted on any transport

• isBanlisted

  public boolean isBanlisted(Hash peer, String transport)

  Check if a router is banlisted on a specific transport.

  Parameters:

  peer - the router hash to check

  transport - the transport name to check; null matches a ban on any transport

  Returns:

  true if the router is banlisted on the specified transport

• isBanlistedForever

  public boolean isBanlistedForever(Hash peer)

  Check if a router is permanently banlisted.

  Parameters:

  peer - the router hash to check

  Returns:

  true if the router is permanently banlisted

• isBanlistedHostile

  public boolean isBanlistedHostile(Hash peer)

  Check if a router is banlisted with a hostile duration (at least 1 hour).

  Parameters:

  peer - the router hash to check

  Returns:

  true if the router is banlisted with hostile duration

• getBanAge

  public long getBanAge(Hash peer)

  How long the banlist has been holding a peer, in milliseconds.

  This is the discriminator between the two reasons a build request arrives naming a banlisted peer, which need different fixes:

  • old age — the ban predates the build, so peer selection handed out a peer the banlist already held, which is a selection bug;
  • young age — the ban landed while the build was in flight, so the selection was correct and only a selection-time cooldown would stop the next request repeating it.

  The ban duration class cannot substitute: a peer permanently banned mid-flight and one banned last week both report as permanent.

  Parameters:

  peer - the router hash to check

  Returns:

  age of the standing ban in ms, or -1 if the peer is not currently banlisted or the entry predates this field

• getBanCause

  public String getBanCause(Hash peer)

  Reason recorded when the peer was banlisted.

  Diagnostic only. A rejected tunnel build says a peer was banned but not why, so a burst of rejections cannot be attributed to a cause. Without it the only way to find out which subsystem is banning peers is to add temporary logging to each caller.

  Parameters:

  peer - the router hash to check

  Returns:

  the recorded cause code or reason, or null when the peer is not currently banlisted or no cause was recorded