Document rate-limits on the address book updater channel

zebra-network/src/peer/handshake.rs

@@ -914,6 +914,10 @@ where
             // addresses. Otherwise, malicious peers could interfere with the
             // address book state of other peers by providing their addresses in
             // `Version` messages.
+            //
+            // New alternate peer address and peer responded updates are rate-limited because:
+            // - opening connections is rate-limited
+            // - we only send these messages once per handshake
             let alternate_addrs = connected_addr.get_alternate_addrs(remote_canonical_addr);
             for alt_addr in alternate_addrs {
                 let alt_addr = MetaAddr::new_alternate(alt_addr, &remote_services);
@@ -1411,6 +1415,12 @@ where
         Err(err) => {
             tracing::debug!(?err, "heartbeat error, shutting down");
 
+            // # Security
+            //
+            // Peer errors and shutdowns are rate-limited because:
+            // - opening connections is rate-limited
+            // - the number of connections is limited
+            // - after the first error or shutdown, the peer is disconnected
             if let Some(book_addr) = connected_addr.get_address_book_addr() {
                 let _ = address_book_updater
                     .send(MetaAddr::new_errored(book_addr, *remote_services))

zebra-network/src/peer_set/candidate_set.rs

@@ -316,6 +316,12 @@ where
 
     /// Add new `addrs` to the address book.
     async fn send_addrs(&self, addrs: impl IntoIterator<Item = MetaAddr>) {
+        // # Security
+        //
+        // New gossiped peers are rate-limited because:
+        // - Zebra initiates requests for new gossiped peers
+        // - the fanout is limited
+        // - the number of addresses per peer is limited
         let addrs: Vec<MetaAddrChange> = addrs
             .into_iter()
             .map(MetaAddr::new_gossiped_change)

zebra-network/src/peer_set/initialize.rs

@@ -433,6 +433,12 @@ async fn limit_initial_peers(
 
     // Send every initial peer to the address book, in preferred order.
     // (This treats initial peers the same way we treat gossiped peers.)
+    //
+    // # Security
+    //
+    // Initial peers are limited because:
+    // - the number of initial peers is limited
+    // - this code only runs once at startup
     for peer in preferred_peers.values().flatten() {
         let peer_addr = MetaAddr::new_initial_peer(*peer);
         // `send` only waits when the channel is full.