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 で Connector の Status を取得したいとなったら以下の様な感じで取得できます。
$ 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":{}}'
{
"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
}
}
}
}
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
}
}
]
]
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)
番外編 Terraform の provider です。
現時点ではいくつか対応していない機能があります。
- Remote Network の "Location" 設定
- User の Group 割当
- Connector の "Status emails" 設定
まとめ
使い込んではいませんので所感です。
export/import があり導入も手軽なので、 tg-cli (JavaScript版) の使い勝手が良さそうです。
Twingate-CLI (Python版) の固有機能として DataFrame での出力ができる点がありますが、今の所利用シーンが思い浮かびません。
