Add documentation for new breadcrumb functionality

docs/breadcrumbs/mass-deployment.md

@@ -2,10 +2,10 @@
 
 Breadcrumbs are volatile and need slightly more upkeep than Tokens and Canaries themselves. They are relatively short-lived, lasting only until the Canary's settings (or IP) changes. Depending on what was changed, new breadcrumbs may need to be generated and deployed.
 
-To make this easier for you, Breadcrumbs can be mass deployed by making use of read-only Flock API auth keys. This allows you to build them into your automation and deployment scripts.
+To make this easier for you, Breadcrumbs can be mass deployed by making use of breadcrumb-deploy Flock API auth keys that can only be used on Breadcrumb endpoints. This allows you to build them into your automation and deployment scripts.
 
-Read-only Flock API keys can be generated via the "[Flock API Key endpoints](/flocks-settings/flock-auth-token.html)" and setting `auth_token_type` to `read-only`.
+Breadcrumb-deploy Flock API keys can be generated via the "[Flock API Key endpoints](/flocks-settings/flock-auth-token.html)" and setting `auth_token_type` to `breadcrumb-deploy`.
 
 ::: warning
-While read-only Flock API auth keys limit which devices can be viewed to a specific flock, it is recommended that they be disabled after they are used by scripts to deploy breadcrumbs. This can be done via the "[Remove Flock API key](/flocks-settings/flock-auth-token.html#remove-flock-api-key)" endpoint.
+While breadcrumb-deploy Flock API auth keys limit visibility of Canary details to the contents of the chosen Breadcrumb, it is recommended that they be disabled after they are used by scripts to deploy breadcrumbs. This can be done via the "[Remove Flock API key](/flocks-settings/flock-auth-token.html#remove-flock-api-key)" endpoint.
 :::

docs/breadcrumbs/overview.md

@@ -13,12 +13,20 @@ endpoints:
       - name: node_id
         required: true
         type: string
-        description: A valid Canary node_id
+        description: A valid Canary node_id. This field is optional for [Credential Breadcrumb Kinds](/breadcrumbs/overview.html#credential-breadcrumb-kinds).
       - name: kind
         required: true
         type: string
         description: Name of desired breadcrumb type. Please check "[Available Breadcrumb Kinds](/breadcrumbs/overview.html#available-breadcrumb-kinds)"
                      for the different Breadcrumb kind values.
+      - name: mode
+        required: false
+        type: string
+        description: Determines the output mode of the breadcrumb. `text` places the full contents of the breadcrumb into the `crumb` output field and `json` splits the contents into separate fields.
+      - name: reminder
+        required: false
+        type: string
+        description: A reminder that will be included in the alert to let you know where you deployed this breadcrumb. This field is required for [Credential Breadcrumb Kinds](/breadcrumbs/overview.html#credential-breadcrumb-kinds).
     response: JSON structure with output content of the crumb generation.
   breadcrumb_download:
     name: Download Breadcrumb
@@ -33,12 +41,20 @@ endpoints:
       - name: node_id
         required: true
         type: string
-        description: A valid Canary node_id
+        description: A valid Canary node_id. This field is optional for [Credential Breadcrumb Kinds](/breadcrumbs/overview.html#credential-breadcrumb-kinds).
       - name: kind
         required: false
         type: string
         description: Name of desired breadcrumb type. Please check "[Available Breadcrumb Kinds](/breadcrumbs/overview.html#available-breadcrumb-kinds)"
                      for the different Breadcrumb kind values. If not specified, an archive of all possible breadcrumbs will be returned.
+      - name: mode
+        required: false
+        type: string
+        description: Determines the output mode of the breadcrumb. `text` produces a single text file with the contents of the breadcrumb and `zip` produces a zip archive of the contents.
+      - name: reminder
+        required: false
+        type: string
+        description: A reminder that will be included in the alert to let you know where you deployed this breadcrumb. This field is required for [Credential Breadcrumb Kinds](/breadcrumbs/overview.html#credential-breadcrumb-kinds).
     response: Temporary download link or archive of different breadcrumbs.
 ---
 
@@ -58,24 +74,31 @@ The following services and breadcrumb kinds are currently supported:
 </APIEndpoints>
 
 ### Available Breadcrumb Kinds
-| Kind | Service | Description |
-|---|---|---|
-| rdp-profile | RDP | Remote Desktop Profile. This crumb can either be treated like a Canarytoken and left in place somewhere on a host where an attacker might stumble onto it, or it can be imported into Microsoft Remote Desktop as a profile. |
-| ssh-host | SSH | SSH Host Entry. This crumb creates a Host entry for the Canary in this host's SSH config. You can simply run the script in a bash shell and it will place the Host entry at the end of the file. It's advisable to trigger an alert on the bird's ssh service from this host to create an entry in the SSH known_hosts file.|
-| putty-profile | SSH | SSH PuTTY Profile. This crumb creates a session profile for the Canary on the PuTTY SSH client. On a Windows host that runs PuTTY, you can import the session by double clicking the crumb file, or by running `reg import putty-sessions.reg` in PowerShell or `regedit /i putty-sessions.reg` in a terminal. |
-| filezilla-profile | File Transfer (FTP) | FTP FileZilla Profile. This crumb creates a Site Manager entry for the FileZilla FTP client. In FileZilla, select File > Import, and import the crumb. This will make the Canary visible in Site Manager. |
-| winscp-profile | File Transfer (FTP) | WinSCP Profile. This crumb creates a session profile for the Canary on the WinSCP FTP client. On a Windows host that runs WinSCP, you can import the session by double clicking the crumb file, or by running `reg import winscp-sessions.reg` in PowerShell or `regedit /i winscp-sessions.reg` in a terminal. |
-| windows-ftp-shortcut | File Transfer (FTP) | Windows FTP Server Shortcut. This crumb creates a Windows file shortcut to the bird's FTP service. The crumb can be created by dropping the script in the desired location and running it with PowerShell. |
-| windows-smb-shortcut | Windows File Share | Windows SMB Server Shortcut. This crumb creates a Windows file shortcut to the bird's SMB service. The crumb can be created by dropping the script in the desired location and running it with PowerShell. |
-| macos-http-shortcut | Webserver | MacOS HTTP Shortcut. This crumb creates a MacOS web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
-| macos-https-shortcut | Webserver | MacOS HTTPS Shortcut. This crumb creates a MacOS web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
-| windows-http-shortcut | Webserver | Windows HTTP Shortcut. This crumb creates a Windows web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
-| windows-https-shortcut | Webserver | Windows HTTPS Shortcut. This crumb creates a Windows web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
+| Kind | Service | Creates Credentials | Description |
+|---|---|---|---|
+| ssh-key | SSH | Yes | SSH Key. This crumb generates a valid SSH key pair and a sample config entry. We will provide an extra alert if the public key is detected in any future SSH events on your Canary. You can deploy this breadcrumb by placing the public and private key files into a host's `.ssh/` folder, and copying the Host entry into `.ssh/config`.|
+| putty-profile | SSH | No | SSH PuTTY Profile. This crumb creates a session profile for the Canary on the PuTTY SSH client. On a Windows host that runs PuTTY, you can import the session by double clicking the crumb file, or by running `reg import putty-sessions.reg` in PowerShell or `regedit /i putty-sessions.reg` in a terminal. |
+| rdp-profile | RDP | No | Remote Desktop Profile. This crumb can either be treated like a Canarytoken and left in place somewhere on a host where an attacker might stumble onto it, or it can be imported into Microsoft Remote Desktop as a profile. |
+| filezilla-profile | File Transfer (FTP) | No | FTP FileZilla Profile. This crumb creates a Site Manager entry for the FileZilla FTP client. In FileZilla, select File > Import, and import the crumb. This will make the Canary visible in Site Manager. |
+| winscp-profile | File Transfer (FTP) | No | WinSCP Profile. This crumb creates a session profile for the Canary on the WinSCP FTP client. On a Windows host that runs WinSCP, you can import the session by double clicking the crumb file, or by running `reg import winscp-sessions.reg` in PowerShell or `regedit /i winscp-sessions.reg` in a terminal. |
+| windows-ftp-shortcut | File Transfer (FTP) | No | Windows FTP Server Shortcut. This crumb creates a Windows file shortcut to the bird's FTP service. The crumb can be created by dropping the script in the desired location and running it with PowerShell. |
+| windows-smb-shortcut | Windows File Share | No | Windows SMB Server Shortcut. This crumb creates a Windows file shortcut to the bird's SMB service. The crumb can be created by dropping the script in the desired location and running it with PowerShell. |
+| macos-http-shortcut | Webserver | No | MacOS HTTP Shortcut. This crumb creates a MacOS web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
+| macos-https-shortcut | Webserver | No | MacOS HTTPS Shortcut. This crumb creates a MacOS web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
+| windows-http-shortcut | Webserver | No | Windows HTTP Shortcut. This crumb creates a Windows web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
+| windows-https-shortcut | Webserver | No | Windows HTTPS Shortcut. This crumb creates a Windows web page shortcut. The crumb file can simply be dropped somewhere that an attacker might click into it. |
 
 ::: tip
-Remember to make sure that the desired services are enabled and reachable on the Canary, before deploying breadcrumbs. The services can either be enabled on the Console UI, or via the "[device configuration](/bird-management/service-configuration.html)" endpoints.
+Remember to make sure that the desired services are enabled and reachable on the Canary before deploying breadcrumbs. The services can either be enabled on the Console UI, or via the "[device configuration](/bird-management/service-configuration.html)" endpoints.
 :::
 
+### Breadcrumb Credentials
+Certain Breadcrumbs generate and store valid credentials that act as an identifier for the Breadcrumb and make them more appealing to attackers. When creating these Breadcrumbs you must provide a reminder, which will be included in an alert if the credentials are used in an attack on any of your Canaries.
+
+As these Breadcrumb kinds produce static credentials, you can generate them without supplying a `node_id` to create a set of valid credentials which will still alert on use without creating configuration files referencing a specific Canary.
+
+These Breadcrumbs are currently excluded from the archive produced by downloading without a specified kind.
+
 ## Generate Breadcrumb
 
 <APIDetails :endpoint="$page.frontmatter.endpoints.breadcrumb_generate">

docs/flocks-settings/flock-auth-token.md

@@ -13,7 +13,7 @@ endpoints:
       - name: auth_token_type
         required: false
         type: string
-        description: The access level of the key. Either 'read-only', 'canarytoken-deploy', 'analyst', or 'admin'
+        description: The access level of the key. Either 'read-only', 'canarytoken-deploy', 'breadcrumb-deploy', 'analyst', or 'admin'
       - name: flock_id
         required: true
         type: string

docs/incidents/incident-objects.md

@@ -2232,5 +2232,49 @@ Human readable timestamp of the request eg. `2020-01-30 09:56:37 UTC+0000` <br><
                   "WINRMPAYLOAD": "..."
                }
 ```
+:::
+  </div>
 </div>
+
+## SSH Key Breadcrumb Used
+Triggered when the public key from an SSH Key Breadcrumb is used in an attack.
+
+<div class="section-container">
+  <div class="details-content">
+
+::: attribute-details
+
+**KEY**
+The public key used in the attack. <br><br>
+**SERVICE**
+The bird service targeted with the public key. <br><br>
+**USERNAME**
+The username used in the SSH connection attempt. <br><br>
+**reminder**
+The reminder set when the breadcrumb was created. <br><br>
+**timestamp**
+The timestamp of the request eg. `1580378197` <br><br>
+**timestamp_std**
+Human readable timestamp of the request eg. `2020-01-30 09:56:37 UTC+0000` <br><br>
+
+:::
+
+  </div>
+  <div class="example-content">
+
+<br>
+
+::: api-response
+``` json
+<EVENT_DESCRIPTION> = "SSH Key Breadcrumb Used"
+<LOGTYPE> = "29001"
+<REMINDER> = "..."
+<EVENT_DICT> = {
+                  "KEY": "...",
+                  "SERVICE": "...",
+                  "USERNAME": "...",
+               }
+```
+:::
+  </div>
 </div>