# Actions

These are a collection of endpoints that allow you to mint new, interact with, and view your existing Canarytokens.

# 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

    # Create Canarytoken

    POST /api/v1/canarytoken/create

    Create a new Canarytoken.

    Required Parameters

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

    Optional Parameters

    flock_id string
    Defaults to: 'flock:default'
    A valid flock_id (defaults to the Default Flock)
    web_image string
    An image file for use with web-image tokens (request must be multipart/form-data encoded if parameter is present, required when using web-image)
    cloned_web string
    Domain to check against (required when creating cloned-web tokens)
    s3_source_bucket string
    S3 bucket to monitor for access (required when creating aws-s3 tokens)
    s3_log_bucket string
    S3 bucket where logs will be stored (required when creating aws-s3 tokens)
    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)
    browser_scanner_enabled boolean
    Defaults to: true
    Enables a Javascript scanner to retrieve more information (only valid with 'http' Canarytokens)
    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)
    exe string
    The Windows executable that you would like tokened (required when creating signed-exe 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
    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'
    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)
    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).

    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