NodeSeek Rulings Search Bot

Overview

NodeSeek Rulings Search Bot is a Telegram bot that automatically crawls and stores moderation records (rulings) from the NodeSeek forum. The data is saved in a local SQLite database, allowing users to query a specific user’s punishment history at any time via Telegram.

The project offers two execution modes:

• Full mode (scan.py) – Includes the crawler and the query interface. Ideal for administrators who want to keep the database up‑to‑date.
• Public mode (scan_public.py) – Query‑only version with built‑in rate limiting (100 requests/min). Perfect for deploying a read‑only service to the public.

You can access the all information in the GitHub Repository: NodeSeek Rulings Search Bot

---

✨ Key Features

• Dual‑mode operation – Full crawler vs. lightweight public query.
• Scheduled crawling – Automatic daily incremental fetch at 00:00:00 (also manually triggerable in full mode).
• External configuration – All bot tokens, admin IDs, DB path, etc., are stored in config.json.
• Hot‑update cookies – In full mode, admins can update the crawling cookie via a Telegram command (protected by a password).
• Human‑readable translations – Raw JSON actions are translated into Chinese descriptions (post moves, lock/unlock, coin rewards, bans, etc.).
• Statistics – Query total records, most‑recorded user, most active admin, yesterday’s count, etc.
• Security – Search results are HTML‑escaped, and public mode includes a sliding‑window rate limiter.
• Cookie expiry alerts – Full mode notifies admins when a 403 error occurs due to an expired cookie.

---

🚀 Quick Start

1. Install dependencies

# Requires Python 3.8+
pip install python-telegram-bot[job-queue] curl_cffi

curl_cffi is used to mimic a browser fingerprint and bypass basic anti‑scraping measures.

2. Initialise configuration

Run any script (e.g., python scan.py) once to generate a default config.json. Then edit the file according to the mode you plan to use.

Full‑mode (scan.py) example

{
    "BOT_TOKEN": "YOUR_TELEGRAM_BOT_TOKEN",
    "ADMIN_CHAT_ID": 123456789,
    "DB_FILE": "nodeseek_ruling.db",
    "COOKIE_FILE": "cookie.txt",
    "API_URL_TEMPLATE": "https://www.nodeseek.com/api/admin/ruling/id-{}",
    "PASSWORD": "YOUR_ADMIN_PASSWORD"
}

Public‑mode (scan_public.py) example

{
    "BOT_TOKEN": "YOUR_TELEGRAM_BOT_TOKEN",
    "DB_FILE": "nodeseek_ruling.db"
}

Field	Description
BOT_TOKEN	Token obtained from @BotFather
ADMIN_CHAT_ID	(Full mode) Telegram ID of the admin who receives crawl reports and alerts
PASSWORD	(Full mode) Password required to update the cookie via Telegram
DB_FILE	Path to the SQLite database

3. Run the project

• Full mode (crawling + query):

  python scan.py

• Public query only:

  python scan_public.py

The bot will start listening for commands. Common commands include:

• /search <username> – Retrieve the ruling history of a user.
• /stats – Show overall statistics.
• /update_cookie <new_cookie> – (Full mode, admin only) Refresh the crawling cookie.

---

📦 Project Structure

NodeSeek-Rulings-Search/
├─ config.json          # generated configuration file
├─ nodeseek_ruling.db   # SQLite database (auto‑created)
├─ scan.py              # Full mode script (crawler + bot)
├─ scan_public.py       # Public query script (bot only)
├─ cookie.txt           # Optional cookie file for authenticated crawling
└─ README.md            # Project documentation (this page)

---

🛠️ Technical Details

• Crawler – Uses curl_cffi to perform HTTP requests with a realistic user‑agent and cookie handling.
• Database – Simple SQLite schema storing ruling_id, user_id, action_type, timestamp, and a human‑readable description.
• Telegram Bot – Built with python-telegram-bot’s JobQueue for scheduled crawling and command handling.
• Rate Limiting – Public mode employs a sliding‑window algorithm limiting each user to 100 queries per minute.

---

🎉 Conclusion

NodeSeek Rulings Search Bot provides a convenient way to keep track of moderation actions on the NodeSeek forum and expose them via a friendly Telegram interface. Whether you need a full‑featured admin tool or a lightweight public query service, the dual‑mode design lets you choose the right balance of functionality and security.

Feel free to clone the repository, adjust the configuration, and start the bot to explore the ruling history of any NodeSeek user!