SolitonNKは結果の表示だけじゃない。スクリプトを使って解析結果を基にアクションさせよう。（１／３）　anko用組み込み関数

前回の「[SolitonNKには解析機能がこんな豊富にある](https://qiita.com/kakawai/items/dfbafc752855cf724855)」の記事を読んで、ネットワークのログ分析しても、管理者が定期的にダッシュボードを見て確認しなきゃいけないのでは？というご質問を頂戴しました。SolitonNKでは、検索結果を整理・可視化してウェブ表示するだけではなく、解析結果の値が、予め設定した値になったり、スレッシュホールドを超えていたりしたら、ユーザにアラート通知したり、様々なアクションを起こしたりすることもできます。

SolitonNKには anko ベースのスクリプトエンジンと検索結果からアクションを起こすための組み込み関数があり、これを用いてスクリプトを記述して、検索と解析、およびその結果に基づくアクションを自動化・スケジューリングすることができます。

SolitonNKで使えるankoの組み込み関数の説明（本記事）と、SolitonNKでのスクリプトの書き方と使い方の説明、正常ではないDNSクエリをウェブに書き出すサンプルスクリプトの３回に分けて説明します。


# 組み込み関数

SolitonNKに固有の組み込み関数について、[マニュアル](https://github.com/westphaldp/gravwell-wiki/blob/master/scripting/scriptingsearch.md)に基づいて説明します。

これら組み込み関数は

	関数名(<引数/配列>)<返り値>
という書式で記述されます。

## リソースと永続データの操作

`getResource(name) []byte, error`	：`name`で指定されたリソースを指定バイト毎に区切った配列にして返します。リソースの取得中に何らかのエラーが発生した場合には `error` を返します。
`setResource(name, value) error`	：`value`で指定された内容で、`name` で指定された名前のコンテンツを（既存のものがない場合には）作成、または（既存のものがある場合には）更新します。何らかのエラーが発生した場合には `error` を返します。
`setPersistentMap(mapname, key, value)`	：指定されたキーと値の組み合わせを、スケジュールされたスクリプトが繰り返し実行される間保持するために `mapname` で指定された永続マップに保存します。
`getPersistentMap(mapname, key) value`	：指定された永続マップから、指定されたキーに紐付けられた値を返します。
`delPersistentMap(mapname, key)`	：指定されたマップから指定されたキー/値のペアを削除します。

## 検索エントリの操作

`setEntryEnum(ent, key, value)`	：指定されたエントリに列挙値を設定します。
`getEntryEnum(ent, key) value, error`	：指定されたエントリから指定された列挙値を読み取ります。
`delEntryEnum(ent, key)`	：指定された列挙値を特定のエントリから削除します。

## 数値と文字列の操作

`len(val) int`	：`val`で指定された文字列、スライスなどの文字長を返します。
`toIP(string) IP`	：文字列をIPアドレスに変換します。パケットモジュールなどによって生成されたIPアドレスとの比較などに適しています。
`toMAC(string) MAC`	：文字列をMACアドレスに変換します。
`toString(val) string`	：`val`で指定された数値を文字列に変換します。
`toInt(val) int64`	：`val`で指定された数値を整数に変換します（変換可能な場合）。変換できない場合は`0`を返します。
`toFloat(val) float64`	：`val`で指定された数値を浮動小数点数に変換します（変換可能な場合）。変換できない場合は`0.0`を返します。
`toBool(val) boolval`	：`val`で指定された数値をブーリアン型の値に変換します（変換可能な場合）。変換できない場合は `false` を返します。ゼロ以外の数字と文字列 "y"、"yes"、"true" は `true` を返します。
`typeOf(val) type val`	：`val`で指定された数値の型を文字列として返します（例えば"string"、"bool"など）。

## 検索スクリプトの操作

このセクションにおいて、引数や返り値のフィールドの記述で `search` と記述されてる場合は 検索 そのものを表し、`searchID` と記述されてる場合には個々の検索実行に付された 検索ID を表しています。
`search` は、検索からエントリをアクティブに読み取るために使用されます。一方、`searchID` はアタッチまたはその他の方法でハンドリングされている非アクティブな検索を参照するのに使用されます。

`startBackgroundSearch(query, start, end) (search, err)`	： `start` および `end`で指定された時間範囲内でバックグラウンド実行される、指定されたクエリ文字列による検索を作成します。戻り値は検索構造体です。開始および終了の時刻は、`time` ライブラリを使用して指定する必要があります（下のサンプルスクリプトの記述が参考になるでしょう）。
`startSearch(query, start, end) (search, err)`	：上記の `startBackgroundSearch` と同様な機能ですが、フォアグラウンドで動作します。
`detachSearch(search)`	：指定された検索（検索構造体）をデタッチします。この機能を用いると、フォアグラウンドの検索は自動的にクリーンアップされますので、検索が完了する度にこの関数を呼び出してクリーンアップさせておく必要があります。
`attachSearch(searchID) (search, error)`	：指定された検索IDの検索をアタッチし、エントリなどの読み取りに使用できる検索構造体を返します。
`getSearchStatus(searchID) (string, error)`	：指定した検索IDの検索のステータスを返します。例えば`SAVED`など。
`getAvailableEntryCount(search) (uint64, bool, error)`	：指定された検索から読み取ることができるエントリの数、検索が完了したかどうかのブール値（真偽）、および何らかのエラーが発生した場合は `error` を返します。
`getEntries(search, start, end) ([]SearchEntry, error)`	：指定された検索によって得られたエントリを取得します。開始時刻の `start` と終了時刻の `end` 、`getAvailableEntryCount`関数と同様です。
`isSearchFinished(search) (bool, error)`	：指定された検索が完了すると `true` を返します
`executeSearch(query, start, end) ([]SearchEntry, error) `	：検索を開始し、完了するまで待機し、最大1万件のエントリを取得し、検索から切り離して得られたエントリを返します。
`deleteSearch(searchID) error`	：指定された検索IDの検索を削除します
`backgroundSearch(searchID) error`	：指定された検索IDの検索をバックグラウンドに送ります。これは、後の手動検査のために検索を`保持`するのに役立ちます。
`downloadSearch(searchID, format, start, end) ([]byte, error)`	：ユーザーがウェブUIの[ダウンロード]ボタンをクリックした場合と同様に、指定された検索IDの検索をダウンロードします。必要に応じて、"json"、"csv"、"text"、"pcap"、または"lookupdata"のいずれか文字列で `format` 指定できます。`start` および `end` は、開始時刻と終了時刻です。

## ネットワークアクション

セキュリティ上の理由で、現在 httpGet関数や、SendMail関数などは使用できなくなっています。しかしならがら、ankoのnet/httpパッケージの多くの関数は使えますので、http.NewRequest(method, url, body)を組み立てて Client.Do(req)する方法を用いれば、検索結果に基づいて、ウェブへのアクションができます。

SolitonNKに用意されているanko用組み込み関数の説明はここまでです。
[次の記事](https://qiita.com/kakawai/items/49b1e8eaa9c91504b34b)ではSolitonNKの検索用スクリプトを書く方法・使い方について説明します。