{"id":28149848,"url":"https://github.com/nvisosecurity/osquery-discord-notifier","last_synced_at":"2025-05-15T02:14:40.957Z","repository":{"id":271690762,"uuid":"913205271","full_name":"NVISOsecurity/osquery-discord-notifier","owner":"NVISOsecurity","description":"Monitor osquery logs and use an LLM to provide concise, user-friendly summaries of new events directly in Discord.","archived":false,"fork":false,"pushed_at":"2025-04-05T14:05:46.000Z","size":346,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T14:30:25.349Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVISOsecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-07T08:31:16.000Z","updated_at":"2025-04-05T14:05:49.000Z","dependencies_parsed_at":"2025-02-14T13:24:49.716Z","dependency_job_id":"05472ab6-d314-4a7f-bab2-59c7f5a9ef9a","html_url":"https://github.com/NVISOsecurity/osquery-discord-notifier","commit_stats":null,"previous_names":["nvisosecurity/osquery-discord-notifier"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVISOsecurity%2Fosquery-discord-notifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVISOsecurity%2Fosquery-discord-notifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVISOsecurity%2Fosquery-discord-notifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVISOsecurity%2Fosquery-discord-notifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVISOsecurity","download_url":"https://codeload.github.com/NVISOsecurity/osquery-discord-notifier/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254259420,"owners_count":22040822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-15T02:14:40.626Z","updated_at":"2025-05-15T02:14:40.951Z","avatar_url":"https://github.com/NVISOsecurity.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# osquery-discord-notifier\nMonitor osquery logs and use an LLM to provide concise, user-friendly summaries of new events through Private Messages in Discord.\n\n## Introduction \nosquery-discord-notifier is a python tool designed to help you monitor \u0026 notify on new osquery logs in a way that is both lightweight and powerful. By leveraging a language model, it generates concise and user-friendly summaries of new events, which are then sent directly to your Discord channel. \n\nThis allows for quick and easy monitoring of your system's security and performance without the need to manually sift through extensive logs, or to install a complete SOAR stack (Elasticsearch, Splunk, ...) to monitor a low volume of important events.\n\nThe tool continuously monitors the osquery ``osqueryd.results.log`` file, detects newly added events, and processes them through an LLM (if configured \u0026 available - a fallback is available) before notifying you through a Private Message in Discord.\n\nThis tool is by no means a replacement for a professional, scalable security monitoring service. It was developed out of the need to monitor a small set of important events in a lightweight manner within a home lab setup, and to monitor a very small number of servers for important (security) events.\n\n## Download \u0026 Install\n\n1. Download \u0026 install osquery (https://osquery.io/).\n\n2. In osquery, configure all queries you want to monitor \u0026 be notified about. Make sure your queries are scheduled to run at an interval like in the examples above, so they show up in the monitored log file. More information: https://osquery.readthedocs.io/en/stable/deployment/configuration/.\n\n3. Create and configure a new Discord bot. More information: https://discordpy.readthedocs.io/en/stable/discord.html.\n\n4. Make a copy of ``.env.TEMPLATE`` and call it ``.env``, and complete all the variables in the file. The Discord variables are required, the LLM ones are optional.\n\n5. Create a new virtual environment for python \u0026 install all dependencies\n\n```\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n6. Start the bot\n```\n.venv/bin/python osquery_discord_notifier.py\n```\n\n7. If everything was configured correctly, you should now receive a test message on Discord. This confirms everything was configured successfully!\n\n![Example Image 3](docs/example_now_running.png)\n\n8. (Optional) ``osquery_discord_notifier.py`` does not install a service. A simple way of making sure that it's continuously running (even if it would be killed for some reason) and to survive a reboot, is to add it to the cron jobs and use ``run-one`` to guarantee exactly 1 instance is running:\n\n```\n* * * * * run-one /repos/osquery-discord-notifier/.venv/bin/python /repos/osquery-discord-notifier/osquery_discord_notifier.py \u003e /var/log/osquery_discord_notifier.log\n```\n\n## Bot commands\n\n### !stats\nYou can perform a \"liveness\" check on the bot simply by sending it the message ``!stats``, which will respond with the server uptime:\n\n![Example Image 3](docs/example_server_uptime.png)\n\n### !events\n\nSend message ``!events`` to get an overview of the 5 latest events in the monitored osquery log file (or a truncated version in case the message exceeds the Discord limit of 2000 characters).\n\n## Example alerts\n\nA few examples of notifications useful while monitoring a home lab environment:\n\n### Malware download detected\n\n![Malware Download example](docs/example_mimikatz_detected.png)\n\nBased on this osquery.conf configuration:\n```\n\"schedule\": {\n    \"defender_alerts\": {\n      \"query\": \"SELECT * FROM windows_eventlog WHERE channel = 'Microsoft-Windows-Windows Defender/Operational' AND eventid IN (1116, 1117, 1121, 1123, 1124);\",\n      \"interval\": 5,\n      \"description\": \"Checks for Windows Defender alerts\"\n    }\n}\n```\n\n### New startup item detected\n\n![Startup item added exaloke](docs/example_docker_startup.png)\n\nBased on this osquery.conf configuration:\n```\n\"schedule\": {\n    \"startup_items\": {\n      \"query\": \"SELECT * from startup_items;\",\n      \"interval\": 5,\n      \"description\": \"Checks for startup items\"\n    }\n}\n```\n\n### New RDP Login session\n\n![RDP Session example](docs/example_new_rdp_session.png)\n\nBased on this osquery.conf configuration:\n\n```\n\"schedule\": {\n    \"rdp_sessions\": {\n        \"query\": \"SELECT * FROM logged_in_users WHERE type = 'rdp';\",\n        \"interval\": 60,\n        \"description\": \"Checks for active RDP sessions\"\n    }\n}\n```\n\n## Feature Wishlist\n\nA few things we might implement in future versions of the tool\n\n- Let the user interact with the bot by asking it follow-up questions, which are then processed by the configured Language Model (``When did you see a similar event in the past?``, ``What does S-1-5-21-500 mean?``, ``Is this event something I should worry about?``, ...).\n- More commands beyond ``!stats`` (although we don't want to turn this into a potential C\u0026C: commands should always be \"read only\" and not cause side-effects on the server).\n- A better event loop.\n\n## Acknowledgements\n\nThanks to the [osquery](https://github.com/osquery/osquery) team for building great software making this project possible.\n\n## Contributing\n\nWe would love to hear from you on a Pull Request or Issue in this repository.   \nAlternatively, you can reach out to our team at research@nviso.eu.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvisosecurity%2Fosquery-discord-notifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvisosecurity%2Fosquery-discord-notifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvisosecurity%2Fosquery-discord-notifier/lists"}