# Factory

Sometimes you want to automate the creation of Canarytokens across your fleet. Perhaps you want every EC2 instance to reach out and fetch a token on creation (or startup). The Canary Console API allows for the automation, but it seems a bad idea to use your API key on every host.

The Canarytoken factory gives you a limited use key that is able to create other tokens. You can leave this key on a host knowing that even if an attacker were able to grab it, he'd be able to create new tokens but not remove (or alter) anything else.

# List Canarytokens available via Canarytoken Factory

TIP

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

GET /api/v1/canarytokens/factory/list

Lists the Canarytokens available via your Canarytokens Factory.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator and Canarytokens Factory information.

Example

    Response
    {
      "factory_canarytokens":{
        "aws-id":"Amazon API Key",
        "cloned-web":"Cloned Website",
        "dns":"DNS",
        "doc-msword":"MS Word .docx Document",
        "fast-redirect":"Fast HTTP Redirect",
        "http":"Web",
        "msexcel-macro":"MS Excel .xlsm Document",
        "msword-macro":"MS Word .docm Document",
        "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

    # Create Canarytokens Using Factory

    POST /api/v1/canarytoken/factory/create

    Create Canarytokens using a Canarytokens Factory auth string

    Required Parameters

    factory_auth string
    A valid factory_auth string
    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. Supported classes include http, dns, cloned-web, doc-msword, web-image, windows-dir, pdf-acrobat-reader, msword-macro, msexcel-macro, aws-id, qr-code, fast-redirect, slow-redirect, slack-api

    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)
    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 you want to create an AWS API key linked to certain Name otherwise it is randomly generated.
    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 generated Canarytoken.

    Example

      Response
      {
        "canarytoken": {
          "access_key_id": "<access_key_id>",
          "canarytoken": "<token_code>",
          "created": "1586246956.323499",
          "created_printable": "2020-04-07 08:09:16 (UTC)",
          "enabled": true,
          "factory_auth": "<factory_auth_token>",
          "flock_id": "flock:default",
          "hostname": "<token_hostname>",
          "key": "canarydrop:<key>",
          "kind": "aws-id",
          "memo": "Example Memo",
          "renders": {
            "aws-id": "\n    [default]\n    aws_access_key_id = <aws_access_key>\n    aws_secret_access_key = <aws_secret_access_key>"
          },
          "secret_access_key": "<aws_secret_access_key>",
          "triggered_count": 0,
          "updated_id": 14,
          "url": "<token_url>",
          "username": "<token_user_name>"
        },
        "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

      # Download Canarytoken using Factory Auth String

      GET /api/v1/canarytoken/factory/download

      Download the generated file (if one exists) for the supplied Canarytoken using Factory auth string

      Required Parameters

      factory_auth string
      A valid Canarytoken factory auth string
      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

        # Create Canarytoken Factory Auth String

        POST /api/v1/canarytoken/create_factory

        Create an auth string for the Canarytoken Factory endpoint.

        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

        Optional Parameters

        flock_id string
        Defaults to: 'flock:default'
        A valid flock_id (defaults to the Default Flock)

        Response

        A JSON structure with auth string and Canarytoken factory endpoint.

        Example

          Response
          {
            "factory_auth": "<factory_auth_token>",
            "factory_url": "/api/v1/canarytoken/factory",
            "result": "success"
          }
          
          1
          2
          3
          4
          5

          # Delete Canarytoken Factory Auth String

          DELETE /api/v1/canarytoken/delete_factory

          Delete an auth string for the Canarytoken Factory endpoint.

          Required Parameters

          auth_token string
          A valid auth token
          factory_auth string
          An existing factory auth string

          Response

          A JSON structure with result indicator.

          Example

            Response
            {
              "msg": "TokenFactory auth string deleted",
              "result": "success"
            }
            
            1
            2
            3
            4