Ban Knots Script v1.2.2

Release Notes v1.2.2

Summary

Bug fix for detection bug that prevented the script from working in v1.2.1.

What's Fixed

🐛 Bug Fix

• Fixed Detection Loop: Resolved subshell issue where echo | while caused all detected nodes to be lost. The script now uses arrays to properly track and process detected nodes.

Technical Details

The v1.2.1 release had a bug in the detection loop that used a pipe (echo -e "$KNOTS_NODES" | while), creating a subshell where variable updates were lost. This has been fixed by using a bash array instead.

Note

v1.2.1 does not work correctly due to this bug. All users must update to v1.2.2.

To update:

# Download the fixed version
wget https://github.com/noosphere888/Ban-Knots/releases/download/v1.2.2/standalone-ban-knots.sh
chmod +x standalone-ban-knots.sh

# If you have cron installed, update it
./standalone-ban-knots.sh --uninstall-cron
./standalone-ban-knots.sh --install-cron

Full Changelog: v1.2.1...v1.2.2

Ban Knots Script v1.2.1

Release Notes v1.2.1

Summary

Refined detection method. Removes service flag 26 detection that may be causing false positives or be easily mitigated. Knots nodes set service flag 26, unlike Core but may cause false positives. This is as a precaution and refinement of accuracy.

What's Changed

Bug Fixes

• Refined Detection Method: Service flag 26 is used by Bitcoin Knots to indicate Replace-By-Fee (RBF) policy settings, not as a general Knots identifier. While currently only Knots uses this flag and unlikely to cause issues, relying on it could lead to false positives or be unreliable. The script now uses only user agent detection and IP tracking for best accuracy.
• Better Argument Handling: Fixed issue where -h without an argument would cause the script to fail. Now properly validates all command-line arguments require values. Thank you @Rav3nPL.

Note

The script continues to reliably detect Knots nodes through user agent identification. The service flag check was an experimental addition in v1.2.0 that we've decide to remove for accuracy.

To update:

# Download the fixed version
wget https://github.com/noosphere888/Ban-Knots/releases/download/v1.2.1/standalone-ban-knots.sh
chmod +x standalone-ban-knots.sh

# If you have cron installed, update it
./standalone-ban-knots.sh --uninstall-cron
./standalone-ban-knots.sh --install-cron

Technical Details

• Bitcoin Knots sets service flag 26 only when mempool_opts.rbf_policy == RBFPolicy::Always
• This flag indicates RBF policy, not a general Knots identifier
• Removed to prevent any potential confusion with other implemenatations

What Still Works

• User agent detection for nodes identifying as Knots
• IP banlist tracking (local + optional external)
• All other v1.2.0 features remain functional

Full Changelog: v1.2.0...v1.2.1

Ban Knots Script v1.2.0

Release Notes - v1.2.0

Overview

This release adds enhanced detection capabilities to identify Bitcoin Knots nodes that attempt to hide their identity. The script now uses three detection methods instead of just user agent matching. Additionally, enhanced Umbrel support has been integrated for easy deployment on Umbrel nodes.

New Features

1. Service Flag Detection

• Detects nodes advertising service flag 26 (NODE_KNOTS)
• Identifies "hidden" Knots nodes that disguise their user agent but still advertise Knots-specific features
• More reliable than user agent detection alone

2. Historical IP Banlist Integration (Optional)

• Downloads known Knots node IPs from aeonBTC/Knots-Banlist when using --external-ban-list flag
• Disabled by default for privacy - opt-in with -e flag
• Updates weekly from upstream when enabled
• Merges external list with your local discoveries

3. Local Discovery Tracking

• Saves discovered Knots IPs to ~/.bitcoin/knots-banlist.txt
• When --external-ban-list is used, merges upstream with local discoveries
• All new discoveries are added to the list
• Optional log file (knots-banlist.txt.log) tracks when/how each IP was discovered
• Your personal banlist grows over time

4. Enhanced Statistics

• Shows detection breakdown: how many nodes caught by each method
• Highlights "HIDDEN" nodes (those using service flag 26 but disguised user agent)
• Displays count of locally discovered nodes
• Provides summary of all detection methods used

5. Umbrel Support

• Auto-detection of Umbrel environment
• Automatic Docker container execution for Umbrel nodes
• --umbrel flag for manual override when needed
• Seamless integration with Umbrel's Bitcoin Core setup

What's Changed

• Service flag detection is enabled by default - catches hidden Knots nodes
• Local discovery tracking always active - builds your personal Knots IP list at ~/.bitcoin/knots-banlist.txt
• External IP banlist is opt-in with --external-ban-list flag (privacy-focused)
  • When enabled: Downloads community list and merges with your local discoveries
  • When disabled: Still saves all discovered IPs locally for future runs
• All existing commands and options work exactly the same
• Output now shows which detection method caught each node
• Added credits to projects that inspired the enhanced detection

Example Output

=== Bitcoin Knots Node Ban Script v1.2.0 ===
Platform: Umbrel (using Docker container)
RPC Host: 127.0.0.1:8332
Enhanced Detection: true
External Ban List: true

Updating Knots IP banlist from upstream...
Updated banlist: 13,000+ total IPs (upstream + local)

Total peers: 125

Found 15 Knots node(s):
  By user agent: 8
  By service flag: 12
  By IP list: 3
  Hidden nodes: 4 (flag 26 but disguised UA)

Processing: 192.168.1.100:8333 (/Satoshi:28.1.0/)
  Detection: ServiceFlag-26+HIDDEN
  Status: Banned successfully
  Added new discovery to banlist

Current ban list summary:
Total banned addresses: 42
Knots IP banlist: 13958 total IPs
Recent discoveries: 5 (see /home/user/.bitcoin/knots-banlist.txt.log)

Installation

# Quick install with auto-detection
wget https://github.com/noosphere888/Ban-Knots/releases/download/v1.2.0/standalone-ban-knots.sh && \
chmod +x standalone-ban-knots.sh && \
./standalone-ban-knots.sh --install-cron

Credits

• Service flag detection inspired by caesrcd/gnoban
• IP banlist from aeonBTC/Knots-Banlist
• Enhanced Umbrel support contributed by TMan253 (PR #3)

Compatibility

• Fully backward compatible with v1.1.0
• No breaking changes
• All existing cron jobs continue to work
• Works seamlessly on Umbrel, Start9, and standard Bitcoin Core installations

Ban Knots Script v1.1.0

Ban-Knots v1.1.0 Release Notes

Improvements

Automatic Authentication

• Cookie Authentication by Default: Script now automatically detects and uses Bitcoin Core's .cookie file
• No More Required Credentials: Simply run ./standalone-ban-knots.sh without any parameters
• Smart Fallback Chain: Tries cookie → bitcoin.conf → manual credentials → config file
• Custom Cookie Path: New --cookie-path option for non-standard setups

Platform-Specific Support

Start9 Support

• Auto-Detection: Automatically detects Start9 environment
• Container Support: Handles podman container execution transparently
• Clear Instructions: Helpful error messages guide Start9 users through setup
• Troubleshooting: Dedicated troubleshooting section for Start9-specific issues

Umbrel Support

• Docker Integration: New --umbrel flag for Umbrel compatibility
• Password Fix: Supports passwords containing = characters
• One-Line Install: Quick setup command specifically for Umbrel users

New Features

• Simplified Installation: ./standalone-ban-knots.sh --install-cron works out of the box
• Better Error Messages: Clear guidance when authentication fails
• Platform Detection: Shows detected platform (Start9/Umbrel) during execution
• Improved Cron Support: Better handling of authentication in cron jobs

Technical Changes

• Refactored disconnect/ban logic for better readability (PR #1)
• Fixed password parsing to support special characters
• Removed TTY requirement for container execution (works in cron)
• Made RPC username/password optional in argument parsing

Documentation Updates

• New "Authentication Methods" section explaining the auth hierarchy
• Updated Quick Start with cookie auth as the default option
• Added Start9-specific instructions with podman commands
• Added Umbrel installation instructions
• Updated all examples to show simplified usage
• Added troubleshooting for platform-specific issues

Migration Guide

For Existing Users

Your current setup will continue to work! The script is fully backward compatible:

• Manual credentials (-u/-P) still work and take priority
• Config files (-c) continue to function as before
• Existing cron jobs don't need to be changed

For New Users

Just run the script - it's that simple!

# Download and run
wget https://github.com/noosphere888/Ban-Knots/releases/download/v1.1.0/standalone-ban-knots.sh
chmod +x standalone-ban-knots.sh
./standalone-ban-knots.sh

# Install as cron job
./standalone-ban-knots.sh --install-cron

For Start9 Users

# The script now handles everything automatically
./standalone-ban-knots.sh -u <your-username> -P <your-password>

For Umbrel Users

# Use the new --umbrel flag
./standalone-ban-knots.sh -u <your-username> -P <your-password> --umbrel

Thanks

Special thanks to:

• @Rav3nPL for the disconnect/ban logic improvements (PR #1)
• @TMan253 for Umbrel support and password parsing fix (PR #2)
• The community feedback and testing on X

Bug Fixes

• Fixed Start9 container execution issues
• Fixed password parsing for special characters
• Fixed cron execution on systems without TTY
• Improved error handling for missing authentication

Full Changelog

• Add automatic cookie authentication as default
• Add bitcoin.conf parsing as fallback
• Add Start9 auto-detection and podman support
• Add Umbrel support with --umbrel flag
• Add --cookie-path option for custom cookie locations
• Simplify disconnect/ban logic (PR #1)
• Fix password parsing to support = characters (PR #2)
• Update documentation with platform-specific instructions
• Improve error messages and user guidance
• Make authentication credentials optional
• Add platform detection output

---

Note: This release maintains full backward compatibility. All existing configurations and setups will continue to work without changes.

Ban Knots Script v1.0.0

Initial Release - Bitcoin Knots Ban Script

One-command installation script to automatically ban/disconnect Bitcoin Knots nodes from any Bitcoin Core node.

Quick Install

wget https://github.com/noosphere888/Ban-Knots/releases/download/v1.0.0/standalone-ban-knots.sh && \
chmod +x standalone-ban-knots.sh && \
./standalone-ban-knots.sh -u yourrpcuser -P yourrpcpass --install-cron

Features

• One-command cron installation - set it and forget it!
• Works with any Bitcoin Core node with RPC enabled
• Automatic detection of Knots nodes
• Config file support
• Dry-run mode for testing
• Automatic logging

You'll need SSH access to your Bitcoin node. If you're running:

• Bitcoin Core: ssh [username]@[IP-ADDRESS]
• Umbrel: ssh umbrel@umbrel.local (password: same as web interface)
• Start9: ssh start9@[HOSTNAME].local
• RaspiBlitz: ssh admin@{IP-ADDRESS]
• MyNode: ssh mynode@{IP-ADDRESS]
• RaspiBolt/Custom: ssh [username]@{IP-ADDRESS]

See the README for full documentation