slack-watchman enumerates a Slack workspace via its API to surface leaked credentials, PII and misconfigurations, serving red, blue and purple teams on systems they are authorized to assess.
| Tool | PaperMtn/slack-watchman — Slack API monitoring and enumeration tool for exposed secrets and sensitive data |
| Category | SaaS security auditing / secrets detection (Python, GPL-3.0) |
| Primary Use | Continuously scanning an owned Slack workspace with --secrets, --pii and time-bounded --timeframe queries to catch leaked tokens, keys and personal data |
| Safe Use | Running against workspaces you own or are explicitly authorized to assess, typically with a service-account Slack app token, for defensive hygiene and continuous monitoring |
| Telemetry Note | All activity flows through the official Slack Web API with a user token or d cookie, so scans are visible in Slack admin logs and app audit trails; defenders can monitor for apps with broad search:read/files:read scopes |
slack-watchman is a Python application from PaperMtn that uses the Slack API to find potentially sensitive data exposed across a workspace, and to enumerate structural information that red, blue and purple teams will each find useful for different reasons. The project sits at roughly 404 stars, is licensed under GPL-3.0, and positions itself squarely as a monitoring utility rather than an attack tool: the intended workflow is a deep baseline scan followed by scheduled incremental runs. It is part of a small family of sibling tools — gitlab-watchman, github-watchman, and a variant for Slack Enterprise Grid — which signals a mature, maintained ecosystem around the same signature-detection architecture.
The core detection capability is organized into four buckets. First, credentials: API keys, tokens and service accounts for AWS, Azure, GCP, Google API, Slack itself (both keys and webhooks), Twitter, Facebook and GitHub, plus generic private keys, access tokens, bearer tokens, client secrets and private tokens. Second, files: certificate files, potentially interesting or sensitive attachments such as .docm, .xlsm and .zip archives, executables, keychain files, and config files for popular services including Terraform, Jenkins and OpenVPN. Third, personal data: leaked passwords, passport numbers, dates of birth, social security numbers and national insurance numbers. Fourth, financial data such as PayPal Braintree tokens, bank card details, IBAN and CUSIP numbers. That breadth is what makes it a hygiene tool as much as an enumeration tool.
Detection is driven by custom YAML signatures pulled at runtime from the central PaperMtn/watchman-signatures repository, and the tool automatically refreshes its signature base on each run so it stays current without a manual update step. This is the same model used across the Watchman family, which means signature quality is community-maintained and inspectable — you can read exactly what a given rule matches, and you can disable noisy ones. Suppression is handled cleanly: add signature IDs to the disabled_signatures section of the watchman.conf YAML file in your home directory, with IDs discoverable in the individual YAML files upstream. This matters in practice because generic rules like tokens_generic_bearer_tokens tend to fire on innocuous text in busy workspaces.
Time-bounded searching is the feature that turns slack-watchman from a one-off auditor into a continuous monitor. The --timeframe flag accepts d for 24 hours, w for 7 days, m for 30 days, or a for all time, and the README's suggested pattern is a single all-time deep scan followed by regular scheduled runs against a short window. Because every run only returns results inside the chosen timeframe, incremental deltas become trivially diffable, and JSON output can be appended to a log file for trend analysis. It is a simple design, but it is the difference between a scanner and a monitoring program.
Beyond secrets, the enumeration side maps the workspace itself. The --users flag enumerates all users and all admins and writes them to .csv in the working directory, while --channels does the same for conversations — including externally shared ones and any conversation containing a Slack Canvas, which the author notes often holds sensitive or important information. It also surfaces workspace authentication options. For an authorized assessor this is reconnaissance-grade context on collaboration sprawl; for a blue team it is an asset inventory of external sharing exposure they probably do not have anywhere else.
The --probe mode is the most operationally interesting corner of the tool. Run with slack-watchman --probe against a workspace domain, it performs an unauthenticated enumeration that returns the workspace name and ID, approved account-creation domains, configured OAuth providers, SSO status, and whether two-factor authentication is required. This is passive, publicly reachable information, but it is exactly the kind of external footprinting data an attacker would pull manually — running it against your own domain tells you what your authentication posture advertises to the world. Note the framing: this is reconnaissance of configuration metadata, not exploitation, and it belongs in external attack-surface reviews of assets you own.
Authentication supports two paths. The primary one is a Slack app OAuth user token with a defined set of user token scopes: channels:read, files:read, groups:read, im:read, links:read, mpim:read, remote_files:read, search:read, team:read, users:read and users:read.email. A ready-made app manifest ships in docs/app_manifest.json to speed up app creation. The README's operational advice here is worth repeating: user tokens act on behalf of the authorizing user, so create and authorize the app with a service account, or the scanner will have visibility into your private conversations. The alternative is cookie authentication using the browser d cookie plus the workspace URL via the --cookie flag, with the README linking to the author's writeup on retrieving Slack cookies.
Credential handling is layered sensibly. The tool first checks the environment variables SLACK_WATCHMAN_TOKEN, SLACK_WATCHMAN_COOKIE and SLACK_WATCHMAN_URL, then falls back to the watchman.conf YAML file in the home directory, with an example in docs/example.conf. The cookie and URL values are optional and only needed for cookie auth. The Docker path fits this model well: docker pull papermountain/slack-watchman:latest and then run with --env-file .env so secrets never touch the image or shell history. For local installation, pipx install slack-watchman is the recommended route, giving an isolated environment and a global slack-watchman command; python3 -m pip install slack-watchman works as a plain alternative.
Output is deliberately dual-mode. Terminal-friendly stdout is the default and is designed for human reading, while --output json produces structured output the README explicitly targets at SIEM ingestion, redirectable with something like slack-watchman --timeframe a --all --output json >> slack_watchman_log.json. A --verbose flag adds more fields to JSON at the cost of size, and --debug enables debug-level logging for troubleshooting. For a blue team wiring this into a scheduled pipeline with alerting on new matches, the JSON mode plus short timeframes is the intended composition.
There are a few watch-items worth flagging before deploying. Cookie-based auth effectively reuses an interactive user session and will be attributed to that user in Slack's logs, so the service-account token path is the defensible choice for standing scans. The broad read scopes the app requires — particularly search:read and files:read — make the scanner's own Slack app a sensitive asset that should itself be monitored and least-privileged. And because signatures auto-update at runtime from an upstream repository, pinned environments may want to audit what changed when detection behavior shifts.
From a defensive telemetry perspective, everything slack-watchman does transits the official Slack Web API under a token or cookie, so it leaves a clean audit trail in Slack admin and app logs rather than scraping web UIs. Defenders watching for misuse of this class of tool should alert on newly installed apps requesting that scope combination, and on anomalous search volume from service accounts. Used as intended — against workspaces you own or are contracted to assess — it is one of the more complete answers to a genuinely common problem: Slack as an unmanaged secrets store.
PaperMtn/slack-watchman.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.