<img src="https://i.imgur.com/VPgx6ra.png" width="550">
# Slack Watchman for Enterprise Grid
## About Slack Watchman for Enterprise Grid
Slack Watchman for Enterprise Grid uses the Slack Enterprise Grid DLP API to look for potentially exposed secrets and sensitive data in Slack Enterprise Grid.
**Note**: Slack Watchman for Enterprise Grid is designed for Enterprise Grid subscribers of Slack only. If you use Slack without an Enterprise subscription, you can use the standard version of [Slack Watchman](https://github.com/PaperMtn/slack-watchman)
### Features
Slack Watchman for Enterprise Grid looks for:
- API Keys, Tokens & Service Accounts
- AWS, Azure, GCP, Google API, Slack (keys & webhooks), Twitter, Facebook, GitHub
- Generic Private keys
- Access Tokens, Bearer Tokens, Client Secrets, Private Tokens
- Files
- Certificate files
- Potentially interesting/malicious/sensitive files (.docm, .xlsm, .zip etc.)
- Executable files
- Keychain files
- Config files for popular services (Terraform, Jenkins, OpenVPN and more)
- Personal Data
- Leaked passwords
- Passport numbers, Dates of birth, Social security numbers, National insurance numbers, Drivers licence numbers (UK), Individual Taxpayer Identification Number
- CVs, salary information
- Financial data
- PayPal Braintree tokens, Bank card details, IBAN numbers, CUSIP numbers
- Budget files
It looks for this exposed data across all workspaces in the Enterprise, in the following locations:
- Public channels
- Private channels
- Draft messages
- Slack connect channels
- Direct messages
- Multi-person direct messages
#### Time based searching
Slack Watchman for Enterprise Grid can search through all messages sent in your Enterprise in the previous 24 hours. Limitations in the API, and data processing bottlenecks, don't allow for any further than 24 hours to be queried.
You can provide time periods to search for using the `--hours` and `--minutes` options at runtime. This means you can schedule running regularly, and in general little and often is the best approach.
#### Multiprocessing
Multiprocessing is used to search the potentially huge amount of data retrieved when getting all messages sent in an Enterprise. You can specify how many cores to use at runtime, and the more cores you use, the faster processing is generally done. That being said, you are still constrained by the API.
I have found the most efficient approach is to use between 8-12 cores.
You can specify cores using the optional flag `--cores` at runtime. If this flag is not set, Slack Watchman will automatically use all available cores up to a maximum of 8.
### Signatures
Slack Watchman uses custom YAML signatures to detect matches in Slack. These signatures are pulled from the central [Watchman Signatures repository](https://github.com/PaperMtn/watchman-signatures). Slack Watchman for Enterprise Grid automatically updates its signature base at runtime to ensure its using the latest signatures to detect secrets.
## Requirements
### Slack API token
To run Slack Watchman for Enterprise Grid, you will need a Slack API access token that is authorised to use the Enterprise DLP API.
To do this, you need to create a [Slack App](https://api.slack.com/apps) and install it at the organisation level.
The app needs to have the following **User Token Scopes** added:
```
discovery:read
discovery:write
team:read
users:read
```
**Note**: `discovery:read` and `discovery:write` can only be added to an app by Slack themselves, you will need to contact your Slack CSM. They will also provide you with instructions on how to install the app at organisation level and retrieve the access token.
#### Providing token
Provide the token in the environment variable `SLACK_WATCHMAN_EG_TOKEN`
## Installation
You can install the latest stable version via pip:
`python3 -m pip install slack-watchman-eg`
Or build from source yourself:
Download the release source files, then from the top level repository run:
```shell
python3 -m pip build
python3 -m pip install --force-reinstall dist/*.whl
```
## Docker Image
Slack Watchman for Enterprise Grid is also available from the Docker hub as a Docker image:
`docker pull papermountain/slack-watchman-eg:latest`
You can then run Slack Watchman for Enterprise Grid in a container, making sure you pass the required environment variables:
```
// help
docker run --rm papermountain/slack-watchman-eg -h
// scan all
docker run --rm -e SLACK_WATCHMAN_EG_TOKENN=xoxp... papermountain/slack-watchman-eg --hours 1 --cores 8
docker run --rm --env-file .env papermountain/slack-watchman-eg --hours 1 --cores 8
```
## Usage
```
usage: slack-watchman-eg [-h] [--hours HOURS] [--minutes MINUTES] [--output {json,terminal}] [--cores CORES] [--version] [--users] [--workspaces] [--debug] [--verbose]
Monitoring your Slack Enterprise Grid for sensitive information
options:
-h, --help show this help message and exit
--hours HOURS, -hr HOURS
How far back to search in whole hours between 1-24. Defaults to 1 if no acceptable value given
--minutes MINUTES, -m MINUTES
How far back to search in whole minutes between 1-60
--output {json,terminal}, -o {json,terminal}
What logging output to use - JSON formatted output, or textual outputfor reading via terminal. Default is terminal
--cores CORES, -c CORES
Number of cores to use between 1-12
--version, -v show program's version number and exit
--users, -u Return all users
--workspaces, -w Return all workspaces
--debug, -d Turn on debug level logging
--verbose, -V Turn on more verbose output for JSON logging. This includes more fields, but is larger
```
## Other Watchman apps
You may be interested in the other apps in the Watchman family:
- [Slack Watchman](https://github.com/PaperMtn/slack-watchman)
- [GitLab Watchman](https://github.com/PaperMtn/gitlab-watchman)
- [GitHub Watchman](https://github.com/PaperMtn/github-watchman)
## License
The source code for this project is released under the [GNU General Public Licence](https://www.gnu.org/licenses/licenses.html#GPL). This project is not associated with Slack Technologies or Salesforce.
## [2.0.0] - 2023-04-14
This major version release brings multiple updates to Slack Watchman for Enterprise Grid, both in usability, functionality and behind the scenes improvements.
### Added
- Support for centralised signatures from the Watchman Signatures repository. This makes it much easier to keep the signature base for all Watchman applications up to date, and to add functionality to Slack Watchman with new signatures. New signatures are downloaded, and updates to existing signatures are applied, at runtime, meaning Slack Watchman for Enterprise Grid will always be using the most up to date signatures.
- Option for terminal optimised logging instead of JSON formatting. This is now the default when running with no output option selected, and is a lot easier for humans to read. Also, colours!
- Option choose between verbose or succinct logging when using JSON output. Default is succinct.
- Debug logging option
### Removed
- Support for tombstoning posts that match signatures removed
- Local signatures - Centralised signatures mean that user-created custom signatures can't be used with Slack Watchman for Enterprise Grid anymore. If you have made a signature you think would be good for sharing with the community, feel free to add it to the Watchman Signatures repository, so it can be used in all Watchman applications
- For the reason above, the functionality to have sandbox signatures has been removed as well
### Fixed
- Draft searches were giving an error due to not being able to populate some workspace information. This has now been fixed
## [1.1.1] - 2022-05-16
### Added
- Signature to find Atlassian tokens
## [1.1.0] - 2022-04-02
### Added
- Docker image now available from the Docker hub, or by building from source.
- Support for Python 3.7
- New logo to play nicely with dark mode
### Fixed
- More errors when importing packages
## [1.0.2] - 2021-12-30
### Fixed
- Error when importing packages
- Signatures not being included in the distribution package
## [1.0.1] - 2021-12-30
### Added
- Refactor and update distribution files
## [1.0.0] - 2021-12-30
- Initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/PaperMtn/slack-watchman-enterprise-grid",
"name": "slack-watchman-eg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "audit,slack,slack-watchman,watchman,blue-team,red-team,threat-hunting,slack-watchman-enterprise-grid",
"author": "PaperMtn",
"author_email": "papermtn@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/d1/73/7842d6bdf47e3d69b1546b9d9a34825f947685d8a2ca406a01cdc84c83e7/slack-watchman-eg-2.0.0.tar.gz",
"platform": null,
"description": "<img src=\"https://i.imgur.com/VPgx6ra.png\" width=\"550\">\n\n# Slack Watchman for Enterprise Grid\n\n\n\n\n\n## About Slack Watchman for Enterprise Grid\n\nSlack Watchman for Enterprise Grid uses the Slack Enterprise Grid DLP API to look for potentially exposed secrets and sensitive data in Slack Enterprise Grid.\n\n**Note**: Slack Watchman for Enterprise Grid is designed for Enterprise Grid subscribers of Slack only. If you use Slack without an Enterprise subscription, you can use the standard version of [Slack Watchman](https://github.com/PaperMtn/slack-watchman)\n\n### Features\nSlack Watchman for Enterprise Grid looks for:\n\n- API Keys, Tokens & Service Accounts\n - AWS, Azure, GCP, Google API, Slack (keys & webhooks), Twitter, Facebook, GitHub\n - Generic Private keys\n - Access Tokens, Bearer Tokens, Client Secrets, Private Tokens\n- Files\n - Certificate files\n - Potentially interesting/malicious/sensitive files (.docm, .xlsm, .zip etc.)\n - Executable files\n - Keychain files\n - Config files for popular services (Terraform, Jenkins, OpenVPN and more)\n- Personal Data\n - Leaked passwords\n - Passport numbers, Dates of birth, Social security numbers, National insurance numbers, Drivers licence numbers (UK), Individual Taxpayer Identification Number\n - CVs, salary information\n- Financial data\n - PayPal Braintree tokens, Bank card details, IBAN numbers, CUSIP numbers\n - Budget files\n \nIt looks for this exposed data across all workspaces in the Enterprise, in the following locations:\n- Public channels\n- Private channels\n- Draft messages\n- Slack connect channels\n- Direct messages\n- Multi-person direct messages\n\n#### Time based searching\nSlack Watchman for Enterprise Grid can search through all messages sent in your Enterprise in the previous 24 hours. Limitations in the API, and data processing bottlenecks, don't allow for any further than 24 hours to be queried. \n\nYou can provide time periods to search for using the `--hours` and `--minutes` options at runtime. This means you can schedule running regularly, and in general little and often is the best approach.\n\n#### Multiprocessing\nMultiprocessing is used to search the potentially huge amount of data retrieved when getting all messages sent in an Enterprise. You can specify how many cores to use at runtime, and the more cores you use, the faster processing is generally done. That being said, you are still constrained by the API.\n\nI have found the most efficient approach is to use between 8-12 cores.\n\nYou can specify cores using the optional flag `--cores` at runtime. If this flag is not set, Slack Watchman will automatically use all available cores up to a maximum of 8.\n### Signatures\nSlack Watchman uses custom YAML signatures to detect matches in Slack. These signatures are pulled from the central [Watchman Signatures repository](https://github.com/PaperMtn/watchman-signatures). Slack Watchman for Enterprise Grid automatically updates its signature base at runtime to ensure its using the latest signatures to detect secrets. \n\n## Requirements\n### Slack API token\nTo run Slack Watchman for Enterprise Grid, you will need a Slack API access token that is authorised to use the Enterprise DLP API.\n\nTo do this, you need to create a [Slack App](https://api.slack.com/apps) and install it at the organisation level.\n\nThe app needs to have the following **User Token Scopes** added:\n```\ndiscovery:read\ndiscovery:write\nteam:read\nusers:read\n```\n**Note**: `discovery:read` and `discovery:write` can only be added to an app by Slack themselves, you will need to contact your Slack CSM. They will also provide you with instructions on how to install the app at organisation level and retrieve the access token.\n\n#### Providing token\nProvide the token in the environment variable `SLACK_WATCHMAN_EG_TOKEN`\n\n## Installation\nYou can install the latest stable version via pip:\n\n`python3 -m pip install slack-watchman-eg`\n\nOr build from source yourself:\n\nDownload the release source files, then from the top level repository run:\n```shell\npython3 -m pip build\npython3 -m pip install --force-reinstall dist/*.whl\n```\n\n## Docker Image\n\nSlack Watchman for Enterprise Grid is also available from the Docker hub as a Docker image:\n\n`docker pull papermountain/slack-watchman-eg:latest`\n\nYou can then run Slack Watchman for Enterprise Grid in a container, making sure you pass the required environment variables:\n\n```\n// help\ndocker run --rm papermountain/slack-watchman-eg -h\n\n// scan all\ndocker run --rm -e SLACK_WATCHMAN_EG_TOKENN=xoxp... papermountain/slack-watchman-eg --hours 1 --cores 8\ndocker run --rm --env-file .env papermountain/slack-watchman-eg --hours 1 --cores 8\n```\n\n## Usage\n```\nusage: slack-watchman-eg [-h] [--hours HOURS] [--minutes MINUTES] [--output {json,terminal}] [--cores CORES] [--version] [--users] [--workspaces] [--debug] [--verbose]\n\nMonitoring your Slack Enterprise Grid for sensitive information\n\noptions:\n -h, --help show this help message and exit\n --hours HOURS, -hr HOURS\n How far back to search in whole hours between 1-24. Defaults to 1 if no acceptable value given\n --minutes MINUTES, -m MINUTES\n How far back to search in whole minutes between 1-60\n --output {json,terminal}, -o {json,terminal}\n What logging output to use - JSON formatted output, or textual outputfor reading via terminal. Default is terminal\n --cores CORES, -c CORES\n Number of cores to use between 1-12\n --version, -v show program's version number and exit\n --users, -u Return all users\n --workspaces, -w Return all workspaces\n --debug, -d Turn on debug level logging\n --verbose, -V Turn on more verbose output for JSON logging. This includes more fields, but is larger\n```\n\n## Other Watchman apps\nYou may be interested in the other apps in the Watchman family:\n- [Slack Watchman](https://github.com/PaperMtn/slack-watchman)\n- [GitLab Watchman](https://github.com/PaperMtn/gitlab-watchman)\n- [GitHub Watchman](https://github.com/PaperMtn/github-watchman)\n\n## License\nThe source code for this project is released under the [GNU General Public Licence](https://www.gnu.org/licenses/licenses.html#GPL). This project is not associated with Slack Technologies or Salesforce.\n## [2.0.0] - 2023-04-14\nThis major version release brings multiple updates to Slack Watchman for Enterprise Grid, both in usability, functionality and behind the scenes improvements.\n### Added\n- Support for centralised signatures from the Watchman Signatures repository. This makes it much easier to keep the signature base for all Watchman applications up to date, and to add functionality to Slack Watchman with new signatures. New signatures are downloaded, and updates to existing signatures are applied, at runtime, meaning Slack Watchman for Enterprise Grid will always be using the most up to date signatures. \n- Option for terminal optimised logging instead of JSON formatting. This is now the default when running with no output option selected, and is a lot easier for humans to read. Also, colours! \n- Option choose between verbose or succinct logging when using JSON output. Default is succinct.\n- Debug logging option\n### Removed\n- Support for tombstoning posts that match signatures removed\n- Local signatures - Centralised signatures mean that user-created custom signatures can't be used with Slack Watchman for Enterprise Grid anymore. If you have made a signature you think would be good for sharing with the community, feel free to add it to the Watchman Signatures repository, so it can be used in all Watchman applications \n- For the reason above, the functionality to have sandbox signatures has been removed as well\n### Fixed\n- Draft searches were giving an error due to not being able to populate some workspace information. This has now been fixed\n\n## [1.1.1] - 2022-05-16\n### Added\n- Signature to find Atlassian tokens\n\n## [1.1.0] - 2022-04-02\n### Added\n- Docker image now available from the Docker hub, or by building from source.\n- Support for Python 3.7\n- New logo to play nicely with dark mode\n### Fixed\n- More errors when importing packages\n\n## [1.0.2] - 2021-12-30\n### Fixed\n- Error when importing packages\n- Signatures not being included in the distribution package\n\n## [1.0.1] - 2021-12-30\n### Added\n- Refactor and update distribution files\n\n## [1.0.0] - 2021-12-30\n- Initial release\n\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Monitoring Slack Enterprise Grid for exposed secrets",
"version": "2.0.0",
"split_keywords": [
"audit",
"slack",
"slack-watchman",
"watchman",
"blue-team",
"red-team",
"threat-hunting",
"slack-watchman-enterprise-grid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5201555f84a639422398e9f2af127110ff80474ddea0d2bf9544da780be1c32",
"md5": "4f79fc82b0acc5941aec209a6bed44fd",
"sha256": "edc29452c18e309b825a119b47cc5134e131b786fd21301b4d2a265891822ff3"
},
"downloads": -1,
"filename": "slack_watchman_eg-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f79fc82b0acc5941aec209a6bed44fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 41440,
"upload_time": "2023-04-15T19:50:59",
"upload_time_iso_8601": "2023-04-15T19:50:59.700075Z",
"url": "https://files.pythonhosted.org/packages/f5/20/1555f84a639422398e9f2af127110ff80474ddea0d2bf9544da780be1c32/slack_watchman_eg-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d1737842d6bdf47e3d69b1546b9d9a34825f947685d8a2ca406a01cdc84c83e7",
"md5": "1768e86d6ab0844a829be3d7c20cf52d",
"sha256": "412f43e3383d0c27fa5f4d9a063108e09848aeb98744098b9d28107bbd25365f"
},
"downloads": -1,
"filename": "slack-watchman-eg-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1768e86d6ab0844a829be3d7c20cf52d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 41377,
"upload_time": "2023-04-15T19:51:01",
"upload_time_iso_8601": "2023-04-15T19:51:01.308658Z",
"url": "https://files.pythonhosted.org/packages/d1/73/7842d6bdf47e3d69b1546b9d9a34825f947685d8a2ca406a01cdc84c83e7/slack-watchman-eg-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-15 19:51:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "PaperMtn",
"github_project": "slack-watchman-enterprise-grid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "slack-watchman-eg"
}
JSON
