# 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": {
        "apeeper": "EC2 Meta-data Service", 
        "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

      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

          # 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