Package: slack-discovery-sdk
Python-Slack-Discovery-SDK👋🏼 Welcome to the Python-Slack-Discovery-SDK! This project aims to make using the Slack Discovery APIs easier.🚨 Note: This SDK is only accessible to customer developers with access to the Discovery API (Enterprise accounts) or partners who have been onboarded to the Security and Compliance partner program. To learn more about the Discovery APIs, pleasevisit our help center. 🚨Prerequisites For Using the SDKPython version 3.6 or greaterLatest version of pipA token with discovery scopes (discovery:readand ordiscovery:write)Note: Please see theOAuth guideon how to get this token if you don't already have one.Using the SDKUse pip to install the SDK.pipinstallslack-discovery-sdkOnce you've installed the SDK, you can use the following import statement
to use the methods in the SDK.fromslack_discovery_sdkimportDiscoveryClientNote: use the following command to set your environmental variable to be your token with discovery scopes.exportSLACK_DISCOVERY_SDK_TEST_ENTERPRISE_TOKEN="your-discovery-token-goes-here"To initialize the SDK, you must pass in a token with Discovery Scopes:importosenterprise_token=os.environ["SLACK_DISCOVERY_SDK_TEST_ENTERPRISE_TOKEN"]client=DiscoveryClient(token=enterprise_token)Note: Please see theOAuth guideon how to get this token if you don't already have one.Now, you can use the client to call all of the Slack Discovery SDK methods.
Here is an example of calling thediscovery.enterprise.infoendpoint, and printing the result to the console:enterprise_info=client.discovery_enterprise_info()print(enterprise_info.body)To view the full code using thediscovery.enterprise.infoendpoint, please see the sampleapp.pyfile.To view all of the methods offered by the SDK, please see theclient.py file.👨🏻‍💻 Understanding the Setup Script 👩🏻‍💻In order to speed up the development process, we've provided you with a script calledset_env_vars.shin the scripts folder to automate a few things needed to run the SDK.
The script accomplishes the following things using the following code:Prints your current Python version (you will need Python version 3.6 or greater for this SDK)python3--versionSets your Virtual Environmentpython3-mvenv.venvsource.venv/bin/activateEnsures pip is updated to the latest versionpipinstall-UpipInstalls required packages and dependenciespipinstall-e".[testing]"👨🏻‍💻 Adding Env Variables to Setup Script 👩🏻‍💻🚨 At this point, you'll need to edit thescripts/set_env_vars.shscript in an editor of your choice 🚨Edit the line below, and add in your token withdiscovery:readanddiscovery:writescopes.exportSLACK_DISCOVERY_SDK_TEST_ENTERPRISE_TOKEN='xoxp-**********'Now, if you want to run the examples in theslack_discovery_sdk/examplesdirectory, you'll need to set
a few other additional environmental variables.Edit the lines below, and add in the appropriate tokens:# A normal bot token with many scopesexportSLACK_DISCOVERY_SDK_TEST_BOT_TOKEN="xoxb-*******"# A test workspace ID in the Enterprise Org# SLACK_DISCOVERY_SDK_TEST_BOT_TOKEN should have the access to this workspaceexportSLACK_DISCOVERY_SDK_TEST_TEAM_ID='T0********'# A test channel ID in the Enterprise OrgexportSLACK_DISCOVERY_SDK_TEST_CHANNEL_ID='C0******'# Used for audit logs API (examples/audit_logs_pattern.py)# A User Token with auditlogs:read scopes,exportSLACK_DISCOVERY_SDK_TEST_USER_AUDIT_TOKEN='xoxp-*************'🚨 Once you are done adding in your tokens, save the file 🚨Note: before you can run this script, you will need to mark the file as executable with the following command:chmod+xscripts/set_env_vars.sh👩🏻‍💻 Run the Setup Script 👨🏻‍💻Use the following command to run the script:Note: you must use thesourcecommand so that the env variables are set properly.source./scripts/set_env_vars.shIf all went well, you should see the following output:YourcurrentPythonversionis:Python3.10.0
Settingyourvirtualenv.
Success.
SettingyourSLACK_DISCOVERY_SDK_TEST_ENTERPRISE_TOKEN.
Success.
SettingyourSLACK_DISCOVERY_SDK_TEST_BOT_TOKEN(thisisneededifyouwanttoruntheexamples).
Success.
SettingyourSLACK_DISCOVERY_SDK_TEST_TEAM_ID(thisisneededifyouwanttoruntheexamples).
Success.
SettingyourSLACK_DISCOVERY_SDK_TEST_CHANNEL_ID(thisisneededifyouwanttoruntheexamples).
Success.
SettingyourSLACK_DISCOVERY_SDK_TEST_USER_AUDIT_TOKEN(thisisneededifyouwanttoruntheexamples).
Success.Running the ExamplesUse the following command to run a script which calls thediscovery.enterprise.infoendpoint. This endpoint returns basic information about the Enterprise Grid org where the app is installed, including all workspaces (teams).python3slack_discovery_sdk/examples/get_enterprise_info.pyYou should see a response similar to the following (note the result below has been truncated for readability):DEBUG:slack_discovery_sdk.base_client:Ratelimitmetrics:DEBUG:slack_discovery_sdk.base_client:Receivedthefollowingresponse-status:200,headers:{'date':'Wed, 13 Oct 2021 22:09:57 GMT',...,body:{"ok":true,"enterprise":{"id":"T027****D2R","name":"Enterprise-****-Sandbox","domain":"test-****","email_domain":"","icon":...,"image_default":true},"is_verified":false,"teams":[{"id":"****","name":"Enterprise-****-Sandbox","domain":"test-****","email_domain":"","icon":{"image_102":"https:\/\/a...avatars-teams\/ava_0021-88.png","image_default":true},"is_verified":false,"enterprise_id":"E**","is_enterprise":0,"created":1625594757,"archived":false,"deleted":false,"discoverable":"unlisted"}]}}If you want to run all of the examples at once, you can use therun_all.shscript.Note: before you can run this script, you will need to mark the file as executable with the following command:chmod+xscripts/run_all.shThen, run the script:./scripts/run_all.shThis will run all of the examples in theslack_discovery_sdk/examplesfolder, and
you should see debug output in your terminal once the script has finished running.Continue reading below to learn what each example does:💳DLP_call_pattern.py💳This script involves using the tombstoning capabilities of the Discovery SDK to check for messages that contain sensitive information. If sensitive information is detected by our script (for example a credit card number), the message is tombstoned, and the user is notified that their message is being reviewed.Once you run this script, you should see that one of your
messages in the channel which you set in your env variable (SLACK_DISCOVERY_SDK_TEST_CHANNEL_ID) should have been tombstoned. The message should now sayThis message is being scanned to make sure it complies with your team’s data security policies.🙋🏾‍♀️user_based_eDiscovery_with_edits.py👩🏻‍🏫This script retrieves all of the conversations (channels) and messages a particular user is in. It then outputs those
conversations to a file, and stores them in the following format:YYYY/MM/DD/user_id/channel_id/discovery_conversations.json. If thehas_editsflag is true
for a certain conversation, all edited messages will be found in theeditsfield.👩🏻‍🏫audit_logs_pattern.py👩🏻‍🏫This script will use theAudit Logs APIto find all of the
channels that a particular user has created. As is the
case with theuser_based_eDiscoveryscript, it will only
be useful if you have a paricular user which you want to see details about. This script will output the channel creation events associated with a particular user_id to in the following format:YYYY/MM/DD/user_id/audit_logs/public_channel_created.json.🙋🏾‍♀️user_based_eDiscovery_pattern.py👩🏻‍🏫This is the same as theuser_based_eDiscovery_with_edits.pyscript, except it
doesn't capture edits.ConsiderationsThe SDK and examples are to aid in your development process. Please feel free to use this as a learning exercise, and to build on top of these examples, but the examples shown above are by no means a complete solution.Running testsTo run the unit tests in this repository, creating a Discovery API enabled app is required._metadata:major_version:1minor_version:1display_information:name:discovery-api-testfeatures:bot_user:display_name:discovery-api-testoauth_config:redirect_urls:-https://your-own-domain.ngrok.io/slack/oauth_redirectscopes:user:-discovery:read-discovery:writebot:-channels:manage-channels:read-chat:write-commands-groups:write-im:write-mpim:write-reactions:write-channels:join-files:writesettings:org_deploy_enabled:truesocket_mode_enabled:falsetoken_rotation_enabled:falseAnd then, setting the bot / user tokens in the env variables as below:# Setup your virtual environmentpython--version# make sure if you're using Python 3.6+python-mvenv.venvsource.venv/bin/activate
pipinstall-Upip
pipinstall-e".[testing]"# Set required env variables# 1. An admin user token with discovery:read, discovery:writeexportSLACK_DISCOVERY_SDK_TEST_ENTERPRISE_TOKEN=xoxp-xxx# 2. A normal bot token with many scopesexportSLACK_DISCOVERY_SDK_TEST_BOT_TOKEN=xoxb-xxxx# 3. A test workspace ID in the Enterprise Org#    SLACK_DISCOVERY_SDK_TEST_BOT_TOKEN should have the access to this workspaceexportSLACK_DISCOVERY_SDK_TEST_TEAM_ID=T1234567890# 4. A test channel ID in the Enterprise Org#    SLACK_DISCOVERY_SDK_TEST_BOT_TOKEN should have the access to this channelexportSLACK_DISCOVERY_SDK_TEST_CHANNEL_ID=C1234567890
pytesttests/# You can check logs/pytest.log for trouble shootingFeedbackFor feedback, please usethis feedback form.Issues and TroubleshootingFor issues, please usethis issue form.