# Actions

# List Kinds of Canarytokens

TIP

The values returned by this Canarytokens API correspond to the kind parameter used to create Canarytokens. As an example, if you wanted to create a Cloned Web Canarytoken, you would check the response to this Canarytokens API and use cloned-web to define the Canarytoken type you wish to create.

GET /api/v1/canarytokens/list

Lists the available Canarytokens on your Canary Console.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator and Canarytokens information.

Example

    Response
    {
      "canarytokens": {
        "active-directory-login": "Active Directory Login",
        "autoreg-google-docs": "Google Doc",
        "autoreg-google-sheets": "Google Sheet",
        "aws-id": "AWS API Key",
        "aws-s3": "AWS S3 Bucket",
        "cloned-web": "Cloned Website",
        "dns": "DNS",
        "doc-msexcel": "MS Excel Document",
        "doc-msword": "MS Word Document",
        "fast-redirect": "Fast Redirect",
        "gmail": "Gmail",
        "google-docs": "Google Doc",
        "google-sheets": "Google Sheet",
        "googledocs_factorydoc": "Document Factory",
        "googlesheets_factorydoc": "Document Factory",
        "http": "Web Bug",
        "msexcel-macro": "MS Excel Macro Document",
        "msword-macro": "MS Word Macro Document",
        "office365mail": "Office 365 Mail Bug",
        "pdf-acrobat-reader": "Acrobat PDF",
        "qr-code": "QR Code",
        "sensitive-cmd": "Sensitive Command",
        "signed-exe": "Custom Exe/Binary",
        "slack-api": "Slack API Key",
        "slow-redirect": "Slow Redirect",
        "web-image": "Custom Web Image",
        "windows-dir": "Windows Folder",
        "wireguard": "WireGuard VPN"
      },
      "result": "success"
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33

    # Fetch all Canarytokens

    GET /api/v1/canarytokens/fetch

    Fetches all Canarytokens on your Canary Console.

    Required Parameters

    auth_token string
    A valid auth token

    Response

    A JSON structure with result indicator and Canarytokens information.

    Example

      Response
      {
        "tokens": {
            {
              "browser_scanner_enabled": "True",
              "canarytoken": "<token_code>",
              "created": "1685958255.606980'",
              "created_printable": "2023-06-05 09:44:15 (UTC)'",
              "enabled": "True",
              "flock_id": "flock:default'",
              "hostname": "<token_hostname>",
              "key": "<token_key>",
              "kind": "http'",
              "memo": "desktop",
              "node_id": "<token_node_id>",
              "triggered_count": "0",
              "updated_id": "1",
              "url": "<token_url>"
            },
            {
              "canarytoken": "<token_code>",
              "created": "1688122821.384507",
              "created_printable": "2023-06-30 11:00:21 (UTC)",
              "enabled": "True",
              "flock_id": "flock:default",
              "hostname": "<token_hostname>",
              "key": "<token_key>",
              "kind": "dns",
              "memo": "mail inbox",
              "node_id": "<token_node_id>",
              "triggered_count": "0",
              "updated_id": "2",
              "url": "<token_url>"
            }
        },
        "result": "success"
      }
      
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36

      # Create Canarytoken

      POST /api/v1/canarytoken/create

      Create a new Canarytoken.

      Required Parameters

      auth_token string
      A valid auth token
      kind string
      Specifies the type of Canarytoken. Please check "List Canarytokens" for available Canarytoken kind values.
      memo string
      A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.

      Optional Parameters

      aws_access_key string
      AWS Secret Access Key (required if automating creation of AWS S3 token)
      aws_region string
      AWS region (required if automating creation of AWS S3 token)
      azure_id_cert_file_name string
      Azure ID config will use this as the file path to the certificate (required when creating Azure ID tokens).
      browser_redirect_url string
      Browser redirect URL is the URL you want your Canarytoken server to redirect attackers to after they have triggered your Canarytoken token (required when creating fast-redirect and slow-redirect tokens)
      browser_scanner_enabled boolean
      Defaults to: true
      Enables a Javascript scanner to retrieve more information (only valid with 'http' Canarytokens)
      cloned_web string
      Domain to check against (required when creating cloned-web tokens)
      exe string
      The Windows executable that you would like tokened (required when creating signed-exe tokens)
      doc file
      Upload MS Word Document to canarytoken; optionally used with MS Word Document (doc-msword) token. With curl use the following flag -F 'doc=@upload-me.docx; type=application/vnd.openxmlformats-officedocument.wordprocessingml.document'
      flock_id string
      Defaults to: 'flock:default'
      A valid flock_id (defaults to the Default Flock)
      pdf file
      Upload PDF file to canarytoken; optionally used with Adobe PDF canarytoken (pdf-acrobat-reader). With curl use the following flag -F pdf=@upload-me.pdf; type=application/pdf
      process_name string
      Name of the process you want to monitor (required when creating sensitive-cmd tokens)
      s3_log_bucket string
      S3 bucket where logs will be stored (required when creating aws-s3 tokens)
      s3_source_bucket string
      S3 bucket to monitor for access (required when creating aws-s3 tokens)
      web_image file
      Upload an Image file (jpeg or png) that will be displayed on the Canarytokens URL (required when creating web-image tokens) With curl use the following flag: -F 'web_image=@upload-me.png; type=image/png' for png files -F 'web_image=@upload-me.jpg; type=image/jpeg' for jpeg files
      tokened_usernames string
      A comma separated list of Active Directory usernames to token (required when creating active-directory-login tokens)

      Response

      A JSON structure with the created Canarytoken information.

      Example

        Response
        {
          "canarytoken": {
            "browser_scanner_enabled": true,
            "canarytoken": "<token_code>",
            "created": "1586161315.087693",
            "created_printable": "2020-04-06 08:21:55 (UTC)",
            "enabled": true,
            "flock_id": "flock:default",
            "hostname": "<token_hostname>",
            "key": "<token_key>",
            "kind": "http",
            "memo": "Example Memo",
            "triggered_count": 0,
            "updated_id": 7,
            "url": "<token_url>"
          },
          "result": "success"
        }
        
        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18

        # Delete Apeeper Canarytoken Factory

        POST /api/v1/apeeperfactory/delete

        Delete an Apeeper Canarytoken factory.

        Required Parameters

        auth_token string
        A valid auth token
        hash string
        A valid ApeeperFactory hash

        Response

        A JSON structure with result indicator.

        # Delete Canarytoken

        POST /api/v1/canarytoken/delete

        Delete a Canarytoken. You'll need to delete all incidents on a token before you can delete the token itself. If there are still incidents attached to the token, you can specify `clear_incidents=true` to delete them all.

        Required Parameters

        auth_token string
        A valid auth token
        canarytoken string
        A valid Canarytoken

        Optional Parameters

        clear_incidents boolean
        Delete associated incidents

        Response

        A JSON structure with result indicator.

        Example

          Response
          {
            "result": "success"
          }
          
          1
          2
          3

          # Bulk Delete Canarytokens

          POST /api/v1/canarytokens/delete

          Bulk delete Canarytokens that match the specified criterion. You'll need to delete all incidents on the matching tokens before you can delete the tokens, otherwise no tokens will be deleted and an error returned.

          Required Parameters

          auth_token string
          A valid auth token
          domains string
          A comma separated list of custom domains from which all tokens should be deleted.

          Response

          A JSON structure with result indicator.

          Example

            Response
            {
              "result": "success",
              "deleted_count": 1
            }
            
            1
            2
            3
            4

            # Disable Canarytoken

            POST /api/v1/canarytoken/disable

            Disable a Canarytoken.

            Required Parameters

            auth_token string
            A valid auth token
            canarytoken string
            A valid Canarytoken

            Response

            A JSON structure with result indicator.

            Example

              Response
              {
                "result": "success"
              }
              
              1
              2
              3

              # Download Canarytoken

              GET /api/v1/canarytoken/download

              Download the generated file (if one exists) for the supplied Canarytoken.

              Required Parameters

              auth_token string
              A valid auth token
              canarytoken string
              An identifier for a Canarytoken that supports downloadable files

              Response

              A file if the Canarytoken supports file generation, otherwise an error.

              Example

                Response
                $ ls -l
                -rw-r--r--  1 user  thinkst  5095 Apr  7 12:29 <filename>
                
                1
                2

                # Enable Canarytoken

                POST /api/v1/canarytoken/enable

                Enable a disabled Canarytoken.

                Required Parameters

                auth_token string
                A valid auth token
                canarytoken string
                A valid Canarytoken

                Response

                A JSON structure with result indicator.

                Example

                  Response
                  {
                    "result": "success"
                  }
                  
                  1
                  2
                  3

                  # Fetch a Canarytoken

                  GET /api/v1/canarytoken/fetch

                  Fetch information about a specific Canarytoken.

                  Required Parameters

                  auth_token string
                  A valid auth token
                  canarytoken string
                  A valid Canarytoken

                  Response

                  A JSON structure with the Canarytoken.

                  Example

                    Response
                    {
                      "result": "success",
                      "token": {
                        "canarytoken": "<token_code>",
                        "created": "1585947523.255526",
                        "created_printable": "2020-04-03 20:58:43 (UTC)",
                        "enabled": true,
                        "flock_id": "flock:default",
                        "hostname": "<token_hostname>",
                        "key": "<token_key>",
                        "kind": "dns",
                        "memo": "Example Memo",
                        "triggered_count": 0,
                        "updated_id": 4,
                        "url": "<token_url>"
                      }
                    }
                    
                    1
                    2
                    3
                    4
                    5
                    6
                    7
                    8
                    9
                    10
                    11
                    12
                    13
                    14
                    15
                    16
                    17

                    # Remove AWS S3 Canarytoken

                    POST /api/v1/canarytoken/remove/s3

                    Remove an AWS S3 Canarytoken from your Amazon console.

                    Required Parameters

                    auth_token string
                    A valid auth token
                    canarytoken string
                    A valid Canarytoken
                    aws_access_key string
                    AWS Access Key ID (this is not stored on the Console and is only used for the duration of the operation)
                    aws_secret_key string
                    AWS Secret Access Key (this is not stored on the Console and is only used for the duration of the operation)
                    aws_region string
                    AWS Region where the token is located

                    Optional Parameters

                    delete_buckets boolean
                    Defaults to: false
                    Boolean indicating if buckets must be deleted
                    s3_source_bucket string
                    Name of the S3 bucket which was being monitored (required if delete_buckets is true)

                    Response

                    A JSON structure with result indicator.

                    # Update Canarytoken Memo

                    POST /api/v1/canarytoken/update

                    Update the memo of a Canarytoken.

                    Required Parameters

                    auth_token string
                    A valid auth token
                    canarytoken string
                    A valid Canarytoken
                    memo string
                    A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.

                    Response

                    A JSON structure with result indicator.

                    Example

                      Response
                      {
                        "result": "success",
                        "token": {
                          "canarytoken": "<token_code>",
                          "created": "1585947523.255526",
                          "created_printable": "2020-04-03 20:58:43 (UTC)",
                          "enabled": true,
                          "flock_id": "flock:default",
                          "hostname": "<token_hostname>",
                          "key": "<token_key>",
                          "kind": "dns",
                          "memo": "Updated Example Memo",
                          "triggered_count": 0,
                          "updated_id": 4,
                          "url": "<token_url>"
                        }
                      }
                      
                      1
                      2
                      3
                      4
                      5
                      6
                      7
                      8
                      9
                      10
                      11
                      12
                      13
                      14
                      15
                      16
                      17

                      # Update Canarytoken Redirect URL

                      POST /api/v1/canarytoken/update/redirect_url

                      Update the redirect URL of a Canarytoken that supports redirects.

                      Required Parameters

                      auth_token string
                      A valid auth token
                      canarytoken string
                      A valid Canarytoken that support redirects (e.g. slow redirect token or QR code token)
                      redirect_url string
                      A valid url that the user should be redirected to after opening the Canarytoken

                      Response

                      A JSON structure with result indicator.

                      Example

                        Response
                        {
                          "result": "success",
                        }
                        
                        1
                        2
                        3