{"id":13617145,"url":"https://github.com/dropbox/securitybot","last_synced_at":"2025-04-14T03:33:05.260Z","repository":{"id":57465205,"uuid":"66394057","full_name":"dropbox/securitybot","owner":"dropbox","description":"Distributed alerting for the masses!","archived":true,"fork":false,"pushed_at":"2018-11-01T16:05:37.000Z","size":83,"stargazers_count":996,"open_issues_count":14,"forks_count":112,"subscribers_count":58,"default_branch":"master","last_synced_at":"2024-12-17T01:03:40.679Z","etag":null,"topics":["bot","duo","security-automation","slack"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dropbox.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":"securitybot/__init__.py","support":null}},"created_at":"2016-08-23T18:48:01.000Z","updated_at":"2024-12-03T03:57:40.000Z","dependencies_parsed_at":"2022-09-17T18:00:50.794Z","dependency_job_id":null,"html_url":"https://github.com/dropbox/securitybot","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/dropbox%2Fsecuritybot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fsecuritybot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fsecuritybot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fsecuritybot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dropbox","download_url":"https://codeload.github.com/dropbox/securitybot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248815759,"owners_count":21165977,"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":["bot","duo","security-automation","slack"],"created_at":"2024-08-01T20:01:37.458Z","updated_at":"2025-04-14T03:33:00.246Z","avatar_url":"https://github.com/dropbox.png","language":"Python","readme":"# Securitybot\n### Distributed alerting for the masses!\nSecuritybot is an open-source implementation of a distributed alerting chat bot, as described in Ryan Huber's [blog post][slack-blog].\nDistributed alerting improves the monitoring efficiency of your security team and can help you catch security incidents faster and more efficiently.\nWe've tried to remove all Dropbox-isms from this code so that setting up your own instance should be fairly painless.\nIt should be relatively easy to install the listed requirements in a virtualenv/Docker container and simply have the bot do its thing.\nWe also provide a simple front end to dive through the database, receive API calls, and create custom alerts for the bot to reach out to people as desired.\n\n## Deploying\nThis guide runs through setting up a Securitybot instance as quickly as possible with no frills.\nWe'll be connecting it to Slack, SQL, and Duo.\nOnce we're done, we'll have a file that looks something like `main.py`.\n\n### SQL\nYou'll need a database called `securitybot` on some MySQL server somewhere.\nWe've provided a function called `init_sql` located in `securitybot/sql.py` that will initialize SQL.\nCurrently it's set up to use the host `localhost` with user `root` and no password.\nYou'll need to change this because of course that's not how your database is set up.\n\n### Slack\nYou'll need a token to be able to integrate with Slack.\nThe best thing to do would be to [create a bot user][bot-user] and use that token for Securitybot.\nYou'll also want to set up a channel to which the bot will report when users specify that they haven't performed an action.\nFind the unique ID for that channel (it'll look similar to `C123456`) and be sure to invite the bot user into that channel, otherwise it won't be able to send messages.\n\n### Duo\nFor Duo, you'll want to create an [Auth API][auth-api] instances, name it something clever, and keep track of the integration key, secret key, and auth API endpoint URI.\n\n### Running the bot\nTake a look at the provided `main.py` in the root directory for an example on how to use all of these.\nReplace all of the global variables with whatever you found above.\nIf the following were all generated successfully, Securitybot should be up and running.\nTo test it, message the bot user it's assigned to and say `hi`.\nTo test the process of dealing with an alert, message `test` to test the bot.\n\n## Architecture\nSecuritybot was designed to be as modular as possible.\nThis means that it's possible to easily swap out chat systems, 2FA providers, and alerting data sources.\nThe only system that is tightly integrated with the bot is SQL, but adding support for other databases shouldn't be difficult.\nHaving a database allows alerts to be persistent and means that the bot doesn't lose (too much) state if there's some transient failure.\n\n### Securitybot proper\nThe bot itself performs a small set of functions:\n\n1. Reads messages, interpreting them as commands.\n1. Polls each user object to update their state of applicable.\n1. Grabs new alerts from the database and assigns them to users or escalates on an unknown user.\n\nMessaging, 2FA, and alert management are provided by configurable modules, and added to the bot upon initialization.\n\n#### Commands\nThe bot handles incoming messages as commands.\nCommand parsing and handling is done in the `Securitybot` class and the commands themselves are provided in two places.\nThe functions for the commands are defined in `commands.py` and their structure is defined in `commands.yaml` under the `config/` directory.\n\n### Messaging\nSecuritybot is designed to be compatible with a wide variety of messaging systems.\nWe currently provide bindings for Slack, but feel free to contribute any other plugins, like for Gitter or Zulip, upstream.\nMessaging is made possible by `securitybot/chat/chat.py` which provides a small number of functions for querying users in a messaging group, messaging those users, and sending messages to a specific channel/room.\nTo add bindings for a new messaging system, subclass `Chat`.\n\n### 2FA\n2FA support is provided by `auth/auth.py`, which wraps async 2FA in a few functions that enable checking for 2FA capability, starting a 2FA session, and polling the state of the 2FA session.\nWe provide support for Duo Push via the Duo Auth API, but adding support for a different product or some in-house 2FA solution is as easy as creating a subclass of `Auth`.\n\n### Task management\nTask management is provided by `tasker/tasker.py` and the `Tasker` class.\nSince alerts are logged in an SQL database, the provided Tasker is `SQLTasker`.\nThis provides support for grabbing new tasks and updating them via individual `Task` objects.\n\n### Blacklists\nBlacklists are handled by the SQL database, provided in `blacklist/blacklist.py` and the subclass `blacklist/sql_blacklist.py`.\n\n### Users\nThe `User` object provides support for handling user state.\nWe keep track of whatever information a messaging system gives to us, but really only ever use a user's unique ID and username in order to contact them.\n\n### Alerts\nAlerts are uniquely identified by a SHA-256 hash which comes from some hash of the event that generated them.\nWe assume that a SHA-256 hash is sufficiently random for there to be no collisions.\nIf you encounter a SHA-256 collision, please contact someone at your nearest University and enjoy the fame and fortune it brings upon you.\n\n## FAQ\n\nPlease ask us things\n\n## Contributing\nContributors must abide by the [Dropbox Contributor License Agreement][cla].\n\n## License\n\nCopyright 2016 Dropbox, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n\n\n[slack-blog]: https://slack.engineering/distributed-security-alerting-c89414c992d6 \"Distributed Alerting\"\n[bot-user]: https://api.slack.com/bot-users \"Slack Bot Users\"\n[auth-api]: https://duo.com/docs/authapi \"Duo Auth API\"\n[cla]: https://opensource.dropbox.com/cla/ \"Dropbox CLA\"\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdropbox%2Fsecuritybot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdropbox%2Fsecuritybot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdropbox%2Fsecuritybot/lists"}