Internal Fetch¶

The internal fetch endpoint enables retrieving server public keys and certificates (SSH/RDP) for establishing secure connections to target servers. This endpoint is used to fetch cryptographic material from remote servers for authentication and encryption purposes.

Warning

The endpoints described in this section belong to the /internal API group and may change without prior notice. These interfaces are intended for internal use and are not guaranteed to be stable between releases. For more details refer to the API BETA Endpoints section.

Data Structures¶

FetchModel¶

Attribute

Type

Required

Description

protocol

string

yes

Connection protocol. Immutable. Allowed values: http, mysql, pgsql, rdp, ssh, telnet, tls, tn3270, tn5250, vnc. Case-insensitive. Filterable.

address

string

yes

Address to connect to. Filterable.

port

number

yes

Port to connect to. Value format: port. Filterable.

bindip

string

IP address to bind to when connecting. Filterable.

servername

string

Server name for SNI. Requires protocol to be one of: http, mysql, pgsql, rdp, telnet, tls, tn3270, tn5250, vnc. Filterable.

rdp_secproto

string

RDP security protocol. Immutable. Default value: nla. Allowed values: nla, std, tls. Required when protocol is rdp. Filterable.

Retrieve Available Attributes of the FetchModel¶

Request

Method

GET

Path

/api/v2/objspec/fetch

GET /api/v2/objspec/fetch

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.31.138.59/api/v2/objspec/fetch'

Fetch SSH Server Public Key¶

Request

Method

POST

Path

/api/v2/internal/fetch

Headers

Content-Type: application/json

Body

FetchModel

POST /api/v2/internal/fetch

Example Request - SSH

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"protocol": "ssh", "address": "10.0.0.1", "port": 22}' \
  'https://10.31.138.59/api/v2/internal/fetch'

Response - SSH

{
    "result": "success",
    "ssh_public_key": {
        "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGvHcVf1Ii7m5p2zoW5JjlPw0dwJogykoMYmW80TMGwa",
        "fingerprint_sha1": "SHA1:30:c6:e3:08:28:61:61:d7:97:ab:92:05:1f:ea:51:38:ec:ab:01:39",
        "fingerprint_sha256": "SHA256:hJY17iobERovVViFUGo9bGrcT3f8OyiBtED49A4z41U"
    }
}

Fetch RDP Server Certificate¶

Request

Method

POST

Path

/api/v2/internal/fetch

Headers

Content-Type: application/json

Body

FetchModel

POST /api/v2/internal/fetch

Example Request - RDP with TLS

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"protocol": "rdp", "address": "10.0.0.2", "port": 3389, "rdp_secproto": "tls"}' \
  'https://10.31.138.59/api/v2/internal/fetch'

Response - RDP with TLS

{
    "result": "success",
    "tls_certificate": {
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKn...\n-----END CERTIFICATE-----",
        "fingerprint_sha1": "SHA1:a5:b6:c7:d8:e9:f0:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee",
        "fingerprint_sha256": "SHA256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
        "subject": "CN=rdp.example.com",
        "issuer": "CN=rdp.example.com",
        "valid_from": "2024-01-01T00:00:00Z",
        "valid_to": "2025-01-01T00:00:00Z"
    }
}

Example Request - RDP Standard

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"protocol": "rdp", "address": "10.0.0.3", "port": 3389, "rdp_secproto": "std"}' \
  'https://10.31.138.59/api/v2/internal/fetch'

Response - RDP Standard

{
    "result": "success",
    "rdp_public_key": {
        "public_key": "308201...base64_encoded_key...",
        "fingerprint_sha1": "SHA1:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44",
        "fingerprint_sha256": "SHA256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678"
    }
}

Fetch and Store Server Keys/Certificates¶

This example demonstrates how to use batch operations to fetch SSH/RDP server public keys or certificates and store them in server objects.

Fetch SSH Key and Update Server¶

The following batch operation fetches an SSH public key from a remote server and updates the corresponding server object:

Example Request - Fetch and Store SSH Key

{
  "atomic": true,
  "requests": {
    "fetch_ssh_key": {
      "method": "POST",
      "endpoint": "/internal/fetch",
      "data": {
        "protocol": "ssh",
        "address": "192.168.1.100",
        "port": 22
      }
    },
    "update_server": {
      "method": "PATCH",
      "endpoint": "/server/{server_id}",
      "data": {
        "ssh_public_key": "{responses.fetch_ssh_key.ssh_public_key.public_key}"
      }
    }
  }
}

Response

{
    "result": "success",
    "responses": {
        "fetch_ssh_key": {
            "result": "success",
            "status-code": 200,
            "ssh_public_key": {
                "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGvHcVf1Ii7m5p2zoW5JjlPw0dwJogykoMYmW80TMGwa",
                "fingerprint_sha1": "SHA1:30:c6:e3:08:28:61:61:d7:97:ab:92:05:1f:ea:51:38:ec:ab:01:39",
                "fingerprint_sha256": "SHA256:hJY17iobERovVViFUGo9bGrcT3f8OyiBtED49A4z41U"
            }
        },
        "update_server": {
            "result": "success",
            "status-code": 200
        }
    }
}

Fetch RDP Certificate and Update Server¶

For RDP servers with TLS security, the batch operation fetches the TLS certificate:

Example Request - Fetch and Store RDP Certificate

{
  "atomic": true,
  "variables": {
    "server_address": "192.168.1.200",
    "server_port": 3389,
    "server_id": "{server_id}"
  },
  "requests": {
    "fetch_rdp_cert": {
      "method": "POST",
      "endpoint": "/internal/fetch",
      "data": {
        "protocol": "rdp",
        "address": "{variables.server_address}",
        "port": "{variables.server_port}",
        "rdp_secproto": "tls"
      }
    },
    "update_server": {
      "method": "PATCH",
      "endpoint": "/server/{variables.server_id}",
      "data": {
        "tls_certificate": "{responses.fetch_rdp_cert.tls_certificate.certificate}"
      }
    }
  }
}

Response

{
    "result": "success",
    "responses": {
        "fetch_rdp_cert": {
            "result": "success",
            "status-code": 200,
            "tls_certificate": {
                "certificate": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKn...\n-----END CERTIFICATE-----",
                "fingerprint_sha1": "SHA1:a5:b6:c7:d8:e9:f0:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee",
                "fingerprint_sha256": "SHA256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd"
            }
        },
        "update_server": {
            "result": "success",
            "status-code": 200
        }
    }
}

Batch Fetch Multiple Server Keys¶

This example shows how to fetch and store keys for multiple servers in a single batch operation:

Example Request - Multiple Servers

{
  "atomic": false,
  "requests": {
    "server1_fetch": {
      "method": "POST",
      "endpoint": "/internal/fetch",
      "atomic": false,
      "data": {
        "protocol": "ssh",
        "address": "10.0.0.1",
        "port": 22
      }
    },
    "server1_update": {
      "method": "PATCH",
      "endpoint": "/server/{server_id_1}",
      "atomic": false,
      "data": {
        "ssh_public_key": "{responses.server1_fetch.ssh_public_key.public_key}"
      }
    },
    "server2_fetch": {
      "method": "POST",
      "endpoint": "/internal/fetch",
      "atomic": false,
      "data": {
        "protocol": "rdp",
        "address": "10.0.0.2",
        "port": 3389,
        "rdp_secproto": "tls"
      }
    },
    "server2_update": {
      "method": "PATCH",
      "endpoint": "/server/{server_id_2}",
      "atomic": false,
      "data": {
        "tls_certificate": "{responses.server2_fetch.tls_certificate.certificate}"
      }
    }
  }
}

Note

  • The /internal/fetch endpoint requires appropriate permissions to access remote servers

  • Set atomic: false for individual requests when processing multiple servers to prevent one failure from blocking all operations

  • The fetched keys/certificates should match the server’s configured protocol

  • For RDP servers, ensure the rdp_secproto parameter matches the server’s security configuration