If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/PBH-BTN/PeerBanHelper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• GPL-3.0 licensed
• CI configured
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live PBH-BTN/PeerBanHelper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/PBH-BTN/PeerBanHelper.

What it runs against: a local clone of PBH-BTN/PeerBanHelper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in PBH-BTN/PeerBanHelper | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of PBH-BTN/PeerBanHelper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/PBH-BTN/PeerBanHelper.git
#   cd PeerBanHelper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of PBH-BTN/PeerBanHelper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "PBH-BTN/PeerBanHelper(\\.git)?\\b" \\
  && ok "origin remote is PBH-BTN/PeerBanHelper" \\
  || miss "origin remote is not PBH-BTN/PeerBanHelper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "build.gradle.kts" \\
  && ok "build.gradle.kts" \\
  || miss "missing critical file: build.gradle.kts"
test -f ".github/workflows/build_gradle.yml" \\
  && ok ".github/workflows/build_gradle.yml" \\
  || miss "missing critical file: .github/workflows/build_gradle.yml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "docker-compose.yml" \\
  && ok "docker-compose.yml" \\
  || miss "missing critical file: docker-compose.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/PBH-BTN/PeerBanHelper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PeerBanHelper is an automated BitTorrent peer blocking firewall that identifies and disconnects unwanted peers (leeches, fake-progress clients, datacenter IPs) by connecting to torrent client APIs (qBittorrent, Deluge, BiglyBT, BitComet, Transmission) and enforcing custom or cloud-based ban rules. It combines PeerID blacklists, GeoIP geolocation filtering, heuristic progress-cheat detection, and expression-engine-based masquerade checks to protect against both passive (IP-based) and active threats in the BitTorrent swarm. Hybrid monorepo: Java backend (src/ with ~2M LOC) implements core blocking logic, peer detection, and API adapters for each torrent client; TypeScript/Vue frontend (~600K + 480K LOC) provides the WebUI (src/views for dashboard, ban lists, rule subscriptions). Both compile into a single Docker image (Dockerfile present). The .claude/ directory suggests use of Claude-assisted development workflows.

Individual BitTorrent users and seedbox operators who want automated protection against ISP throttling, copyright-tracking honeypots, and leeching clients without manual peer management. Also targets admins of private torrent trackers maintaining swarm quality via the cloud rule subscription system (BTN-Collected-Rules).

Actively developed and production-ready: the project has comprehensive documentation, multi-client support (5+ torrent apps), a deployed demo site (pbh-demo.pbh-btn.com), and a mature WebUI with ban history, statistics, and rule management. Recent language diversity (Java backend, TypeScript/Vue frontend) and the presence of GitHub Actions workflows signal ongoing maintenance, though commit recency data is not visible here.

Standard open source risks apply.

Cannot determine from file list alone; however, the presence of .github/prompts/ for opsx (OpenSpec) commands and .claude/skills/ suggests active integration of AI-assisted development and task automation. The comprehensive issue templates (bug_report.yml, web_ui.yml, others.yml) and multiple PR templates (backend.yml, webui.yml) indicate structured contribution workflows.

git clone https://github.com/PBH-BTN/PeerBanHelper.git
cd PeerBanHelper
# For backend (Java): verify Java compiler presence, build via Gradle (not shown but typical)
# For frontend (TypeScript/Vue): npm install && npm run dev
# For Docker: docker build -t pbh . && docker run --net host pbh

Exact build steps require examining build.gradle, pom.xml, or package.json (not in file list provided).

Daily commands: Cannot provide exact commands without pom.xml/build.gradle/package.json; inferred from README: Backend likely requires mvn clean install or gradle build + java -jar app.jar. Frontend: npm install && npm run serve or npm run build. Docker: docker run --net host --env CONFIG_PATH=/config pbh-btn/peerbanhelper (host network mandatory for real peer IPs).

• build.gradle.kts — Primary build configuration for the entire JVM project; all contributors must understand the dependency structure and build tasks
• .github/workflows/build_gradle.yml — CI/CD pipeline that defines how the project is compiled, tested, and released; essential for understanding deployment flow
• README.md — Project overview documenting core functionality (peer blocking, rule engines, multi-client support) that shapes all architectural decisions
• Dockerfile — Containerization definition showing runtime environment setup and how the application is deployed in production
• docker-compose.yml — Local development environment orchestration; critical for onboarding and understanding service dependencies
• .github/copilot-instructions.md — AI-assisted development guidelines and coding standards that maintainers expect contributors to follow
• gradle.properties — Build property definitions including versions and configuration flags that affect compilation and runtime behavior

Add a New Peer Blocking Rule Module

1. Create the rule module class in the backend source (check src/ structure after exploring the repo) (build.gradle.kts)
2. Define the module configuration schema in the configuration section (build.gradle.kts)
3. Add WebUI component for rule configuration in the frontend layer (.github/workflows/build_fe.yml)
4. Update the README.md to document the new blocking module and its capabilities (README.md)
5. Add integration tests following the existing test structure (.github/workflows/jvm-ci.yml)

Add Support for a New BT Client

1. Implement the client API integration in backend (typically in a client-specific adapter module) (build.gradle.kts)
2. Define WebAPI endpoint mappings and authentication handling (build.gradle.kts)
3. Add client-specific UI components to the WebUI for configuration and monitoring (.github/workflows/build_fe.yml)
4. Update docker-compose.yml to include a test instance of the new client for integration testing (docker-compose.yml)
5. Document the client integration steps in README.md (README.md)

Optimize Native Code Performance (GeoIP/Peer Detection)

1. Modify C++ implementation in cpp-src/ghost-common-jni.cpp for performance improvements (cpp-src/ghost-common-jni.cpp)
2. Update build configuration to compile optimized native library (build.gradle.kts)
3. Add performance benchmarks and validation tests in the CI pipeline (.github/workflows/jvm-ci.yml)
4. Document performance changes and JNI interface updates (cpp-src/build.txt)

Add Cloud Rule Subscription Feature

1. Implement rule subscription manager and cloud API client in backend (build.gradle.kts)
2. Create data model for storing subscription metadata and rule definitions (build.gradle.kts)
3. Build WebUI pages for managing subscriptions, viewing updates, and testing rules (.github/workflows/build_fe.yml)
4. Add scheduled update mechanism and cache invalidation logic (docker-compose.yml)
5. Document subscription format and cloud rule API in README.md (README.md)

• JVM/Kotlin/Java — Cross-platform runtime enabling support for multiple operating systems (Linux, Windows, macOS) and easy deployment via Docker while maintaining type safety and extensive library ecosystem
• C++ JNI Native Code — Performance-critical path for peer identification, IP geolocation lookups, and complex hashing operations that demand sub-millisecond latency at scale
• WebUI (JavaScript/React/Vue implied) — Browser-based management interface allowing users to configure rules, monitor bans, and analyze peer data without requiring CLI knowledge
• Docker & Compose — Standardized containerization enabling reproducible deployments across NAS, cloud, and bare-metal while simplifying dependency management and multi-service orchestration
• AviatorScript Expression Engine — User-customizable rule evaluation without requiring code recompilation, enabling community-contributed rules and dynamic filtering logic
• Gradle Build System — Kotlin-based build definition providing type-safe dependency management, plugin composition, and seamless integration with JVM tooling ecosystem

• JVM + Native C++ Hybrid Architecture

  • Why: Achieves both developer velocity (JVM) and performance (C++/JNI) but introduces complexity in dependency management and cross-compilation requirements
  • Consequence: Higher barrier to entry for contributors unfamiliar with JNI; requires platform-specific native builds alongside JVM artifacts

• Cloud Rule Subscriptions + Local Rules

  • Why: Balances centralized threat intelligence with offline resilience and user privacy, but requires conflict resolution and subscription management overhead
  • Consequence: Rule priority/precedence logic becomes complex; potential for outdated local rules if cloud sync fails

• WebUI instead of CLI-only interface

  • Why: Improves user experience and accessibility for non-technical users, but adds frontend maintenance burden and browser compatibility concerns
  • Consequence: Must maintain two parallel interfaces; increased testing matrix for different browsers and operating systems

• Multi-BT Client Support (qB, Deluge, BiglyBT, etc.)

  • Why: Maximizes utility and user base, but requires API compatibility layer abstraction for each client's unique WebAPI implementation
  • Consequence: Breaking changes in one client's API require defensive coding; integration tests must cover all supported clients

• Aggressive Peer

  • Why: undefined
  • Consequence: undefined

1. Host network mandatory: Docker requires --net host, not bridge mode, or peers' real IPs are lost and detection fails completely. 2. GeoIP database startup: application downloads MaxMind GeoIP2 database on first run; requires internet access and sufficient disk space; missing DB silently degrades geolocation features. 3. Torrent client version pinning: qBittorrent ≥4.5.0 (no XDown), Transmission ≥4.1.0-beta2, BitComet ≥2.18; older versions have incompatible APIs. 4. IPv6 support caveat: only traditional IPv4/IPv6; I2P and Tor connections are silently ignored, not banned, which can confuse users expecting universality. 5. Config path: application expects config at /config in Docker or $PWD/config locally; misconfiguration silently fails rule subscriptions.

• Peer ID Spoofing Detection — BitTorrent clients advertise a PeerID in the protocol handshake; malicious clients fake PeerIDs to evade blacklists. PeerBanHelper uses heuristic checks and expression rules to detect mismatches between declared client version and actual behavior.
• GeoIP Geolocation & ASN Filtering — MaxMind GeoIP2 database maps IP addresses to country, city, ASN, and network type (datacenter, mobile, etc.). PeerBanHelper uses this to ban entire geographic regions or cloud providers in a single rule, rather than maintaining millions of IP ranges.
• Heuristic Progress-Cheat Detection — Leeches falsely report 100% download progress to manipulate swarm peer selection. PeerBanHelper monitors upload/download ratios and progress announcements over time to statistically identify anomalies without relying on client signatures.
• Expression Engine (AviatorScript) — Custom ban rules are user-defined scripts (e.g., 'ban if (upload < threshold AND client == 'Fake') evaluated at runtime by AviatorScript JVM engine, allowing flexibility without recompiling PeerBanHelper.
• Distributed Torrent Client API Adapters — PeerBanHelper must query different clients (qBittorrent RPC, Deluge JSON-RPC, BitComet proprietary) via their Web APIs; adapter pattern isolates client-specific protocol details from ban logic, enabling support for multiple clients.
• IPv4/IPv6 Dual-Stack Filtering — Modern swarms include both IPv4 and IPv6 peers; PeerBanHelper must ban on both stacks independently, but silently ignores privacy networks (I2P, Tor) since they obscure real IP identity.
• Active Monitoring & Swarm Analytics — Local analysis module tracks peer behavior (upload speed, progress claims, disconnect patterns) in real-time; aggregated statistics feed the dashboard charts and inform heuristic thresholds for cheat detection.

• PBH-BTN/BTN-Collected-Rules — Companion rule repository; PeerBanHelper downloads and applies these cloud-based peer blacklists via the subscription system in RuleSubscription.vue.
• PBH-BTN/PBH-Adapter-BiglyBT — Official plugin extending PeerBanHelper to support BiglyBT; demonstrates the adapter pattern used for non-qB/Deluge clients.
• PBH-BTN/PBH-Adapter-Deluge — Official Deluge plugin; required alongside PeerBanHelper for Deluge integration, showing modular architecture for client support.
• transmission/transmission — Upstream Transmission BitTorrent client; PeerBanHelper supports Transmission ≥4.1.0-beta2 via its RPC API, making this an integration target.
• qbittorrent/qBittorrent — Most widely supported client (qB ≥4.5.0); PeerBanHelper's primary integration point and reference implementation for other adapters.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for peer detection modules

The repo has multiple detection modules (PeerID blacklist, Client Name blacklist, IP/GeoIP blocking, progress cheat detection, multi-dial hunting) but the file structure shows no visible test directory. This is critical for a security-focused tool that blocks peers - false positives could harm legitimate users. New contributors can add tests for the core detection logic to improve reliability.

• [ ] Create tests/ or tests/ directory structure mirroring src/ modules
• [ ] Add unit tests for peer detection logic (PeerID, Client Name matching)
• [ ] Add integration tests for IP/GeoIP blocking with sample peer data
• [ ] Add tests for AviatorScript expression engine evaluation safety
• [ ] Document test coverage targets in CONTRIBUTING.md

Create GitHub Actions CI/CD workflow for multi-platform builds and testing

The .github/CODEOWNERS and PULL_REQUEST_TEMPLATE files exist, but .github/workflows/ appears missing. Given this tool supports qBittorrent, Deluge, BiglyBT, and BitComet across multiple platforms, automated CI to verify builds and tests on Linux/Windows/macOS would prevent regressions and ensure cross-platform compatibility.

• [ ] Create .github/workflows/build-test.yml for multi-OS (ubuntu, windows, macos) builds
• [ ] Add linting workflow (.github/workflows/lint.yml) to check code style consistency
• [ ] Create .github/workflows/release.yml for automated releases with compiled binaries
• [ ] Integrate test coverage reporting (codecov or similar) in build workflow
• [ ] Document CI expectations in CONTRIBUTING.md with required PR checks

Document cloud rule format and custom rule specification with examples

The README mentions 'cloud rules' and 'customized rules' as key features, and there's an AviatorScript expression engine referenced, but no visible documentation files for rule syntax, format, or validation. Contributors can create a comprehensive rule specification document with examples to help users and contributors understand the rule system.

• [ ] Create docs/RULE_SPECIFICATION.md detailing cloud rule format and schema
• [ ] Add examples/ directory with sample custom rules for common scenarios (e.g., ban residential ISPs, detect protocol violations)
• [ ] Document AviatorScript engine syntax and available variables in docs/EXPRESSION_ENGINE.md
• [ ] Create rule validation/linting guide for contributors submitting cloud rules
• [ ] Add migration guide for users updating rule syntax between versions

• Add unit test suite for backend/src/main/java/rule/PeerIDBlacklist.java; currently no test file visible in the file list, leaving the most critical ban rule unverified.
• Document the ExpressionEngine (AviatorScript) with concrete examples in docs/expression-engine-guide.md; README mentions it but provides no tutorial for users writing custom rules.
• Implement missing WebUI chart for 'Top 50 ASNs' to match 'Top 50 IPs' feature; GeoIP resolver already parses ASN data, frontend just needs a new chart component in src/views/Statistics.vue.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.