# Actions

# List 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 Document",
        "autoreg-google-sheets":"Google Sheet",
        "aws-id":"Amazon API Key",
        "aws-s3":"Amazon S3",
        "cloned-web":"Cloned Website",
        "dns":"DNS",
        "doc-msword":"MS Word .docx Document",
        "fast-redirect":"Fast HTTP Redirect",
        "google-docs":"Google Document",
        "google-sheets":"Google Sheet",
        "googledocs_factorydoc":"Document Factory",
        "googlesheets_factorydoc":"Document Factory",
        "http":"Web",
        "msexcel-macro":"MS Excel .xlsm Document",
        "msword-macro":"MS Word .docm Document",
        "office365mail":"Office 365 email token",
        "pdf-acrobat-reader":"Acrobat Reader PDF Document",
        "qr-code":"QR Code",
        "signed-exe":"Signed Exe",
        "slack-api":"Slack API Key",
        "slow-redirect":"Slow HTTP Redirect",
        "web-image":"Remote Web Image",
        "windows-dir":"Windows Directory Browsing"
      },
      "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

    # 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
    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 (optional when creating aws-s3 tokens)
    s3_log_bucket string
    S3 bucket where logs will be stored (optional 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)
    aws_id_username string
    AWS ID Username is optional if the client wants to create an AWS API key linked to certain NameError otherwise its randomly generated (optional when creating aws-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)
    exe string
    The Windows executable that you would like tokened (required when creating signed-exe tokens)
    web_image string
    Image file (jpeg or png) that will be displayed on the Canarytokens URL (required when creating web-image 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.

      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

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

              GET /api/v1/canarytoken/fetch

              Fetch information about a specific Canarytoken.

              Required Parameters

              auth_token string
              A valid auth token

              Optional Parameters

              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

                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