## 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.

```
{
  "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
  }
}
```