# 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": {
        "active-directory-login": "Active Directory Login",
        "aws-id": "AWS API Key",
        "azure-id": "Azure Login Certificate and Config",
        "cloned-css": "CSS Cloned Site",
        "cloned-web": "Cloned Website",
        "dns": "DNS",
        "doc-msexcel": "MS Excel Document",
        "doc-msword": "MS Word Document",
        "fast-redirect": "Fast Redirect",
        "http": "Web Bug",
        "msexcel-macro": "MS Excel Macro Document",
        "msword-macro": "MS Word Macro Document",
        "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

    # 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. Please check "List Factory Tokens" for available Canarytoken kind values.

    Optional Parameters

    flock_id string
    Defaults to: flock_id of factory
    A valid flock_id (defaults to the flock_id of the token factory)
    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)
    expected_referrer string
    Expected domain to check against (required when creating cloned-css tokens)
    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)
    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)
    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).
    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 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 the 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
        flock_id string
        A valid flock_id
        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 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

            # List Canarytoken Factory Auth Strings

            GET /api/v1/canarytoken/list_factories

            List all Factory auth strings for the Canarytoken Factory endpoint.

            Required Parameters

            auth_token string
            A valid auth token

            Response

            A JSON structure with a list of factory auth strings.

            Example

              Response
              {
                "factories": [
                  {
                    "factory_auth": "<Factory Auth String>",
                    "flock_id": "flock:default",
                    "memo": "Example Memo"
                  },
                  {
                    "factory_auth": "<Factory Auth String 2>",
                    "flock_id": "flock:default",
                    "memo": "Example Memo 2"
                  }
                ],
                "result": "success"
              }
              
              1
              2
              3
              4
              5
              6
              7
              8
              9
              10
              11
              12
              13
              14
              15