Twingate の API を調べる機会があったのでメモ。

概要

GraphQLベースの Admin API が公開されています。 Web UI 上の操作は一通り行えるようです。

GitHub上で Python と Javascript 製の CLI も公開されています。若干サポートしている機能の違いが有りました。

Getting Started with the API | Docs | Twingate

どのような情報が取得できるかの例は PostMan Collection が公開されているので、 Postman へ import することで簡単に確認できます。

導入と実行例

各ツールでオプション名が違い若干混乱しますが、基本的には network 名 (URL の https://xxx.twingate.com/ 部分) と API Key を指定することで利用できます。

直接実行(curl)

curl で Connector の Status を取得したいとなったら以下の様な感じで取得できます。

curl コマンド

$ NETWORK=""
$ URL="https://${NETWORK}.twingate.com/api/graphql/"
$ API_KEY =""

$ curl -L -X POST "${URL}" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
--data-raw '{"query":"{\n  connectors(after: null, first:10) {\n    edges {\n      node {\n        id\n        name\n        state\n        lastHeartbeatAt\n\n      }\n    }\n    pageInfo {\n      startCursor\n      hasNextPage\n    }\n  }\n}","variables":{}}'

curl 実行結果

{
  "data": {
    "connectors": {
      "edges": [
        {
          "node": {
            "id": "IDx8US0zIx7nt3uEibDip",
            "name": "example-connector-01",
            "state": "ALIVE",
            "lastHeartbeatAt": "2022-10-09T21:47:18.762481+00:00"
          }
        },
        {
          "node": {
            "id": "IDxpTR7cwIkECA5l9Q9G",
            "name": "example-connector-02",
            "state": "ALIVE",
            "lastHeartbeatAt": "2022-10-09T21:46:57.830308+00:00"
          }
        }
      ],
      "pageInfo": {
        "startCursor": "CURxv85etCrXeEyOShWN6oXm=",
        "hasNextPage": false
      }
    }
  }
}

Twingate-Labs/Twingate-CLI

A Python based Command Line Interface (CLI)

Usage

requests,pandas を使用しているため事前にインストールが必要です。

# 依存パッケージのインストール
$ pip install -U requests pandas

# Usage
$ python tgcli.py -h
usage: tgcli.py [-h] [-v] [-l DEBUGLEVEL] [-s SESSIONNAME]
                [-f OUTPUTFORMAT]
                {auth,device,connector,user,group,resource,network,account,key,policy}
                ...

positional arguments:
  {auth,device,connector,user,group,resource,network,account,key,policy}

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -l DEBUGLEVEL, --log DEBUGLEVEL
                        DEBUG,INFO,WARNING,ERROR
  -s SESSIONNAME, --session SESSIONNAME
                        Session Name
  -f OUTPUTFORMAT, --format OUTPUTFORMAT
                        Output Format <JSON,CSV,DF>

Example

SESSIONNAME オプション未指定の場合、自動生成されます。

$ NETWORK=""
$ API_KEY=""

# Get session name
$ python tgcli.py auth login --tenant ${NETWORK} --apikey ${API_KEY}

#Session Created: OrangeEel

作成した SESSIONNAME を使用して実行します。

$ SESSION=OrangeEel
$ python tgcli.py -s ${SESSION} connector list
[
  [
    {
      "node": {
        "id": "IDx8US0zIx7nt3uEibDi",
        "name": "example-connector-01",
        "state": "ALIVE",
        "lastHeartbeatAt": "2022-10-10T22:49:59.988005+00:00",
        "createdAt": "2022-09-25T03:49:01.543217+00:00",
        "updatedAt": "2022-10-03T07:51:03.236550+00:00",
        "hasStatusNotificationsEnabled": false
      }
    },
    {
      "node": {
        "id": "IDxpTR7cwIkECA5l9Q9G",
        "name": "example-connector-02",
        "state": "ALIVE",
        "lastHeartbeatAt": "2022-10-10T22:50:20.686008+00:00",
        "createdAt": "2022-09-25T04:12:10.726199+00:00",
        "updatedAt": "2022-10-03T07:51:47.279982+00:00",
        "hasStatusNotificationsEnabled": false
      }
    }
  ]
]

Twingate-Labs/tg-cli

A javascript based Command Line Interface (CLI)

Usage

バイナリが公開されています。

# ダウンロードとインストール
$ curl -L 'https://github.com/Twingate-Labs/tg-cli/releases/latest/download/cli_linux_x86_64.zip' -o /usr/local/src/tg-cli.zip
$ unzip /usr/local/src/tg-cli.zip -d /usr/local/bin/
$ chmod +x /usr/local/bin/tg

# Usage
$ tg --help

  Usage:   tg
  Version: CLI Version: 0.0.53 | TwingateApiClient Version: 0.1.0

  Description:

    CLI for Twingate

  Options:

    -h, --help                      - Show this help.
    -V, --version                   - Show the version number for this program.
    -a, --account-name  <string>    - Twingate account name
    -l, --log-level     [logLevel]  - Log level                                  (Default: "INFO", Values: "TRACE", "DEBUG", "INFO", "WARN",
                                                                                 "ERROR", "SEVERE", "FATAL", "QUIET", "SILENT")

  Commands:

    export     - Export from account to various formats
    import     - Import from excel file to a Twingate account
    deploy     - Automatically deploy Twingate Connectors to various clouds and platforms
    resource   - Twingate resources
    group      - Twingate groups
    user       - Twingate users
    network    - Twingate networks
    connector  - Twingate connectors
    device     - Twingate devices
    service    - Twingate services
    policy     - Twingate policies

Example

API Key を都度入力する形です。ファイルに保存して使い回すことができます。

$ NETWORK=""

# 初回実行時に API Key を入力
$ tg --account-name ${NETWORK} connector list
 ? Enter Twingate account: (xxxxx) › xxxxx
 ? Enter API key: › **************************************************************************************************************************************

# API Key を `~.tgkeys` に保存するか否か
 ? Save account and API key to file? › Yes
[INFO]    Configuration file saved.
┌──────────────────────┬───────────────────────┬───────────┬───────────┬─────────────────┬────────┬──────────────────────┐
│ id                   │ name                  │ createdAt │ updatedAt │ lastHeartbeatAt │ state  │ remoteNetworkLabel   │
├──────────────────────┼───────────────────────┼───────────┼───────────┼─────────────────┼────────┼──────────────────────┤
│ IDx8US0zIx7nt3uEibDip │ example-connector-01 │ 9/25/22   │ 10/3/22   │ 10/10/22        │ Online │ example-remote-network │
├──────────────────────┼───────────────────────┼───────────┼───────────┼─────────────────┼────────┼──────────────────────┤
│ IDxpTR7cwIkECA5l9Q9G │ example-connector-02 │ 9/25/22   │ 10/3/22   │ 10/10/22        │ Online │ example-remote-network │
└──────────────────────┴───────────────────────┴───────────┴───────────┴─────────────────┴────────┴──────────────────────┘

API Key の保存を行うと、次回以降は Key の入力を省略できます。

$ file .tgkeys
.tgkeys: data
$ tg --account-name ${NETWORK} connector list --output-format json
[INFO]    Using Twingate account: 'xxxxx'
[{"id":"IDx8US0zIx7nt3uEibDip","name":"example-connector-01","createdAt":"2022-09-25T03:49:01.543Z","updatedAt":"2022-10-03T07:51:03.236Z","lastHeartbeatAt":"2022-10-10T23:09:00.021Z","state":"Online","remoteNetworkLabel":"example-remote-network"},{"id":"IDxpTR7cwIkECA5l9Q9G","name":"example-connector-02","createdAt":"2022-09-25T04:12:10.726Z","updatedAt":"2022-10-03T07:51:47.279Z","lastHeartbeatAt":"2022-10-10T23:09:20.694Z","state":"Online","remoteNetworkLabel":"example-remote-network"}]

export

サブコマンドとして export が用意されており、全情報を JSON や Excel 形式で出力できます。

$ tg export --help

  Usage:   tg export
  Version: CLI Version: 0.0.53 | TwingateApiClient Version: 0.1.0

  Description:

    Export from account to various formats

  Options:

    -h, --help                         - Show this help.
    -a, --account-name     <string>    - Twingate account name
    -l, --log-level        [logLevel]  - Log level                (Default: "INFO")
    -f, --format           [value]     - Export format            (Default: "xlsx", Values: "xlsx", "json", "dot", "png",
                                                                  "svg")
    -o, --output-file      [value]     - Output filename
    -n, --remote-networks  [boolean]   - Include Remote Networks
    -r, --resources        [boolean]   - Include Resources
    -g, --groups           [boolean]   - Include Groups
    -u, --users            [boolean]   - Include Users
    -d, --devices          [boolean]   - Include Devices (trust)