Bitcoin Core listbanned RPC: Peer-Defence Guide

This guide explains Bitcoin Core listbanned RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Local state only

A ban exists on the queried node and may reflect automatic scoring or operator action under that version and policy. Another node can legitimately differ. Do not distribute entries as authoritative threat intelligence without independent evidence.

Address and subnet scope

Entries can cover individual addresses or broader subnets. Review prefix scope carefully because a mistaken broad range can remove many honest peers and reduce network diversity. Normalise identifiers without expanding their reach.

Duration and expiry

Correlate entries with setban state, creation time and expiry fields provided by the actual running version. A snapshot alone cannot explain why the ban occurred or whether it remains justified. Preserve incident timing separately.

Privacy and security

Raw addresses reveal peer and defence information. Restrict RPC, redact ordinary reports and apply short retention unless investigation requires more. Never publish the full list as a status badge.

False positives and diversity

Network errors, shared NAT, buggy peers and adversarial traffic can all precede a ban. Measure outbound diversity and chain freshness before and after changes. Clearing bans indiscriminately can restore attacks; retaining mistaken bans can isolate the node.

Operational workflow

Review evidence, scope and expiry; compare independent nodes and logs; change only the exact entry through approved setban procedures; then monitor reconnection and sync. Keep a rollback record and avoid broad clearbanned use during an incident.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

listbanned exposes useful local defence state but no universal reputation. Safe operations protect identifiers, retain incident context and balance exact ban scope against peer diversity and connectivity.