{"id":13820895,"url":"https://github.com/hilt86/NAGBOT","last_synced_at":"2025-05-16T10:33:28.789Z","repository":{"id":133880655,"uuid":"124297590","full_name":"hilt86/NAGBOT","owner":"hilt86","description":"Slack bot that helps you deal with suspicious SSHD logins","archived":false,"fork":false,"pushed_at":"2018-06-01T07:10:53.000Z","size":135,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-14T07:07:11.852Z","etag":null,"topics":["elastalert","elasticsearch","security","sshd"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hilt86.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-03-07T21:37:41.000Z","updated_at":"2022-04-18T15:41:16.000Z","dependencies_parsed_at":"2023-03-13T11:07:44.581Z","dependency_job_id":null,"html_url":"https://github.com/hilt86/NAGBOT","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hilt86%2FNAGBOT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hilt86%2FNAGBOT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hilt86%2FNAGBOT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hilt86%2FNAGBOT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hilt86","download_url":"https://codeload.github.com/hilt86/NAGBOT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254512897,"owners_count":22083478,"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":["elastalert","elasticsearch","security","sshd"],"created_at":"2024-08-04T08:01:11.204Z","updated_at":"2025-05-16T10:33:28.474Z","avatar_url":"https://github.com/hilt86.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\n## In this guide:\n[**NAGBOT**](#nagbot)\n- [Pre-requisites](#pre-requisites)\n- [Installation](#installation)\n - [1. Deploy NagBot to a server or cloud service.](#1-deploy-nagbot-to-a-server-or-cloud-service)\n - [2. Setting up NagBot in Slack.](#2-setting-up-nagbot-in-slack)\n  - [2.1 Create a NagBot Slack app.](#21-create-a-nagbot-slack-app-on-apislackcom)\n  - [2.2 Tokens, Verification and Environmental variables.](#22-tokens-verification-and-environmental-variables)\n  - [2.3 Create a channel to receive escalation events.](#23-create-a-channel-to-receive-escalation-events)\n  - [2.4 Manual test](#24-manual-test)\n - [3. Integration test](#3-integration-test)\n - [4. Credits](#4-credits)\n\n\n### Is your security operations team faced with finding a needle within a haystack? \n\nIn dynamic, multi-cloud deployments developers and security operations are faced with millions of security events every day. It is not uncommon for a log aggregation or SIEM system to have billions or even trillions of events which very quickly becomes unmanageable, for example :\n\n```\nMay 28 11:18:19 elastic01 sshd[27085]: Failed password for jamesm from 74.45.57.208 port 61506 ssh2\nMay 28 23:37:23 elastic01 sshd[28450]: Accepted publickey for kevinm from 45.83.25.161 port 36578 ssh2: RSA SHA256:38jf892f9h2398fp982hf398h23f9\nMay 28 23:37:25 elastic01 sshd[28568]: Accepted publickey for kevinm from 50.18.27.141 port 27347 ssh2: RSA SHA256:38jf892f9h2398fp982hf398h23f9\nMay 28 23:37:34 elastic01 sshd[28634]: Accepted publickey for kevinm from 41.77.79.74 port 36000 ssh2: RSA SHA256:38jf892f9h2398fp982hf398h23f9\nMay 28 23:37:43 elastic01 sshd[28699]: Accepted publickey for kevinm from 104.163.162.211 port 39204 ssh2: RSA SHA256:38jf892f9h2398fp982hf398h23f9\nMay 28 23:37:52 elastic01 sshd[28764]: Accepted publickey for kevinm from 45.32.7.130 port 31533 ssh2: RSA SHA256:38jf892f9h2398fp982hf398h23f9\nMay 28 23:40:23 elastic01 sshd[28831]: Failed publickey for kevinm from 140.18.227.141 port 59899 ssh2: RSA SHA256:89asdlajksdas71ufhiol3fhsidfh\nMay 29 01:39:28 elastic01 sshd[26894]: Accepted password for jamesm from 8.45.7.8 port 49902 ssh2\n```\n\n\nOften the first thing security teams do is install a centralized logging system - which is a good step - but it quickly leads to log fatigue, where security analysts are overwhelmed by the amount of information they need to analyze. \n\nAs the security program for an organization grows teams eventually put in place measures to reduce or filter failed logins using a VPN which means that there are less failed authorization attempts to sort through, but is this the best we can do?\n\n\n# Introducing Nagbot\n\nOur project, dubbed Nagbot takes this a step further and extends what is quickly becoming the industry standard logging and alerting (Elasticsearch + Elastalert) to further scrutinize successful logins. \n\nOn successful SSHD login NagBot will send messages directly to the authenticated user using Slack :\n\n![10_nagbotmessage](https://user-images.githubusercontent.com/37161577/40458814-53a3ef7a-5f41-11e8-90a4-5f97ae3386bd.png)\n\n\nThe user then selects a response from the dropdown \"That was me\" or \"Wasn't me!\" and Nagbot takes appropriate action. If the user responds \"Wasn't me\" Nagbot escalates the event to a separate Slack channel dedicated to security incidents:\n\n\n![11_securityalert](https://user-images.githubusercontent.com/37161577/40458815-5628e9f8-5f41-11e8-82b2-eae5cfbb9697.png)\n\nThe best bit about Nagbot is it is licensed under an open source license so it can be easily deployed without any software licensing. \n\n### Pre-requisites\n\n1. Elasticsearch database \n2. Elastalert installation\n3. Python runtime environment within which to run Nagbot\n4. Slack\n\n1. Elastalert uses or creates an elasticsearch index to store it's alert state. Occasionly this index will need to be deleted using elasticsearch management tools and the \"elastalert-create-index\" command line utility.\n\n## Installation\n\n## 1. Deploy NagBot to a server or cloud service.\n\n### 1.1 HEROKU Web Service\n\n#### Clone NAGBOT Repository\n```shell\ngit clone https://github.com/hilt86/NAGBOT.git\ncd NAGBOT\n```\n\n#### Install App to Heroku\n```shell\nheroku create\n```\n\n#### Add the following settings to the Heroku Dashboard for your App\n\nSettings --\u003e Config Vars\n\n| Config Var                        | Value                                     |\n| -------------                     | -------------                             |\n| DEBUG                             | \\\u003c True \\| False \\\u003e                       |\n| NAGBOT_SLACK_BOT_TOKEN            | \\\u003c Bot Token From Slack \\\u003e                |\n| NAGBOT_SLACK_CHANNEL              | \\\u003c Slack Channel ID \\\u003e                    |\n| NAGBOT_SLACK_ESCALATE_CHANNEL     | \\\u003c Slack Security/Escalation Channel ID \\\u003e|\n| NAGBOT_SLACK_VERIFICATION_TOKEN   | \\\u003c Slack Verification Token \\\u003e            |\n| NAGBOT_USER_ID                    | \\\u003c Slack Nagbot User ID \\\u003e                |\n\n\n## 2. Setting up NagBot in Slack.\n### 2.1 Create a NagBot Slack app on [api.slack.com](https://api.slack.com/apps?utm_source=events\u0026utm_campaign=build-bot-workshop\u0026utm_medium=workshop)\n\nTo set up the NagBot app to work with Slack we need to create a Slack App for your workspace.\nIn your browser navigate to https://api.slack.com/apps . You will be presented with an option to create a new app.\n\n![1_create_new_app](https://user-images.githubusercontent.com/37161577/40458776-3216e5ec-5f41-11e8-98b8-4b81be88d61f.png)\n\nSelect the friendly green button and create a new app.\n\nGive the App a name \"NagBot\" and assign it to it's Workspace.\n\n![2_app_name_workspace](https://user-images.githubusercontent.com/37161577/40458780-35bfd2c6-5f41-11e8-8685-6fb18bab1fc1.png)\n\nTo enable NagBot to interactively message the users of your workspace, Slack needs a *url* to send messages to and a *url* which define what actions to take. eg escalate an out of cardinality login.\n\nNavigate to the Interactive Components in the left menu list.\n\n![3_menu_list](https://user-images.githubusercontent.com/37161577/40458785-38d7920a-5f41-11e8-9150-d2fd3676b309.png)\n\nTurn on interactivity, then fill in the **Request URL** and **Options Load URL** fields, with the URL home of your NagBot app followed by `/slack/message_options` in the request URL and `/slack/message_actions` in the Options Load URL field.\n\n![4_turnon_interactivity](https://user-images.githubusercontent.com/37161577/40458788-3b6ce7ea-5f41-11e8-86f0-e2ce178506b9.png)\n\n**Don’t forget to save changes.**\n\nTo make NagBot appear like a standard user in your workspace, set the **Bot User** details:\n\n![5_botuser](https://user-images.githubusercontent.com/37161577/40458793-3eaf5730-5f41-11e8-83c5-61c3beed2c12.png)\n\n**Don’t forget to save.**\n\n##Event Escalation\nSecurity personnel will receive messages in the escalation channel from the bot as you have named it here.\n\n### 2.2 Tokens, Verification and Environmental variables.\n\nSo that Slack will accept message from your NagBot and can send messages back to Slack we need a:\n**SLACK_BOT_TOKEN** called the Bot User OAuth Token.\n**SLACK_VERIFICATION_TOKEN** conveniently enough call Verification Token.\nIt is important that these tokens remain secret, do not share them. \nTo retrieve the **SLACK_BOT_TOKEN** \nNavigate to OAuth \u0026 Permissions in the left hand side menu:\n\n![6_ oauth_token](https://user-images.githubusercontent.com/37161577/40458798-456db936-5f41-11e8-915c-48994c42efbf.png)\n\n Copy this to like named environmental variables on the server hosting your NagBot App.\n \neg. `$export SLACK_BOT_TOKEN=”xoxp-secret_token”`\n\nTo retrieve the **SLACK_VERIFICATION_TOKEN**\n\nNavigate to Basic Information in the left hand side menu:\n\n![7_verification_token](https://user-images.githubusercontent.com/37161577/40458803-4af1a96c-5f41-11e8-8bad-5502e7eb6a34.png)\n\n Copy this to like named environmental variables on the server hosting your NagBot App.\n \neg. `$export SLACK_VERIFICATION_TOKEN =”another secret token”`\n\n### 2.3 Create a channel to receive escalation events.\n\nFinally we need to create a Slack channel to which suspicious login events can be sent. Only administrative personnel and NagBot need access to this channel.\nCreate a channel, using either Slack app or the Slack Web site, in the workspace you wish NagBot to be active click the **+** next to Channels \n\n![8_addchannel](https://user-images.githubusercontent.com/37161577/40458806-4e29d1f4-5f41-11e8-8224-9bd04f23453a.png)\n\nFill in the displayed fields:\n- change Public to Private if you want escalations to remain private.\n- invite the users and NagBot.\n- then Create Channel.\n\n![9_escalatechannel](https://user-images.githubusercontent.com/37161577/40458808-50508572-5f41-11e8-9aac-407e65a4630b.png)\n\nAdditional users can always be added to the channel later.\n\nNagBot needs to know where to send the escalation message this is identified by the channel id. \nThe easiest way to find it is in the `url` field of your browser. Navigate to the slack channel and the channel id will appear after `/message/####`\n\neg. `https://yourserver.com/messages/ABCDEFGHI/`\n\nCopy this to a NAGBOT_SLACK_CHANNEL environmental variable onto your server.\n\neg. `$export NAGBOT_SLACK_CHANNEL=”ABCDEFGHI”`\n\n### 2.4 Manual test\n\nTo test slackbot manually generate an alert from Elastalert or use curl to send Nagbot a json test event.\n\nFor example:\n\n#### test_event.json\n\n`{\n \"system\": {\n  \"auth\": {\n   \"hostname\": \"yourhost\",\n   \"ssh\": {\n    \"geoip\": {\n     \"continent_name\": \"Oceania\",\n     \"city_name\": \"Pakenham East\",\n     \"country_iso_code\": \"AU\",\n     \"region_name\": \"Victoria\",\n     \"location\": {\n      \"lon\": 141.4741,\n      \"lat\": -34.0702\n     }\n    },\n    \"method\": \"password\",\n    \"port\": \"54084\",\n    \"ip\": \"8.4.4.4\",\n    \"event\": \"Accepted\"\n   },\n   \"pid\": \"8569\",\n   \"user\": \"your user id\",\n   \"timestamp\": \"May 18 02:34:24\"\n  }\n },\n \"offset\": 162887,\n \"beat\": {\n  \"hostname\": \"your.elastic.search.server\",\n  \"name\": \" your.elastic.search.server \",\n  \"version\": \"6.2.3\"\n },\n \"prospector\": {\n  \"type\": \"log\"\n },\n \"source\": \"/var/log/auth.log\",\n \"fileset\": {\n  \"module\": \"system\",\n  \"name\": \"auth\"\n }\n}`\n\nFrom the command line use curl to send the json to NagBot\n\n#### Curl command:\n\n`curl -XPOST --header \"Content-Type: application/json\" 'https://yourserver.nagbotapp.com/api/json/nagbot/' -d @test_event.json`\n\n\n### 3 Integration test\n\nNow that you have tested the components you should be able to login to one of your systems monitored by Logstash / Elasticsearch from a few different IP addresses and you should get a challenge by Nagbot :\n\n\n![10_nagbotmessage](https://user-images.githubusercontent.com/37161577/40458814-53a3ef7a-5f41-11e8-90a4-5f97ae3386bd.png)\n\n\nThe user then selects a response from the dropdown \"That was me\" or \"Wasn't me!\" and Nagbot takes appropriate action. If the user responds \"Wasn't me\" Nagbot escalates the event to a separate Slack channel dedicated to security incidents:\n\n\n![11_securityalert](https://user-images.githubusercontent.com/37161577/40458815-5628e9f8-5f41-11e8-82b2-eae5cfbb9697.png)\n\n### 4 Credits\n\nOriginal concept from [Ryan Huber](https://slack.engineering/distributed-security-alerting-c89414c992d6) but he took too long to open source his version so we decided to make our own!\n\nThis project is a student project for a [University of Southern Queensland](https//www.usq.edu.au) Undergraduate Subject  CSC3600. Any opinions expressed are our own and do not necessarily represent policy of USQ.\n\n**Project Members** \n\n[Hilton De Meillon](https://github.com/hilt86)\n\n[Dustin Lee](https://github.com/Dustin-USQ)\n\n[John Omer-Cooper](https://github.com/johno-c)\n\n[Bandr Talie O Alkhuzaie](https://github.com/bandru1078238)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhilt86%2FNAGBOT","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhilt86%2FNAGBOT","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhilt86%2FNAGBOT/lists"}