# Slack Chatops

## Purpose

This document is intended for both internal teams and customers. It explains how to set up and use the Slack ChatOps integration in Dropzone, including:

* Technical setup steps
* Authentication flow
* Command usage
* Placement and access guidance

***

## 1. Overview

The Slack ChatOps feature enables users to perform investigation management actions directly from Slack, such as:

* Approving investigations
* Reopening investigations
* Changing investigation outcomes

### v0 (Beta) Slash Commands

* `/dzapprove [INVESTIGATION_ID]`
* `/dzreopen [INVESTIGATION_ID]`
* `/dzoutcome [INVESTIGATION_ID] [OUTCOME] [NOTES] [--learning_flag]`
* `/dzhelp`

***

## 2. Prerequisites

Before setting up ChatOps:

* You must have **Admin access** to:
  * The Dropzone tenant
  * The organization’s Slack workspace
* Users must have logged into the Dropzone tenant at least once (required for authentication matching).
* The Slack app must include the required bot scopes (see manifest below).

***

## 3. Setup Instructions

### Step 1 – Create a Slack App

1. Go to:\
   `https://api.slack.com/apps`
2. Click **Create New App**.
3. Choose **From Manifest**.
4. Paste the JSON manifest (provided at the end of this document).
5. Replace `<TENANT>` in the manifest with your Dropzone tenant hostname.

This automatically configures:

* Slash commands
* Bot scopes

***

### Step 2 – Gather Credentials

After creating and installing the Slack app, collect:

* **Signing Secret**
  * Found under **Basic Information** in Slack.
* **Bot Token**
  * Found under **OAuth & Permissions** after installing the app.

***

### Step 3 – Add Credentials to Dropzone

Within your Dropzone tenant:

1. Navigate to **System Info**.
2. Enter:
   * **Signing Secret** → Slack Signing Secret
   * **Bot Token** → Slack Bot Token

> Note: In future versions, this configuration will likely move to the Integrations page under a dedicated Slack ChatOps section.

***

## 4. Authentication Details

1. Slack sends the slash command request to the Dropzone endpoint.
2. The Dropzone backend verifies the request using the **Signing Secret**.
3. If the Signing Secret is incorrect:
   * The request is rejected.
   * The user receives an error from Slack’s built-in Slackbot (not the Dropzone bot).
4. If verification succeeds:
   * Dropzone matches the Slack user’s email address to an existing Dropzone tenant user.
   * The user must have previously logged into the tenant.
5. If no user match is found:
   * The command fails with an authentication error.

***

## 5. Using Slash Commands

| Command      | Description                                         | Example                                                            |
| ------------ | --------------------------------------------------- | ------------------------------------------------------------------ |
| `/dzapprove` | Approve an investigation by ID                      | `/dzapprove 1012`                                                  |
| `/dzreopen`  | Reopen a previously closed investigation            | `/dzreopen 1012`                                                   |
| `/dzoutcome` | Change outcome with note and optional learning flag | `/dzoutcome 1012 malicious Confirmed phishing attempt. --no-learn` |
| `/dzhelp`    | Display usage information                           | `/dzhelp`                                                          |

***

## 6. Behavior and Visibility

* Successful commands post a confirmation message visible to everyone in the channel.
* Progress messages and usage tips are **ephemeral** (visible only to the user).
* Commands cannot currently be executed inside Slack threads.

***

## 7. Best Practices

* Include slash command usage tips in your default Slack response templates.
* Limit Slack channel access to approved users who are logged into Dropzone.
* Only users with **Member** or **Admin** roles can execute slash commands.
* Use the manifest copy-paste flow to minimize YAML/JSON formatting errors.

***

## 8. Known Limitations

* Cannot trigger commands via emoji reactions (planned for v2).
* Cannot execute commands in Slack threads (Slack platform limitation).

***

## JSON Manifest

Replace `<TENANT>` with your Dropzone tenant hostname before pasting into Slack.

```json
{
  "display_information": {
    "name": "DropzoneAI-ChatOps",
    "description": "Manage investigations via Slack",
    "background_color": "#000000"
  },
  "features": {
    "bot_user": {
      "display_name": "DropzoneAI-ChatOps",
      "always_online": true
    },
    "slash_commands": [
      {
        "command": "/dzapprove",
        "url": "https://<TENANT>.dropzone.app/app/api/chatops/slack/approve",
        "description": "Approve an investigation",
        "usage_hint": "[id]",
        "should_escape": false
      },
      {
        "command": "/dzreopen",
        "url": "https://<TENANT>.dropzone.app/app/api/chatops/slack/reopen",
        "description": "Reopen an investigation",
        "usage_hint": "[id]",
        "should_escape": false
      },
      {
        "command": "/dzoutcome",
        "url": "https://<TENANT>.dropzone.app/app/api/chatops/slack/outcome",
        "description": "Change an investigation outcome",
        "usage_hint": "[id] [outcome] [note] [optional: --no-learn]",
        "should_escape": false
      },
      {
        "command": "/dzhelp",
        "url": "https://<TENANT>.dropzone.app/app/api/chatops/slack/help",
        "description": "Usage information for Dropzone AI slash commands",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": ["chat:write", "commands", "users:read", "users:read.email"]
    }
  },
  "settings": {
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dropzone.ai/integrations/tools/slack-chatops.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.