# 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
  }
}
```