github_monitor is an OSINT tool written in Python which allows for real-time monitoring of Github users activities including profile and repositories changes.
- Real-time tracking of Github users activities including profile and repos changes:
- new events like new pushes, PRs, issues, forks, releases etc.
- added/removed public repositories
- added/removed starred repositories
- added/removed followings and followers
- changed user name, email, location, company, bio, blog URL
- detection of account changes
- repositories changes like new stargazers, forks, changed description etc.
- Email notifications for different events (new events, changed followings, followers, repos, user name, email, location, company, bio, blog URL, errors)
- Saving all user activities with timestamps to the CSV file
- Clickable Github URLs printed in the console & included in email notifications (repos, PRs, commits, issues, releases etc.)
- Possibility to control the running copy of the script via signals
Release notes can be found here
I'm not a dev, project done as a hobby. Code is ugly and as-is, but it works (at least for me) ;-)
The script requires Python 3.x.
It uses PyGithub library, also requires requests, python-dateutil, tzlocal and pytz.
It has been tested successfully on:
- macOS (Ventura & Sonoma)
- Linux (Raspberry Pi Bullseye & Bookworm based on Debian, Ubuntu 24)
- Windows (10 & 11)
It should work on other versions of macOS, Linux, Unix and Windows as well.
Install the required Python packages:
python3 -m pip install requests python-dateutil pytz tzlocal PyGithub
Or from requirements.txt:
pip3 install -r requirements.txt
Copy the github_monitor.py file to the desired location.
You might want to add executable rights if on Linux/Unix/macOS:
chmod a+x github_monitor.py
Edit the github_monitor.py file and change any desired configuration variables in the marked CONFIGURATION SECTION (all parameters have detailed description in the comments).
In order to get your Github personal access token (classic), go to your Github app settings https://github.com/settings/apps, then click 'Personal access tokens' -> 'Tokens (classic)' -> 'Generate new token (classic)'.
Copy the value of the token to GITHUB_TOKEN variable (or use -t parameter).
You can limit the type of events that will be monitored and reported by the tool. You can do it by changing the EVENTS_TO_MONITOR variable.
By default all events are monitored, but if you want to limit it, then remove the 'ALL' keyword and leave the events you are interested in, for example:
EVENTS_TO_MONITOR=['PushEvent','PullRequestEvent', 'IssuesEvent', 'ForkEvent', 'ReleaseEvent']
The tool will try to automatically detect your local time zone so it can convert Github API timestamps to your time.
In case you want to specify your timezone manually then change LOCAL_TIMEZONE variable from 'Auto' to specific location, e.g.
LOCAL_TIMEZONE='Europe/Warsaw'
In such case it is not needed to install tzlocal pip module.
If you want to use email notifications functionality you need to change the SMTP settings (host, port, user, password, sender, recipient). If you leave the default settings then no notifications will be sent.
All other variables can be left at their defaults, but feel free to experiment with it.
To get the list of all supported parameters:
./github_monitor.py -h
or
python3 ./github_monitor.py -h
To monitor specific user activity, just type Github username as parameter (misiektoja in the example below):
./github_monitor.py misiektoja
If you have not changed GITHUB_TOKEN variable in the github_monitor.py file, you can use -t parameter:
./github_monitor.py misiektoja -t "your_github_classic_personal_access_token"
If you also want to monitor user's public repositories changes like new stargazers, forks, changed description etc., then use -j parameter:
./github_monitor.py misiektoja -j
The tool will run infinitely and monitor the user until the script is interrupted (Ctrl+C) or killed the other way.
You can monitor multiple Github users by spawning multiple copies of the script.
It is suggested to use sth like tmux or screen to have the script running after you log out from the server (unless you are running it on your desktop).
The tool automatically saves its output to github_monitor_{username}.log file (can be changed in the settings via GITHUB_LOGFILE variable or disabled completely with -d parameter).
There is also other mode of the tool which displays different requested information (-r, -g, -f and -l parameters).
If you want to display list of public repositories for the user, then use -r parameter:
./github_monitor.py -r misiektoja
If you want to display list of repositories starred by the user, then use -g parameter:
./github_monitor.py -g misiektoja
If you want to display list of followers and followings for the user, then use -f parameter:
./github_monitor.py -f misiektoja
If you want to get the list of recent events for the user then use -l parameter. You can also add -n parameter to define how many events should be displayed, by default it shows 5 last events:
./github_monitor.py -l misiektoja -n 10
You can use those functionalities in listing mode regardless if the monitoring is used or not (it does not interfere).
If you want to get email notifications for all user profile and repos changes use -p parameter:
./github_monitor.py misiektoja -p
If you want to get email notifications for all new events (like new pushes, PRs, issues, forks, releases etc.) use -s parameter:
./github_monitor.py misiektoja -s
You can combine those parameters together if needed.
Make sure you defined your SMTP settings earlier (see SMTP settings).
Example email:
If you want to save all Github user's events, profile and repo changes in the CSV file, use -b parameter with the name of the file (it will be automatically created if it does not exist):
./github_monitor.py misiektoja -b github_misiektoja.csv
If you want to change the check interval to 15 mins (900 seconds) use -c parameter:
./github_monitor.py misiektoja -c 900
It is generally not recommended to use values lower than 5 minutes as new events are very often delayed by 5 mins by Github API.
The tool has several signal handlers implemented which allow to change behavior of the tool without a need to restart it with new parameters.
List of supported signals:
Signal | Description |
---|---|
USR1 | Toggle email notifications for user's profile changes (-p) |
USR2 | Toggle email notifications for new events (-s) |
TRAP | Increase the user check interval (by 1 min) |
ABRT | Decrease the user check interval (by 1 min) |
So if you want to change functionality of the running tool, just send the proper signal to the desired copy of the script.
I personally use pkill tool, so for example to toggle new events email notifications for tool instance monitoring the misiektoja user:
pkill -f -USR2 "python3 ./github_monitor.py misiektoja"
As Windows supports limited number of signals, this functionality is available only on Linux/Unix/macOS.
Check other supported parameters using -h.
You can combine all the parameters mentioned earlier in monitoring mode (listing mode only supports -r, -g, -f, -l, -n).
If you use GRC and want to have the tool's log output properly colored you can use the configuration file available here
Change your grc configuration (typically .grc/grc.conf) and add this part:
# monitoring log file
.*_monitor_.*\.log
conf.monitor_logs
Now copy the conf.monitor_logs to your .grc directory and github_monitor log files should be nicely colored when using grc tool.
This project is licensed under the GPLv3 - see the LICENSE file for details