Monitoring and enumerating Slack for exposed secrets
Project description
Slack Watchman
Monitoring and enumerating Slack for exposed secrets
About Slack Watchman
Slack Watchman is an application that uses the Slack API to find potentially sensitive data exposed in a Slack workspace, and to enumerate other useful information for red, blue and purple teams.
More information about Slack Watchman can be found on my blog.
Features
Slack Watchman looks for:
- API Keys, Tokens & Service Accounts
- AWS, Azure, GCP, Google API, Slack (keys & webhooks), Twitter, Facebook, GitHub and more
- 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 and more
- Financial data
- Paypal Braintree tokens, Bank card details, IBAN numbers, CUSIP numbers and more
It also enumerates the following:
- User data
- All users & all admins
- Channel data
- All channels, including externally shared channels
Time based searching
You can run Slack Watchman to look for results going back as far as:
- 24 hours
- 7 days
- 30 days
- All time
This means after one deep scan, you can schedule Slack Watchman to run regularly and only return results from your chosen timeframe.
Signatures
Slack Watchman uses custom YAML signatures to detect matches in Slack. These signatures are pulled from the central Watchman Signatures repository. Slack Watchman automatically updates its signature base at runtime to ensure its using the latest signatures to detect secrets.
Logging
Slack Watchman gives the following logging options:
- Terminal-friendly Stdout
- JSON to Stdout
Slack Watchman defaults to terminal-friendly stdout logging if no option is given. This is designed to be easier for humans to read.
JSON logging is also available, which is perfect for ingesting into a SIEM or other log analysis platforms.
JSON formatted logging can be easily redirected to a file as below:
slack-watchman --timeframe a --all --output json >> slack_watchman_log.json
Authentication Requirements
Slack API token
To run Slack Watchman, you will need a Slack API OAuth access token. You can do this by creating a simple Slack App.
The app needs to have the following User Token Scopes added:
channels:read
files:read
groups:read
im:read
links:read
mpim:read
remote_files:read
search:read
team:read
users:read
users:read.email
Note: User tokens act on behalf of the user who authorises them, so I would suggest you create this app and authorise it using a service account, otherwise the app will have access to your private channels and chats.
Cookie Authentication
Alternatively, Slack Watchman can also authenticate to Slack using a user d
cookie, which is stored in the browser of each user logged into a workspace.
To use cookie authentication, you will need to provide the d
cookie, and the URL of the target workspace. Then you will need to use the --cookie
flag when running Slack Watchman
More information on cookie authentication can be found on my blog
Providing tokens
Slack Watchman will first try to get the Slack token (plus the cookie token and URL if selected) from the environment variables
SLACK_WATCHMAN_TOKEN
SLACK_WATCHMAN_COOKIE
SLACK_WATCHMAN_URL
If this fails it will try to load the token(s) from .conf
file (see below).
.conf file
Configuration options can be passed in a file named watchman.conf
which must be stored in your home directory. The file should follow the YAML format, and should look like below:
slack_watchman:
token: xoxp-xxxxxxxx
cookie: xoxd-%2xxxxx
url: https://xxxxx.slack.com
Slack Watchman will look for this file at runtime, and use the configuration options from here. If you are not using cookie auth, leave cookie
and url
blank.
If you are having issues with your .conf file, run it through a YAML linter.
An example file is in docs/example.conf
Note: Cookie and URL values are optional, and not required if not using cookie authentication.
Installation
You can install the latest stable version via pip:
python3 -m pip install slack-watchman
Or build from source yourself:
Download the release source files, then from the top level repository run:
python3 -m pip build
python3 -m pip install --force-reinstall dist/*.whl
Docker Image
Slack Watchman is also available from the Docker hub as a Docker image:
docker pull papermountain/slack-watchman:latest
You can then run Slack Watchman in a container, making sure you pass the required environment variables:
// help
docker run --rm papermountain/slack-watchman -h
// scan all
docker run --rm -e SLACK_WATCHMAN_TOKEN=xoxp... papermountain/slack-watchman --timeframe a --all --output json
docker run --rm --env-file .env papermountain/slack-watchman --timeframe a --all --output stdout
Usage
Slack Watchman will be installed as a global command, use as follows:
usage: slack-watchman [-h] --timeframe {d,w,m,a} [--output {json,stdout}] [--version] [--all] [--users] [--channels] [--pii] [--secrets]
[--debug] [--verbose] [--cookie]
Monitoring and enumerating Slack for exposed secrets
options:
-h, --help show this help message and exit
--output {json,stdout}, -o {json,stdout}
Where to send results
--version, -v show program's version number and exit
--all, -a Find secrets and PII
--users, -u Enumerate users and output them to .csv
--channels, -c Enumerate channels and output them to .csv
--pii, -p Find personal data: DOB, passport details, drivers licence, ITIN, SSN etc.
--secrets, -s Find exposed secrets: credentials, tokens etc.
--debug, -d Turn on debug level logging
--verbose, -V Turn on more verbose output for JSON logging. This includes more fields, but is larger
--cookie Use cookie auth using Slack d cookie. REQUIRES either SLACK_WATCHMAN_COOKIE and SLACK_WATCHMAN_URL environment
variables set, or both values set in watchman.conf
required arguments:
--timeframe {d,w,m,a}, -t {d,w,m,a}
How far back to search: d = 24 hours w = 7 days, m = 30 days, a = all time
You can run Slack Watchman to look for everything, and output to default stdout:
slack-watchman --timeframe a --all
Other Watchman apps
You may be interested in the other apps in the Watchman family:
License
The source code for this project is released under the GNU General Public Licence. This project is not associated with Slack Technologies or Salesforce.
[4.0.1] - 2023-05-05
Changed
- User output in stdout logging now includes display name and email. The accounts for cases where usernames are nonsensical.
[4.0.0] - 2023-05-03
This major version release brings multiple updates to Slack Watchman in usability, functionality and behind the scenes improvements.
Note: While efforts have been made to make sure there is some backwards compatibility, this release may have some breaking changes on previous versions. Make sure to look at the removed secion
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 will always be using the most up to date signatures.
- Major UI overhaul
- A lot of feedback said Slack Watchman was hard to read. This version introduces new terminal optimised logging as a logging option, as well as JSON formatting. This formatting is now the default when running with no output option selected, and is a lot easier for humans to read. Also, colours!
- Cookie login
- If you have a Slack
d
cookie (which can be gathered from a web browser authenticated to Slack), and you know the URL of the target Slack workspace, Slack Watchman now allows you to authenticate using cookie auth, instead of supplying a bot token.
- If you have a Slack
- Multiprocessing and other backend improvements
- Slack Watchman now makes more efficient use of API calls, and incorporates multiprocessing, to run faster than previous versions. Larger workspaces can now be enumerated much quicker.
- Docker image support
- Slack Watchman is now available as a Docker image. Simply pull from Docker Hub
docker pull papermountain/slack-watchman:latest
- Slack Watchman is now available as a Docker image. Simply pull from Docker Hub
- More useful enumeration options added
- Slack Watchman now gathers more information on a workspace. Useful if your use case is more red than blue...
- Get information on calling user
- Provides you information on the user you are authenticated as, including whether the user has 2FA configured, whether they are an admin etc.
- CSV files containing information on all users and channels in the workspace.
- Get information on calling user
- Slack Watchman now gathers more information on a workspace. Useful if your use case is more red than blue...
- Option choose between verbose or succinct logging when using JSON output. Default is succinct.
- Debug logging option
Removed
- Socket logging functionality
- I'm not sure this functionality was used, but the move to more accessible stdout and JSON logging options means that the option to log to a listening socket has been removed.
- Some CSV output
- For the same reason as above, logging results to CSV has been removed. Enumerating users and channels can still be output to CSV, but formatting a CSV file for a complex nested datastructure is a nightmare, and makes future modifications time consuming.
- Logging to file
- To keep logging as simple as possible, the file output option has also been removed. This can easily be reproduced by piping the output of running Slack Watchman to a file:
slack-watchman --timeframe w --all --output json >> sw-log.json
- To keep logging as simple as possible, the file output option has also been removed. This can easily be reproduced by piping the output of running Slack Watchman to a file:
- Local/custom 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
[3.0.10] - 2020-11-08
Fixed
- Retry added for occasional Requests HTTPSConnectionPool error
Added
- Version added to Stdout logging
- Better exception handling and logging exceptions correctly
- Workspace field added to critical error
[3.0.9] - 2020-10-31
Added
- Mailgun API token rule
- Mailchimp API token rule
- Twilio API token rule
- Stripe API token rule
- Heroku API token rule
- Shodan API token rule
- Cloudflare API token rule
[3.0.8] - 2020-10-10
Added
- Exact regex string match added to output from message searches
- Check added for when the given token doesn't have the required API scope. On incorrect scope, and exception will be raised and the required scope will be output to log
[3.0.7] - 2020-10-02
Added
- Rule to detect MasterCard Datacash credentials
[3.0.6] - 2020-09-22
Changed
- File searching now includes user who posted file via users.list API method
- Logging field name changes = 'type' -> 'detection_type', 'detection' -> 'detection_data'
[3.0.5] - 2020-09-18
Changed
- Updated output to strip quotes from query strings. This should allow better JSON parsing with more log ingestors
- File searching was missing file type output in log data in some occasions, now fixed
[3.0.4] - 2020-09-10
Added
- Added rules to search for:
- CV files
- Files and spreadsheets containing budget and salary information
[3.0.2] - 2020-09-06
Added
- CHANGELOG to track updates
- Small bug meant that PyPI installations weren't including the YAML rule files. This has now been fixed.
Changed
- Top level dir renamed from
watchman
toslack_watchman
to place nicer with PyPI
[3.0.0] - 2020-09-04
Added
- Rules based searching
- Logging options: Log file, Stdout, TCP stream
- Deduplication of output
- Refactor into slack_wrapper to use a class to create an API client
Changed
- Top level dir renamed from
watchman
toslack_watchman
to place nicer with PyPI
Removed
- Custom search by CSV. This is now done by creating your own custom rule
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for slack_watchman-4.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 47e98b66ec2c98906d4a639095c78d56a9d217d8a9991c2316eadc0a45d079dc |
|
MD5 | 10fcbc44270e89c9b5bd96015b40ee23 |
|
BLAKE2b-256 | a439f82c8406733c31011b7b1de5e8518d6a95c10f1135c922028c62778a2d56 |