# pbh-btn/peerbanhelper

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/pbh-btn-peerbanhelper).**

5,730 stars · 141 forks · Java · gpl-3.0

## Links

- GitHub: https://github.com/PBH-BTN/PeerBanHelper
- awesome-repositories: https://awesome-repositories.com/repository/pbh-btn-peerbanhelper.md

## Topics

`biglybt` `bitcomet` `bittorrent` `deluge` `dt-torrrent` `dt0001` `gt0002` `gt0003` `hp-torrent` `hp0001` `peerbanhelper` `qbittorrent` `transmission` `xl0012` `xl0018` `xl0019` `xm0001` `xunlei`

## Description

PeerBanHelper is a scriptable BitTorrent peer banning system that automatically detects and blocks malicious, leeching, or unwanted peers using configurable rules, GeoIP data, and scriptable detection logic. It integrates with popular BitTorrent clients through their web APIs to enforce blocking rules automatically, and provides a self-hosted WebUI dashboard for monitoring active bans, historical blocks, and peer lists.

The system distinguishes itself through collaborative threat intelligence, submitting ban reports and peer population data to a central server for aggregate threat analysis while receiving cloud-defined block rules and remote deny lists. It supports GeoIP-based IP filtering to block connections by country, city, ASN, ISP, or network type, and includes an AviatorScript extensible framework that allows loading custom scripts to add new peer-evaluation rules without modifying the core application.

Additional capabilities include subnet multi-dial detection, progress cheat detection, peer history persistence to prevent ban evasion, and remote rule subscription for automatically updating blocking criteria from external sources. The system also provides traffic monitoring and statistics, daily traffic alerts, and upload speed throttling to manage peer traffic. Deployment options include Docker, FreeBSD, and Windows installations.

## Tags

### Networking & Communication

- [Peer Blocking Systems](https://awesome-repositories.com/f/networking-communication/communication-protocols-architectures/communication-protocols-standards/bittorrent-implementations/peer-blocking-systems.md) — Automatically detects and blocks malicious, leeching, or unwanted BitTorrent peers using configurable rules and detection modules.
- [BitTorrent Client Integrations](https://awesome-repositories.com/f/networking-communication/bittorrent-client-integrations.md) — Integrates with popular BitTorrent clients through their Web APIs to enforce blocking rules automatically. ([source](https://docs.pbh-btn.com/))
- [Unwanted Client Blockers](https://awesome-repositories.com/f/networking-communication/bittorrent-client-integrations/unwanted-client-blockers.md) — Automatically identifies and disconnects leeching, anomalous, or unwanted BitTorrent clients via their Web APIs. ([source](https://cdn.jsdelivr.net/gh/pbh-btn/peerbanhelper@master/README.md))
- [GeoIP Database Integrations](https://awesome-repositories.com/f/networking-communication/geoip-database-integrations.md) — Blocks BitTorrent connections based on geographic location, network type, autonomous system, or city using a GeoIP database.
- [GeoIP-Based IP Blocking Tools](https://awesome-repositories.com/f/networking-communication/geoip-database-integrations/geoip-based-ip-blocking-tools.md) — Blocks connections by country, city, ASN, ISP, or network type using downloaded GeoIP databases.
- [Malicious Peer Detectors](https://awesome-repositories.com/f/networking-communication/peer-to-peer-clients/malicious-peer-detectors.md) — Ships multiple detection modules that identify and block malicious BitTorrent peers automatically. ([source](https://docs.pbh-btn.com/))
- [Scriptable Peer Evaluation](https://awesome-repositories.com/f/networking-communication/peer-to-peer-networking-extensions/scriptable-peer-evaluation.md) — Provides a scriptable engine using AviatorScript to define custom peer-blocking rules without modifying the core application.
- [Client Name Blocking](https://awesome-repositories.com/f/networking-communication/bittorrent-clients/client-name-blocking.md) — Matches the client name reported by a peer and blocks connections from unwanted BitTorrent clients. ([source](https://docs.pbh-btn.com/docs/module/client-name))
- [Remote Deny List Enforcers](https://awesome-repositories.com/f/networking-communication/ip-address-management-systems/static-ip-enforcement/remote-deny-list-enforcers.md) — Blocks connections from IP addresses or CIDR ranges specified by a remote server immediately upon receipt. ([source](https://docs.pbh-btn.com/docs/btn/intro))
- [Peer History Persistence](https://awesome-repositories.com/f/networking-communication/peer-to-peer-clients/peer-history-persistence.md) — Persists peer progress data to a database to prevent ban evasion by reconnecting peers.
- [Peer Population Snapshots](https://awesome-repositories.com/f/networking-communication/peer-to-peer-clients/peer-population-snapshots.md) — Periodically uploads tracked peer activity and last-seen snapshots to a remote server for aggregate threat analysis. ([source](https://docs.pbh-btn.com/docs/btn/intro))
- [Multi-Dial Peer Hunters](https://awesome-repositories.com/f/networking-communication/peer-to-peer-networking/subnet-peer-managers/multi-dial-peer-hunters.md) — Provides a subnet scanning feature that hunts for additional peers after detecting multi-dial IPs. ([source](https://docs.pbh-btn.com/docs/module/multi-dial))
- [Multi-Dial Subnet Detectors](https://awesome-repositories.com/f/networking-communication/subnet-routing/subnet-analyzers/multi-dial-subnet-detectors.md) — Monitors active peers and automatically bans an entire subnet when multi-dial IPs exceed a threshold on the same torrent.
- [Subnet Multi-Dial Detectors](https://awesome-repositories.com/f/networking-communication/subnet-routing/subnet-analyzers/subnet-multi-dial-detectors.md) — Implements subnet multi-dial detection to automatically ban entire subnets exceeding a connection threshold. ([source](https://docs.pbh-btn.com/docs/module/multi-dial))

### System Administration & Monitoring

- [Peer Banning Systems](https://awesome-repositories.com/f/system-administration-monitoring/bittorrent-clients/peer-banning-systems.md) — Automatically detects and blocks malicious BitTorrent peers using configurable rules, GeoIP data, and scriptable detection logic.
- [Progress Cheat Detectors](https://awesome-repositories.com/f/system-administration-monitoring/activity-monitors/torrent-progress-monitors/progress-cheat-detectors.md) — Monitors peer download progress across all active torrents and bans peers that misreport or reset their progress. ([source](https://docs.pbh-btn.com/docs/module/progress-cheat-blocker))
- [Built-in WebUI Dashboards](https://awesome-repositories.com/f/system-administration-monitoring/built-in-webui-dashboards.md) — Ships a built-in WebUI dashboard for monitoring active bans, historical blocks, and peer lists.
- [Peer Traffic Statistics Dashboards](https://awesome-repositories.com/f/system-administration-monitoring/peer-traffic-statistics-dashboards.md) — Tracks peer traffic, ban history, and connection data over time to power visual statistics and trend charts through a built-in WebUI.
- [Self-Hosted Peer Ban Dashboards](https://awesome-repositories.com/f/system-administration-monitoring/self-hosted-system-dashboards/self-hosted-peer-ban-dashboards.md) — Provides a built-in WebUI dashboard displaying active bans, historical blocks, top banned IPs, GeoIP data, and peer lists.

### Data & Databases

- [GeoIP Databases](https://awesome-repositories.com/f/data-databases/geoip-databases.md) — Uses a downloaded GeoIP database to block IPs by country, city, ASN, ISP, or network type.
- [Ban List Snapshots](https://awesome-repositories.com/f/data-databases/data-snapshotting/periodic-snapshots/ban-list-snapshots.md) — Periodically uploads local ban lists and associated data snapshots to a remote server for aggregate threat analysis. ([source](https://docs.pbh-btn.com/docs/btn/intro))
- [Peer Progress Persistence](https://awesome-repositories.com/f/data-databases/peer-discovery-persistence/peer-progress-persistence.md) — Persists peer progress data to a database so reconnecting peers cannot evade bans by resetting statistics. ([source](https://docs.pbh-btn.com/docs/module/progress-cheat-blocker))
- [Distributed Leech Detectors](https://awesome-repositories.com/f/data-databases/visitor-identification/leech-management/distributed-leech-detectors.md) — Detects leechers who download the same file from multiple users by analyzing total download volume per IP across torrents. ([source](https://docs.pbh-btn.com/docs/btn/intro))

### Development Tools & Productivity

- [Scriptable Peer Evaluation Frameworks](https://awesome-repositories.com/f/development-tools-productivity/extensible-application-frameworks/scriptable-peer-evaluation-frameworks.md) — Ships an AviatorScript-based framework that loads custom scripts to extend peer-blocking logic without modifying the core application.
- [Peer Evaluation Scripts](https://awesome-repositories.com/f/development-tools-productivity/workflow-automation-tools/automation-execution-frameworks/automation-scripts/script-actions/peer-evaluation-scripts.md) — Loads custom AviatorScript files that return values to ban a peer, skip other rules, or take no action. ([source](https://docs.pbh-btn.com/docs/module/expression-engine))
- [AviatorScript Peer Evaluation Extensions](https://awesome-repositories.com/f/development-tools-productivity/workflow-automation-tools/system-integration-interfaces/automation-apis/scripting-apis/custom-logic-extensions/aviatorscript-peer-evaluation-extensions.md) — Loads custom AviatorScript files to add new peer-evaluation logic without modifying the core application. ([source](https://docs.pbh-btn.com/docs/module/expression-engine))

### Security & Cryptography

- [Custom Peer Blocking Rules](https://awesome-repositories.com/f/security-cryptography/identity-access-management/access-control/custom-access-rules/custom-peer-blocking-rules.md) — Blocks peers based on configurable criteria such as Peer ID, client name, IP type, GeoIP location, or fake progress heuristics. ([source](https://cdn.jsdelivr.net/gh/pbh-btn/peerbanhelper@master/README.md))
- [Ban History and Statistics](https://awesome-repositories.com/f/security-cryptography/automated-ip-banning/ban-history-and-statistics.md) — Displays active bans, historical blocks, top banned IPs, GeoIP data, and peer lists through a built-in WebUI. ([source](https://cdn.jsdelivr.net/gh/pbh-btn/peerbanhelper@master/README.md))
- [Remote Rule Subscription Blockers](https://awesome-repositories.com/f/security-cryptography/automated-ip-banning/remote-rule-subscription-blockers.md) — Subscribes to remote rule lists and immediately bans any connecting client whose IP matches an entry. ([source](https://docs.pbh-btn.com/docs/module/ip-address-blocker-rules))
- [Subnet Cascade Banners](https://awesome-repositories.com/f/security-cryptography/automated-ip-banning/subnet-cascade-banners.md) — Scans all connected peers when an IP is banned and automatically bans any peer in the same subnet. ([source](https://docs.pbh-btn.com/docs/module/auto-range-ban))
- [IP and CIDR Blocking](https://awesome-repositories.com/f/security-cryptography/ip-blacklisting/ip-and-cidr-blocking.md) — Blocks connections from specific IP addresses or CIDR ranges by adding them to the downloader's blacklist. ([source](https://docs.pbh-btn.com/docs/module/ip-address-blocker))
- [ASN-Based Blocking](https://awesome-repositories.com/f/security-cryptography/network-access-control/topology-visualizers/asn-visualization/asn-based-blocking.md) — Blocks all IP addresses belonging to a given ASN by querying a GeoIP ASN database. ([source](https://docs.pbh-btn.com/docs/module/ip-address-blocker))
- [Collaborative Threat Intelligence Clients](https://awesome-repositories.com/f/security-cryptography/threat-intelligence-aggregation/collaborative-threat-intelligence-clients.md) — Submits ban reports and peer population data to a central server for aggregate threat analysis and receives cloud-defined block rules.
- [Peer Ban Reports](https://awesome-repositories.com/f/security-cryptography/threat-intelligence-platforms/intelligence-reporting/peer-ban-reports.md) — Collects and reports banned peers from local clients to a central server, enabling collaborative threat detection. ([source](https://docs.pbh-btn.com/docs/btn/intro))
- [Ban Report Submissions](https://awesome-repositories.com/f/security-cryptography/threat-intelligence-platforms/threat-intelligence-synchronizers/ban-report-submissions.md) — Submits ban reports and peer population data to a central server for aggregate threat analysis and receives remote deny lists.

### Part of an Awesome List

- [Country-Based Blocking](https://awesome-repositories.com/f/awesome-lists/data/country-and-regional-data/country-identifiers/country-based-blocking.md) — Blocks all connections from IP addresses geolocated to a specified country using a GeoIP city database. ([source](https://docs.pbh-btn.com/docs/module/ip-address-blocker))

### Education & Learning Resources

- [Cloud-Defined Block Rules](https://awesome-repositories.com/f/education-learning-resources/blocking-rule-sets/cloud-defined-block-rules.md) — Receives and enforces anti-leech rules generated by a remote server as a supplement to local detection rules. ([source](https://docs.pbh-btn.com/docs/btn/intro))
- [Custom IP Block Rules](https://awesome-repositories.com/f/education-learning-resources/blocking-rule-sets/custom-ip-block-rules.md) — Loads a rule set composed of IP addresses, CIDR ranges, and comments to define which clients to block. ([source](https://docs.pbh-btn.com/docs/module/ip-address-blocker-rules))
- [Remote IP Rule Subscriptions](https://awesome-repositories.com/f/education-learning-resources/blocking-rule-sets/remote-ip-rule-subscriptions.md) — Subscribes to remote IP set rule lists to automatically update blocking criteria from external sources. ([source](https://cdn.jsdelivr.net/gh/pbh-btn/peerbanhelper@master/README.md))
- [Remote Rule Subscriptions](https://awesome-repositories.com/f/education-learning-resources/blocking-rule-sets/remote-rule-subscriptions.md) — Subscribes to remote IP set rule lists and cloud-defined block rules to automatically update blocking criteria.

### Graphics & Multimedia

- [Excessive Download Blocking](https://awesome-repositories.com/f/graphics-multimedia/download-output-configuration/download-behavior-configurations/excessive-download-blocking.md) — Bans peers that download more data than the total size of the torrent, indicating malicious over-downloading behavior. ([source](https://docs.pbh-btn.com/docs/module/progress-cheat-blocker))

### Scientific & Mathematical Computing

- [City-Based Blocking](https://awesome-repositories.com/f/scientific-mathematical-computing/data-modeling-processing/geospatial-and-location-services/location-services/address-localization/ip-to-city-localization/city-based-blocking.md) — Blocks connections from IP addresses whose city name matches a given keyword, using a GeoIP city database. ([source](https://docs.pbh-btn.com/docs/module/ip-address-blocker))

### Software Engineering & Architecture

- [AviatorScript Plugin Loaders](https://awesome-repositories.com/f/software-engineering-architecture/integration-extensibility/extensibility/plugin-architectures/developer-authoring-interfaces/custom-module-implementations/module-functionality-extenders/plugin-extenders/aviatorscript-plugin-loaders.md) — Loads custom AviatorScript files to extend peer-evaluation logic without modifying the core application.

### Web Development

- [PeerID Pattern Matchers](https://awesome-repositories.com/f/web-development/client-application-identification/peerid-pattern-matchers.md) — Matches incoming BitTorrent connections against known PeerID patterns to detect and block unwanted clients. ([source](https://docs.pbh-btn.com/docs/module/peer-id))