tgsherlock 1.0.0__tar.gz

tgsherlock-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Iván Castañeda (original OSINTelegram)
+Copyright (c) 2026 TGSherlock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

tgsherlock-1.0.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: tgsherlock
+Version: 1.0.0
+Summary: Local web panel for Telegram OSINT: live monitoring, alerts, user tracking and keyword sweeps.
+License: MIT
+Keywords: telegram,osint,monitoring,threat-intelligence,telethon
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Web Environment
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon<2,>=1.34
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: qrcode>=7.4
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/emrekybs/tgsherlock/main/src/tgsherlock/static/logo-sm.png" width="120" alt="TGSherlock logo">
+</p>
+<h1 align="center">TGSherlock</h1>
+<p align="center">Telegram OSINT in a local web panel: live monitoring, alerts, user tracking and keyword sweeps.</p>
+
+![Dashboard](https://raw.githubusercontent.com/emrekybs/tgsherlock/main/docs/screenshots/dashboard.png)
+![User profile](https://raw.githubusercontent.com/emrekybs/tgsherlock/main/docs/screenshots/profile.png)
+
+## Install
+
+```bash
+pipx install tgsherlock
+```
+
+From a local clone: `pipx install .` (if `tgsherlock` is not found afterwards, run `pipx ensurepath` and open a new terminal).
+
+## Run
+
+```bash
+tgsherlock
+```
+
+The panel opens in your browser at `http://127.0.0.1:8765`. On Linux, the first run also adds **TGSherlock** to your application menu, so you can start it with a click.
+
+**First run:** create an app at [my.telegram.org](https://my.telegram.org/apps) → *API development tools*, enter your **API ID** and **API Hash**, then scan the QR code with Telegram (*Settings → Devices → Link Desktop Device*). Phone-number login is available too.
+
+## Features
+
+- **Live Monitor**: real-time messages from chosen users, groups and channels, with optional media download.
+- **Alerts**: watch a user, a group or every chat for any message, keywords, regex, media or indicators. Get notified in-app, on the desktop, by email (SMTP) or by webhook, with digest throttling.
+- **User Profile**: bio, usernames, flags, shared groups, first and last seen per group, hourly activity and a dated message timeline.
+- **Search**: users, groups and channels, shown with their profile photos.
+- **Group History · Keyword Sweep · User Tracker**: background jobs with progress and automatic FloodWait handling.
+- **Entities**: emails, phones, URLs, IPs, crypto wallets, invite links and hashtags, extracted automatically.
+- **Archive & export**: filter everything you collected and export it as CSV, JSON or an HTML report.
+- **Multiple accounts**: add, switch and sign out from the sidebar.
+
+Options: `--port 8790`, `--no-browser`, `--install-desktop`, `--uninstall-desktop`.
+Data stays local: `~/.config/tgsherlock` (settings, sessions) and `~/.local/share/tgsherlock` (databases, media).
+
+## Responsible use
+
+Built for defensive OSINT and threat intelligence. TGSherlock only sees what your own Telegram account can see. Follow local law and Telegram's Terms of Service.
+
+## License
+
+MIT. Based on [OSINTelegram](https://github.com/Ivancastl/OSINTelegram) by Iván Castañeda.

tgsherlock-1.0.0/README.md

@@ -0,0 +1,48 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/emrekybs/tgsherlock/main/src/tgsherlock/static/logo-sm.png" width="120" alt="TGSherlock logo">
+</p>
+<h1 align="center">TGSherlock</h1>
+<p align="center">Telegram OSINT in a local web panel: live monitoring, alerts, user tracking and keyword sweeps.</p>
+
+![Dashboard](https://raw.githubusercontent.com/emrekybs/tgsherlock/main/docs/screenshots/dashboard.png)
+![User profile](https://raw.githubusercontent.com/emrekybs/tgsherlock/main/docs/screenshots/profile.png)
+
+## Install
+
+```bash
+pipx install tgsherlock
+```
+
+From a local clone: `pipx install .` (if `tgsherlock` is not found afterwards, run `pipx ensurepath` and open a new terminal).
+
+## Run
+
+```bash
+tgsherlock
+```
+
+The panel opens in your browser at `http://127.0.0.1:8765`. On Linux, the first run also adds **TGSherlock** to your application menu, so you can start it with a click.
+
+**First run:** create an app at [my.telegram.org](https://my.telegram.org/apps) → *API development tools*, enter your **API ID** and **API Hash**, then scan the QR code with Telegram (*Settings → Devices → Link Desktop Device*). Phone-number login is available too.
+
+## Features
+
+- **Live Monitor**: real-time messages from chosen users, groups and channels, with optional media download.
+- **Alerts**: watch a user, a group or every chat for any message, keywords, regex, media or indicators. Get notified in-app, on the desktop, by email (SMTP) or by webhook, with digest throttling.
+- **User Profile**: bio, usernames, flags, shared groups, first and last seen per group, hourly activity and a dated message timeline.
+- **Search**: users, groups and channels, shown with their profile photos.
+- **Group History · Keyword Sweep · User Tracker**: background jobs with progress and automatic FloodWait handling.
+- **Entities**: emails, phones, URLs, IPs, crypto wallets, invite links and hashtags, extracted automatically.
+- **Archive & export**: filter everything you collected and export it as CSV, JSON or an HTML report.
+- **Multiple accounts**: add, switch and sign out from the sidebar.
+
+Options: `--port 8790`, `--no-browser`, `--install-desktop`, `--uninstall-desktop`.
+Data stays local: `~/.config/tgsherlock` (settings, sessions) and `~/.local/share/tgsherlock` (databases, media).
+
+## Responsible use
+
+Built for defensive OSINT and threat intelligence. TGSherlock only sees what your own Telegram account can see. Follow local law and Telegram's Terms of Service.
+
+## License
+
+MIT. Based on [OSINTelegram](https://github.com/Ivancastl/OSINTelegram) by Iván Castañeda.

tgsherlock-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tgsherlock"
+version = "1.0.0"
+description = "Local web panel for Telegram OSINT: live monitoring, alerts, user tracking and keyword sweeps."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["telegram", "osint", "monitoring", "threat-intelligence", "telethon"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Environment :: Web Environment",
+    "Topic :: Security",
+]
+dependencies = [
+    "telethon>=1.34,<2",
+    "aiohttp>=3.9",
+    "qrcode>=7.4",
+]
+
+[project.scripts]
+tgsherlock = "tgsherlock.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tgsherlock = ["static/*", "static/fonts/*", "assets/*"]

tgsherlock-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tgsherlock-1.0.0/src/tgsherlock/__init__.py

@@ -0,0 +1,2 @@
+"""TGSherlock — local web panel for Telegram OSINT."""
+__version__ = "1.0.0"

tgsherlock-1.0.0/src/tgsherlock/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tgsherlock-1.0.0/src/tgsherlock/alerts.py

@@ -0,0 +1,250 @@
+"""Alert rules: matching, e-mail (SMTP) and webhook delivery with throttling."""
+import asyncio
+import html
+import logging
+import re
+import smtplib
+import ssl
+import time
+from email.message import EmailMessage
+from email.utils import formatdate, make_msgid
+
+import aiohttp
+
+log = logging.getLogger("tgsherlock.alerts")
+
+TRIGGER_LABELS = {
+    "any": "Any message",
+    "keywords": "Keywords",
+    "regex": "Regex",
+    "media": "Has media",
+    "entity": "Entity found",
+}
+
+_rx_cache = {}
+
+
+def _regex(pattern):
+    if pattern not in _rx_cache:
+        try:
+            _rx_cache[pattern] = re.compile(pattern, re.I)
+        except re.error:
+            _rx_cache[pattern] = None
+    return _rx_cache[pattern]
+
+
+def validate_rule(r: dict):
+    if r.get("watch") not in ("user", "chat", "anywhere"):
+        return "Choose what to watch."
+    if r.get("watch") != "anywhere" and not r.get("target_id"):
+        return "Pick a user or group to watch."
+    if r.get("trigger") not in TRIGGER_LABELS:
+        return "Choose a trigger."
+    if r.get("trigger") in ("keywords", "regex") and not (r.get("pattern") or "").strip():
+        return "Enter keywords or a pattern."
+    if r.get("trigger") == "regex" and _regex(r["pattern"]) is None:
+        return "The regular expression is not valid."
+    return None
+
+
+def rule_watches(rule, sender_id, chat_id) -> bool:
+    if not rule["enabled"]:
+        return False
+    if rule["watch"] == "anywhere":
+        return True
+    if rule["watch"] == "user":
+        return sender_id is not None and int(rule["target_id"]) == int(sender_id)
+    return chat_id is not None and int(rule["target_id"]) == int(chat_id)
+
+
+def rule_matches(rule, rec, entities) -> bool:
+    text = rec.get("text") or ""
+    trig = rule["trigger"]
+    pattern = (rule.get("pattern") or "").strip()
+    if trig == "any":
+        return True
+    if trig == "keywords":
+        t = text.lower()
+        return any(k.strip().lower() in t for k in pattern.split(",") if k.strip())
+    if trig == "regex":
+        rx = _regex(pattern)
+        return bool(rx and rx.search(text))
+    if trig == "media":
+        return bool(rec.get("media"))
+    if trig == "entity":
+        wanted = {p.strip().lower() for p in pattern.split(",") if p.strip()}
+        types = {etype.lower() for _, etype in entities}
+        return bool(types & wanted) if wanted else bool(types)
+    return False
+
+
+def describe(rec, rule) -> str:
+    who = rec.get("sender_name") or (f"@{rec['sender_username']}" if rec.get("sender_username") else str(rec.get("sender_id")))
+    where = rec.get("chat_title") or "a private chat"
+    if rule["trigger"] == "keywords":
+        t = (rec.get("text") or "").lower()
+        hit = next((k.strip() for k in rule["pattern"].split(",") if k.strip() and k.strip().lower() in t), "")
+        return f"“{hit}” mentioned by {who} in {where}"
+    if rule["trigger"] == "entity":
+        return f"Indicator posted by {who} in {where}"
+    if rule["trigger"] == "media":
+        return f"{who} shared media in {where}"
+    return f"{who} posted in {where}"
+
+
+# ---------------------------------------------------------------------------
+# e-mail
+# ---------------------------------------------------------------------------
+
+def _send_mail_sync(smtp: dict, recipients, subject: str, text: str, html_body: str):
+    host, port = smtp.get("host"), int(smtp.get("port") or 0)
+    if not host or not port:
+        raise RuntimeError("SMTP host and port are not configured.")
+    if not recipients:
+        raise RuntimeError("No recipients configured.")
+    msg = EmailMessage()
+    msg["Subject"] = subject
+    msg["From"] = smtp.get("sender") or smtp.get("user") or "tgsherlock@localhost"
+    msg["To"] = ", ".join(recipients)
+    msg["Date"] = formatdate(localtime=True)
+    msg["Message-ID"] = make_msgid("tgsherlock")
+    msg.set_content(text)
+    msg.add_alternative(html_body, subtype="html")
+    ctx = ssl.create_default_context()
+    security = smtp.get("security", "starttls")
+    if security == "ssl":
+        server = smtplib.SMTP_SSL(host, port, timeout=20, context=ctx)
+    else:
+        server = smtplib.SMTP(host, port, timeout=20)
+    try:
+        server.ehlo()
+        if security == "starttls":
+            server.starttls(context=ctx)
+            server.ehlo()
+        if smtp.get("user"):
+            server.login(smtp["user"], smtp.get("password") or "")
+        server.send_message(msg)
+    finally:
+        try:
+            server.quit()
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def split_recipients(value: str):
+    return [r.strip() for r in re.split(r"[,;\s]+", value or "") if "@" in r]
+
+
+def _alert_html(alerts):
+    rows = []
+    colors = {"high": "#c0392b", "medium": "#b7791f", "low": "#2b6cb0"}
+    for a in alerts:
+        rows.append(
+            f"<tr><td style='padding:10px;border-bottom:1px solid #e5e7eb;vertical-align:top'>"
+            f"<span style='color:#fff;background:{colors.get(a['severity'], '#555')};border-radius:10px;"
+            f"padding:2px 8px;font-size:12px'>{html.escape(a['severity'].title())}</span></td>"
+            f"<td style='padding:10px;border-bottom:1px solid #e5e7eb'><b>{html.escape(a['title'])}</b><br>"
+            f"<span style='color:#374151'>{html.escape(a['text'] or '')}</span><br>"
+            f"<span style='color:#6b7280;font-size:12px'>{html.escape(a['date'])} · rule: "
+            f"{html.escape(a['rule_name'])}</span></td></tr>")
+    return ("<div style='font-family:Arial,sans-serif'><h2 style='margin:0 0 12px'>TGSherlock alert</h2>"
+            "<table style='border-collapse:collapse;width:100%'>" + "".join(rows) + "</table></div>")
+
+
+def _alert_text(alerts):
+    parts = []
+    for a in alerts:
+        parts.append(f"[{a['severity'].upper()}] {a['title']}\n{a['text']}\n{a['date']} · rule: {a['rule_name']}\n")
+    return "\n".join(parts)
+
+
+class Notifier:
+    """Delivers alerts by e-mail / webhook. E-mails are throttled per rule into digests."""
+
+    def __init__(self, settings):
+        self.settings = settings
+        self.last_mail = {}   # rule_id -> monotonic timestamp
+        self.pending = {}     # rule_id -> (rule, [alerts])
+        self._task = None
+        self._session = None
+
+    def start(self):
+        if self._task is None:
+            self._task = asyncio.ensure_future(self._flusher())
+
+    async def close(self):
+        if self._task:
+            self._task.cancel()
+            self._task = None
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def _http(self):
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=15))
+        return self._session
+
+    async def deliver(self, rule, alert, on_status):
+        """on_status(label) is called with the delivery result for each channel."""
+        notify = rule.get("notify") or {}
+        if notify.get("webhook") and rule.get("webhook"):
+            asyncio.ensure_future(self._webhook(rule["webhook"], alert, on_status))
+        if notify.get("email"):
+            throttle = max(0, int(rule.get("throttle_min") or 0)) * 60
+            last = self.last_mail.get(rule["id"], 0)
+            if throttle and time.monotonic() - last < throttle:
+                self.pending.setdefault(rule["id"], (rule, []))[1].append(alert)
+                on_status("Email queued (digest)")
+            else:
+                self.last_mail[rule["id"]] = time.monotonic()
+                await self._email(rule, [alert], on_status)
+
+    async def _email(self, rule, alerts, on_status=None):
+        smtp = self.settings["smtp"]
+        recipients = split_recipients(rule.get("recipients") or smtp.get("to"))
+        sev = alerts[0]["severity"].upper()
+        subject = (f"[TGSherlock][{sev}] {alerts[0]['title']}" if len(alerts) == 1
+                   else f"[TGSherlock] {len(alerts)} alerts · {rule['name']}")
+        loop = asyncio.get_running_loop()
+        try:
+            await loop.run_in_executor(None, _send_mail_sync, smtp, recipients, subject,
+                                       _alert_text(alerts), _alert_html(alerts))
+            if on_status:
+                on_status("Email sent")
+        except Exception as exc:  # noqa: BLE001
+            log.warning("E-mail delivery failed: %s", exc)
+            if on_status:
+                on_status("Email failed")
+
+    async def _webhook(self, url, alert, on_status):
+        text = f"[{alert['severity'].upper()}] {alert['title']}\n{alert['text']}"
+        payload = {"text": text, "content": text[:1900], "alert": alert}
+        try:
+            session = await self._http()
+            async with session.post(url, json=payload) as resp:
+                on_status("Webhook sent" if resp.status < 400 else f"Webhook failed ({resp.status})")
+        except Exception as exc:  # noqa: BLE001
+            log.warning("Webhook delivery failed: %s", exc)
+            on_status("Webhook failed")
+
+    async def _flusher(self):
+        while True:
+            await asyncio.sleep(30)
+            for rule_id in list(self.pending):
+                rule, alerts = self.pending[rule_id]
+                throttle = max(1, int(rule.get("throttle_min") or 0)) * 60
+                if time.monotonic() - self.last_mail.get(rule_id, 0) >= throttle and alerts:
+                    del self.pending[rule_id]
+                    self.last_mail[rule_id] = time.monotonic()
+                    await self._email(rule, alerts)
+
+    async def send_test(self, to=None):
+        smtp = self.settings["smtp"]
+        recipients = split_recipients(to or smtp.get("to"))
+        loop = asyncio.get_running_loop()
+        sample = [{"severity": "low", "title": "Test alert", "text": "Your SMTP settings work.",
+                   "date": time.strftime("%Y-%m-%d %H:%M:%S"), "rule_name": "Test"}]
+        await loop.run_in_executor(None, _send_mail_sync, smtp, recipients, "[TGSherlock] Test email",
+                                   _alert_text(sample), _alert_html(sample))
+        return recipients

tgsherlock-1.0.0/src/tgsherlock/analysis.py

@@ -0,0 +1,57 @@
+"""Risk classification and indicator (entity) extraction."""
+import re
+
+ENTITY_PATTERNS = [
+    ("Invite link", re.compile(r"(?:https?://)?(?:t\.me|telegram\.me)/(?:\+|joinchat/)[A-Za-z0-9_-]{8,}")),
+    ("URL", re.compile(r"https?://[^\s<>\"'()\[\]]+")),
+    ("Email", re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")),
+    ("IP", re.compile(r"\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b")),
+    ("Crypto wallet", re.compile(r"\b(?:bc1[ac-hj-np-z02-9]{25,71}|[13][a-km-zA-HJ-NP-Z1-9]{25,34}"
+                                  r"|0x[a-fA-F0-9]{40}|T[1-9A-HJ-NP-Za-km-z]{33})\b")),
+    ("Phone", re.compile(r"(?<![\w+])\+\d[\d \-().]{7,16}\d")),
+    ("Username", re.compile(r"(?<![\w@./])@[A-Za-z][A-Za-z0-9_]{4,31}\b")),
+    ("Hashtag", re.compile(r"(?<![\w&/#])#[^\s#.,!?;:()\[\]{}\"']{2,40}")),
+]
+
+ENTITY_TYPES = [name for name, _ in ENTITY_PATTERNS]
+
+
+def extract_entities(text: str):
+    """Return a list of (value, type) pairs found in text, de-duplicated."""
+    if not text:
+        return []
+    found, seen = [], set()
+    taken = []  # spans already claimed by a more specific type
+    for etype, rx in ENTITY_PATTERNS:
+        for m in rx.finditer(text):
+            if any(s <= m.start() < e for s, e in taken):
+                continue
+            value = m.group(0).rstrip(".,;:")
+            if etype == "Phone" and len(re.sub(r"\D", "", value)) < 9:
+                continue
+            key = (value.lower(), etype)
+            if key in seen:
+                continue
+            seen.add(key)
+            taken.append((m.start(), m.end()))
+            found.append((value, etype))
+    return found
+
+
+def _contains(text_l: str, word: str) -> bool:
+    word = word.strip().lower()
+    return bool(word) and word in text_l
+
+
+def classify(text: str, risk_cfg: dict):
+    """Return (level, matched_keyword). level: high | watch | clean."""
+    if not text:
+        return "clean", None
+    t = text.lower()
+    for w in risk_cfg.get("high", []):
+        if _contains(t, w):
+            return "high", w
+    for w in risk_cfg.get("watch", []):
+        if _contains(t, w):
+            return "watch", w
+    return "clean", None

tgsherlock-1.0.0/src/tgsherlock/bus.py

@@ -0,0 +1,24 @@
+"""In-process event bus feeding Server-Sent Events to the browser."""
+import asyncio
+import json
+
+
+class Bus:
+    def __init__(self):
+        self.queues = set()
+
+    def subscribe(self):
+        q = asyncio.Queue(maxsize=500)
+        self.queues.add(q)
+        return q
+
+    def unsubscribe(self, q):
+        self.queues.discard(q)
+
+    def emit(self, kind, data=None):
+        payload = json.dumps({"type": kind, "data": data}, ensure_ascii=False, default=str)
+        for q in list(self.queues):
+            try:
+                q.put_nowait(payload)
+            except asyncio.QueueFull:
+                pass

tgsherlock-1.0.0/src/tgsherlock/cli.py

@@ -0,0 +1,117 @@
+"""Command line entry point: `tgsherlock`."""
+import argparse
+import asyncio
+import json
+import logging
+import signal
+import sys
+import threading
+import urllib.request
+import webbrowser
+
+from aiohttp import web
+
+from . import __version__, desktop
+from .bus import Bus
+from .config import Settings
+from .server import create_app
+from .tg import TG
+
+
+def _running_instance(port) -> bool:
+    try:
+        with urllib.request.urlopen(f"http://127.0.0.1:{port}/api/ping", timeout=1.5) as resp:
+            return json.loads(resp.read().decode()).get("app") == "tgsherlock"
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _open_browser(url):
+    threading.Thread(target=webbrowser.open, args=(url,), daemon=True).start()
+
+
+async def _serve(settings, host, port, open_browser):
+    bus = Bus()
+    tgm = TG(settings, bus)
+    stop = asyncio.Event()
+    app = create_app(settings, tgm, bus, stop, desktop.status, local_only=host in ("127.0.0.1", "localhost"))
+    runner = web.AppRunner(app, access_log=None, shutdown_timeout=2)
+    await runner.setup()
+    site = web.TCPSite(runner, host, port)
+    try:
+        await site.start()
+    except OSError as exc:
+        print(f"Cannot listen on {host}:{port} ({exc.strerror}). Try: tgsherlock --port 8790", file=sys.stderr)
+        await runner.cleanup()
+        return 1
+    url = f"http://{'127.0.0.1' if host in ('0.0.0.0', '::') else host}:{port}/"
+    print(f"TGSherlock {__version__} running at {url}  (Ctrl+C to stop)")
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, stop.set)
+        except (NotImplementedError, RuntimeError):
+            pass
+    asyncio.ensure_future(tgm.start())
+    if open_browser:
+        _open_browser(url)
+    await stop.wait()
+    print("Stopping…")
+    await tgm.close()
+    await runner.cleanup()
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="tgsherlock", description="Telegram OSINT web panel (runs locally).")
+    parser.add_argument("--host", default="127.0.0.1", help="interface to bind (default 127.0.0.1)")
+    parser.add_argument("--port", type=int, help="port (default 8765 or the one saved in Settings)")
+    parser.add_argument("--no-browser", action="store_true", help="do not open the browser")
+    parser.add_argument("--install-desktop", action="store_true", help="add TGSherlock to the application menu")
+    parser.add_argument("--uninstall-desktop", action="store_true", help="remove the application-menu entry")
+    parser.add_argument("--debug", action="store_true", help="verbose logging")
+    parser.add_argument("--version", action="version", version=f"tgsherlock {__version__}")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.DEBUG if args.debug else logging.WARNING,
+                        format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+    if args.uninstall_desktop:
+        desktop.uninstall()
+        print("Removed the application-menu entry.")
+        return
+    if args.install_desktop:
+        path = desktop.install()
+        print(f"Installed menu entry: {path}")
+        return
+
+    settings = Settings()
+    port = args.port or int(settings["port"])
+    open_browser = not args.no_browser and settings["prefs"].get("browser", True)
+
+    if _running_instance(port):
+        url = f"http://127.0.0.1:{port}/"
+        print(f"TGSherlock is already running at {url}")
+        if not args.no_browser:
+            webbrowser.open(url)
+        return
+
+    if desktop.supported() and not settings["desktop_installed"]:
+        try:
+            desktop.install()
+            settings.set("desktop_installed", True)
+        except OSError:
+            pass
+
+    if args.host not in ("127.0.0.1", "localhost"):
+        print("Warning: the panel has no password. Only bind to other interfaces on trusted networks.",
+              file=sys.stderr)
+    try:
+        code = asyncio.run(_serve(settings, args.host, port, open_browser))
+    except KeyboardInterrupt:
+        code = 0
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()