Metadata-Version: 2.1
Name: thns
Version: 0.0.2
Summary: Get Telegram notifications when requests are being made to your web server
Home-page: https://gitlab.com/0bs1d1an/thns
Author: Guido Kroon (@0bs1d1an)
Author-email: gkroon@maelstrom.ninja
License: UNKNOWN
Project-URL: Bug Reports, https://gitlab.com/0bs1d1an/thns/issues
Project-URL: Source, https://gitlab.com/0bs1d1an/thns/
Description: [![pipeline status](https://gitlab.com/0bs1d1an/thns/badges/master/pipeline.svg)](https://gitlab.com/0bs1d1an/thns/commits/master)
        
        # Telegram HTTP notification script
        
        This script will notify you of any or selected HTTP requests made to your server, using the Telegram API.
        
        ## Rationale
        
        During a phishing assignment I was tasked with writing a script similar to this one, to keep track of people that clicked on our link, downloaded our malicious payload, and submitted a form with their personal details.
        I decided to make it more general-purpose and further maintain it here. :-)
        
        ## How to set it up
        
        TL;DR - basically 4 steps:
        
        1. Create your own Telegram bot
        1. Create a new (private) channel and add your bot to that channel
        1. Either hardcode your bot key, chat ID, and web server log file in this script, or use the script arguments.
        1. Consider running the script in a `screen` session to run it in the background so that you can leave your shell.
        
        Detailed explanation: 
        
        First, you will need to create your own [Telegram bot](https://core.telegram.org/bots), which is basically just an API key without any logic (unless you really want to create a [full fledged bot](https://python-telegram-bot.org/)).
        Once you've created your bot using the [@BotFather](https://telegram.me/BotFather) it will also tell your the bot key (API key).
        You can either hardcode the bot key in this script, or provide it as an argument (-k) when running this script.
        
        Second, create a Telegram (private) channel and write down the chat ID.
        If you have trouble finding the chat ID, you can use [@username_to_id_bot](https://telegram.me/username_to_id_bot) and paste the invite link in there.
        It will tell you the channel's chat ID, which you can also hardcode into the script if you want, or provide it as an argument (-c) when running this script.
        Don't forget to also explicitely add the bot to the channel.
        
        Third, either hardcode the web server's access.log file location as well, or provide it as an argument (-l) when running this script.
        
        Finally, run the script. Consider running the script in a `screen` session to run it in the background so that you can leave your shell (e.g. `screen -S thns bash thns.sh -m -s`).
        You can safely detach from the screen session by pressing CTRL+A+D.
        Now you can safely logout and the script will remain in the background.
        To attach again, login to your server again and run `screen -r thns`.
        
        ## Usage
        
        ```
        usage: thns [-h] [-c TELEGRAM_CHAT_ID] [-g] [-i IGNORE [IGNORE ...]]
                    [-k TELEGRAM_BOT_KEY] [-l LOG_FILE] [-m]
                    [-r MATCH_REQUESTS [MATCH_REQUESTS ...]] [-s] [-u]
        
        Get Telegram notifications when requests are being made your web server
        
        optional arguments:
          -h, --help            show this help message and exit
          -c TELEGRAM_CHAT_ID, --chat-id TELEGRAM_CHAT_ID
                                Specify the Telegram chat ID to post to.
          -g, --geo             Include geographical information.
          -i IGNORE [IGNORE ...], --ignore-ips IGNORE [IGNORE ...]
                                Ignore (multiple) IP addresses (e.g. 127.0.0.1 ::1).
          -k TELEGRAM_BOT_KEY, --bot-key TELEGRAM_BOT_KEY
                                Specify the Telegram bot key.
          -l LOG_FILE, --log-file LOG_FILE
                                Specify the (Nginx) log file.
          -m, --map             Post a map pointer.
          -r MATCH_REQUESTS [MATCH_REQUESTS ...], --match-requests MATCH_REQUESTS [MATCH_REQUESTS ...]
                                Match (multiple) specific HTTP requests (e.g. /
                                /robots.txt).
          -s, --silent          Send Telegram messages silently.
          -u, --user-agent      Include the user agent string.
        ```
        
        ## Example
        
        Consider using `screen` to run it in the background. For example:
        
        ```
        $ screen -S -d -m python3 -m thns -m -s -l /var/log/nginx/access.log -c "-1234567890123" -k "123456789:1234567890abcdefghijklmnopqrstuvwxyz" -i 127.0.0.1 ::1
        ```
        
        Then watch your Telegram channel fill:
        
        ![Example](example.jpg)
        
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.6
Description-Content-Type: text/markdown
