13 improvements across security, architecture, and quality of life to…

[xPloits3c]

Pull Request: TELE-TRACE v2.1 — Security, Architecture & QoL Improvements

Summary

This PR applies 13 improvements across security, architecture, and quality of life to the TELE-TRACE codebase. The patched file (tele_trace_patched.py) is a complete drop-in replacement for the original tele_trace.py — all endpoints, all 9 platform checkers, Telegram auth, media download, SangMata history, catbox.moe upload, and the startup banner are fully preserved and functional.

No external dependencies have been added. No template or static file changes are required.

---

⚠️ IMPORTANT — Testing Disclaimer

The Telethon logic has been significantly refactored. The two original scan functions (_scan and _scan_username) have been decomposed into shared helper functions (_extract_profile, _download_all_media, _collect_history_response, etc.). While the refactored code preserves the exact same logical flow, API calls, and data structure of the original, it has not been tested against a live Telegram account.

Before merging or deploying to production, the maintainer should:

1. Run a full end-to-end test with valid Telegram API credentials (api_id + api_hash).
2. Test phone number scan — verify that contact import, profile extraction, photo download, and SangMata history all return correct data.
3. Test username scan — verify that get_entity(), profile extraction, and history collection work as expected.
4. Test edge cases — accounts with no profile photo, accounts with video profile pictures, private accounts, bot accounts, accounts with multiple usernames, and accounts with 2FA enabled.
5. Test the SangMata bot interaction — confirm that the parallel request pattern (send history request → download photos → collect response) still works correctly with the centralized _send_history_request() / _collect_history_response() helpers.
6. Verify the cross-platform scanner — run a platform_scan and confirm all 9 checkers return accurate results with SSL verification now enabled.

The existing templates/ and static/ files require no changes and are fully compatible with this update.

---

Changes Overview

#	Category	Fix	Impact	Effort
1.1	Security	Re-enable SSL	CRITICAL — security	Low
1.2	Security	Timeout on run_async()	CRITICAL — stability	Low
1.3	Security	Eliminate except: pass	HIGH — debuggability	Medium
1.4	Security	Input validation	HIGH — security	Low
1.5	Security	Rate limiting	HIGH — account protection	Medium
2.1	Architecture	Refactor duplication	MEDIUM — maintainability	High
2.2	Architecture	Concurrency lock	MEDIUM — correctness	Low
2.3	Architecture	Centralized parsing	MEDIUM — maintainability	Medium
3.1	Quality of Life	Env vars config	LOW — flexibility	Low
3.2	Quality of Life	Health check endpoint	LOW — operability	Low
3.3	Quality of Life	Graceful shutdown	LOW — cleanliness	Low
3.4	Quality of Life	MIME detection fix	LOW — correctness	Low
3.5	Quality of Life	Structured logging	LOW — operability	Medium

---

Detailed Changelog

1. CRITICAL SECURITY FIXES

1.1 — Re-enable SSL Certificate Verification

Problem: Both _http_get() and _http_post_json() explicitly disabled TLS certificate verification with ctx.check_hostname = False and ctx.verify_mode = ssl.CERT_NONE. Every outbound request to GitHub, Instagram, Reddit, Discord, LinkedIn, and all other platforms was vulnerable to Man-in-the-Middle attacks.

Fix: Removed the two offending lines. Both functions now use ssl.create_default_context() which enables full certificate verification by default. Added explicit ssl.SSLCertVerificationError handling with a logged warning instead of silent failure. Also applied the same fix to the catbox.moe upload in /api/upload_for_search.

Note for Termux users: If SSL errors occur due to missing CA certificates, install them with pkg install ca-certificates rather than disabling verification.

---

1.2 — Add Timeout to run_async()

Problem: The run_async() bridge function called .result() with no timeout. If any Telethon coroutine hung (network issue, unresponsive bot, DNS failure), the calling Flask thread would block indefinitely, making the entire application unresponsive.

Fix: Added a configurable timeout (default: 120 seconds, adjustable via TELETRACE_TIMEOUT env var). On timeout, the future is cancelled and a clear TimeoutError is raised with a descriptive message. The 120-second default is generous enough to accommodate slow photo downloads while still protecting against infinite hangs.

---

1.3 — Eliminate Bare except: pass Statements

Problem: The original code contained numerous except: pass blocks that silently swallowed all exceptions — including KeyboardInterrupt, SystemExit, and real bugs. This made debugging nearly impossible and masked errors that could corrupt state.

Fix: Every bare except: pass has been replaced with either:

• except (AttributeError, TypeError) for known-safe attribute access patterns (name, bio, status extraction)
• except Exception as e: logger.warning(...) for operations where failure is non-critical but should be logged (contact deletion, file removal, photo download)
• except Exception as e: logger.error(..., exc_info=True) for endpoint-level errors where a full traceback is valuable

A global logger (logging.getLogger("tele-trace")) is configured at module level and used consistently throughout the codebase.

Locations patched (complete list):

• _make_client() — old client disconnect
• _scan() → DeleteContactsRequest — temp contact removal
• _scan() / _scan_username() → name, bio, status, emoji_status extraction
• _scan() / _scan_username() → profile photo fallback download
• _scan_username() → get_entity() failure
• logout() → session file and config file removal
• upload_for_search() — catbox.moe upload
• All photo/video download loops
• _fmt_photo_date() — date parsing
• check_discord() — JSON parsing

---

1.4 — Input Validation on API Endpoints

Problem: No input validation was performed on any endpoint. Malformed phone numbers, invalid usernames, or unexpected input types could cause crashes, confusing error messages, or unintended Telegram API calls.

Fix: Added two validation helpers:

• validate_phone() — strips whitespace/dashes/parens, validates against ^\+?[1-9]\d{6,14}$
• validate_username() — strips @ prefix, validates against ^[a-zA-Z0-9_\.]{1,64}$

Applied to /api/scan, /api/send_code, and /api/platform_scan. Invalid input returns a 400 with a clear error message. TimeoutError returns 504. Unexpected exceptions return 500 with a generic message (details logged server-side).

Also added user_id type validation on /api/history to catch non-numeric input early.

---

1.5 — Basic Rate Limiting

Problem: No rate limiting existed on any endpoint. An attacker (or even an overeager user) could spam /api/scan and trigger a flood of ImportContactsRequest calls to Telegram, risking an account ban or temporary restriction.

Fix: Implemented SimpleRateLimiter, an in-memory per-IP rate limiter with configurable window and max requests. Applied via a @rate_limited decorator to the three most sensitive endpoints:

• /api/scan — Telegram profile scan
• /api/platform_scan — 9-platform username check
• /api/upload_for_search — catbox.moe image upload

Defaults: 5 requests per 60-second window per IP. Configurable via TELETRACE_RATE_MAX and TELETRACE_RATE_WINDOW environment variables. Exceeded limits return 429 Too Many Requests.

---

2. ARCHITECTURAL REFACTORING

2.1 — Eliminate _scan / _scan_username Duplication

Problem: _scan() (phone lookup) and _scan_username() (username lookup) were two massive functions that shared approximately 80% of their code: name/bio/status extraction, flags, extra fields, usernames, emoji status, account age estimation, SangMata history interaction, photo/video download, and deduplication. Every bug fix or feature addition had to be applied in both places — and several inconsistencies already existed between them.

Fix: Extracted all shared logic into dedicated helper functions:

Helper	Responsibility
_get_user_from_full()	Extract user object from GetFullUserRequest result
_parse_status()	Parse online status into (status_text, css_class)
_extract_extra_fields()	Extract all UserFull metadata fields
_extract_usernames()	Extract all usernames (including multiple)
_extract_emoji_status()	Extract emoji status document ID
_fmt_photo_date()	Format photo date from Photo object
_send_history_request()	Send user_id to SangMata bot, return (bot, last_id)
_collect_history_response()	Poll for and parse SangMata response
_download_all_media()	Download all profile photos/videos with dedup
_extract_profile()	Orchestrator — calls all of the above

After refactoring, _scan() and _scan_username() are each ~20 lines: they resolve the user (via phone import or get_entity), call _extract_profile(), set the phone field, and return. ~300 lines of duplicated code eliminated.

The return data structure is identical to the original — no frontend changes needed.

---

2.2 — Concurrency Lock on Global State

Problem: The _state dictionary (client, phone_code_hash, login_phone) was shared across Flask threads with no synchronization. Concurrent requests could overwrite phone_code_hash during login, corrupt the client reference during reconnection, or cause race conditions during logout.

Fix: Added _state_lock = threading.Lock() and applied it to all functions that modify _state:

• _make_client() — protects client replacement
• _send_code() — protects phone_code_hash and login_phone writes
• _logout() — protects full state reset

Read-only access to _state["client"] in scan functions does not require the lock since Python’s GIL provides atomic reference reads.

Note: This is the minimum viable fix. True multi-user support would require per-session client instances or a client pool — documented as a future improvement.

---

2.3 — Centralized SangMata Parsing

Problem: The SangMata bot response parsing logic (quota detection, section splitting, entry regex extraction) was duplicated in three places: _get_history(), inline in _scan(), and inline in _scan_username(). Each copy had subtle differences in variable naming but identical logic.

Fix: Extracted _parse_sangmata_response(text: str) -> dict as a single pure function. It handles:

• None/empty text → {"error": "Bot did not respond"}
• Quota detection (“quota” or “sorry” in response) → {"error": "quota_exceeded", "quota_error": "..."}
• Section parsing (Names / Usernames headers with optional markdown bold)
• Entry extraction via the [date] value regex pattern
• Empty result → {"error": "No history recorded"}

All three call sites now use this single function, ensuring consistent behavior and a single place to fix parsing bugs.

---

3. QUALITY OF LIFE IMPROVEMENTS

3.1 — Configuration via Environment Variables

Problem: Host, port, timeouts, and rate limit parameters were hardcoded, making deployment inflexible — especially across different environments (Termux, VPS, Docker).

Fix: Added a CONFIG dictionary at module level that reads from environment variables with sensible defaults:

Variable	Default	Description
TELETRACE_HOST	0.0.0.0	Bind address
TELETRACE_PORT	7777	Server port
TELETRACE_DEBUG	false	Flask debug mode
TELETRACE_TIMEOUT	120	Async operation timeout (seconds)
TELETRACE_RATE_MAX	5	Max requests per rate limit window
TELETRACE_RATE_WINDOW	60	Rate limit window (seconds)

Usage: TELETRACE_PORT=8080 TELETRACE_RATE_MAX=10 python tele_trace.py

---

3.2 — Health Check Endpoint

Problem: No way to programmatically verify the tool’s status without attempting a scan.

Fix: Added GET /api/health which returns:

{
  "server": "ok",
  "event_loop": true,
  "client_initialized": true,
  "session_file_exists": true,
  "config_file_exists": true,
  "telegram_auth": true
}

Returns 200 when the server is operational. Telegram auth check has a 10-second timeout to avoid hanging the health endpoint. Useful for monitoring, uptime checks, and debugging connection issues.

---

3.3 — Graceful Shutdown

Problem: The async event loop ran as a daemon thread and was killed abruptly on Ctrl+C or SIGTERM. This could leave the Telegram session in a dirty state (open connection, pending requests).

Fix: Registered signal handlers for SIGINT and SIGTERM that:

1. Disconnect the Telegram client cleanly (with a 5-second timeout)
2. Stop the async event loop via call_soon_threadsafe
3. Log the shutdown
4. Exit cleanly via SystemExit(0)

---

3.4 — Fix MIME Type Detection

Problem: The original MIME detection used fragile byte offset checks:

if raw[1:4] == b"PNG":      # Works by accident (PNG sig = \x89PNG...)
elif raw[8:12] == b"WEBP":   # Correct offset but missing RIFF check

The PNG check only worked because bytes 1-3 of the PNG signature happen to be PNG, but this is not a proper magic byte check. The WEBP check was missing validation of the RIFF header at bytes 0-3. Neither check handled JPEG or GIF, and no bounds checking was performed on short byte sequences.

Fix: Replaced with a proper detect_mime() function that checks:

• PNG: full 8-byte signature \x89PNG\r\n\x1a\n
• WEBP: RIFF at bytes 0-3 AND WEBP at bytes 8-11
• JPEG: \xff\xd8 at bytes 0-1
• GIF: GIF8 at bytes 0-3
• Length check (< 12 bytes → fallback to JPEG)

Applied to all photo download paths and the profile photo fallback.

---

3.5 — Structured Logging Replaces print()

Problem: All diagnostic output used print() with ad-hoc [History], [SSL] prefixes. No timestamps, no log levels, no ability to filter or redirect output. Error output was mixed with informational messages.

Fix: Configured Python’s logging module at the top of the file:

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
    datefmt="%H:%M:%S",
)
logger = logging.getLogger("tele-trace")

All print() calls converted to appropriate log levels:

• logger.info() — successful operations (history response received, scan complete)
• logger.warning() — non-critical failures (contact deletion failed, SSL error, extra field extraction issue)
• logger.error() — endpoint failures with exc_info=True for full tracebacks
• logger.debug() — verbose diagnostics (individual photo download failures, disconnect errors)

Werkzeug’s internal logger remains set to ERROR to keep the console clean during normal operation.

---

Files Changed

File	Action	Description
tele_trace.py → tele_trace_patched.py	Modified	Complete rewrite with all 13 fixes applied
IMPROVEMENTS.md	Added	This file — detailed changelog and testing instructions
templates/*	Unchanged	No frontend changes required
static/*	Unchanged	No static asset changes required

---

Compatibility

• Python: 3.8+ (same as original)
• Dependencies: No new packages required (Flask, Telethon, standard library only)
• Termux: Fully compatible — env vars work in Termux shell
• Templates/Static: 100% backward compatible — same endpoints, same response format
• API Response Format: Identical to v2.0 — no breaking changes for any frontend consumer

---

How to Test

# 1. Replace the original file
cp tele_trace_patched.py tele_trace.py

# 2. (Optional) Set custom config via env vars
export TELETRACE_PORT=7777
export TELETRACE_RATE_MAX=10

# 3. Run
python tele_trace.py

# 4. Verify health
curl http://localhost:7777/api/health

# 5. Test a phone scan
curl -X POST http://localhost:7777/api/scan \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890"}'

# 6. Test a username scan
curl -X POST http://localhost:7777/api/scan \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser"}'

# 7. Test platform scan
curl -X POST http://localhost:7777/api/platform_scan \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser"}'

# 8. Test rate limiting (should get 429 after 5 rapid requests)
for i in $(seq 1 6); do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -X POST http://localhost:7777/api/scan \
    -H "Content-Type: application/json" \
    -d '{"username": "testuser"}'
done

# 9. Test input validation (should get 400)
curl -X POST http://localhost:7777/api/scan \
  -H "Content-Type: application/json" \
  -d '{"phone": "not-a-phone"}'

# 10. Test graceful shutdown
kill -SIGTERM $(pgrep -f tele_trace)

[anubhavanonymous]

Have you tested the changes !?

[xPloits3c]

Hi @anubhavanonymous, thanks for reviewing!
To be fully transparent: the patched code has not been tested against a live Telegram account, as noted in the IMPROVEMENTS.md under the Testing Disclaimer section.
What has been verified:
∙ ✅ Python syntax validation passes (no syntax errors)
∙ ✅ All 13 fixes compile and are structurally consistent with the original logic
∙ ✅ The return data format is identical to v2.0 — no breaking changes for the frontend
∙ ✅ GitHub’s symbol parser recognizes all functions and classes correctly
∙ ✅ No new dependencies added
What needs live testing before merge:
∙ ❗ Phone number scan (ImportContactsRequest → profile → photos → SangMata)
∙ ❗ Username scan (get_entity → profile → photos → SangMata)
∙ ❗ 2FA login flow
∙ ❗ Edge cases (no profile photo, video avatars, private accounts, bot accounts)
∙ ❗ Cross-platform scanner with SSL verification now enabled
The Telethon API calls remain the same (same functions, same parameters, same data structure), but the surrounding Python code has been significantly refactored — two duplicated functions merged into shared helpers, error handling rewritten, and logging added. This is why an end-to-end test with your API credentials is recommended before merging.
Happy to help fix anything that comes up during testing!