TWSLA (TWSNMP’s Simple Log Analyzer)

GitHub Go version GitHub release (latest by date) GitHub License

TWSLA は、超高速の設定不要の CLI ログアナライザーです。複雑な ELK スタックを設定せずに、大量のログからパターンを即座に grep、カウント、視覚化する必要があるシステム管理者向けに設計されています。

TWSLA Demo

twslaはTWSNMPシリーズのシンプルログ分析ツールです。 Linux/Mac OS/Windowsで動作します。

インストール

Linux/Mac OSはシェルスクリプトでインストールするのがオススメです。

$curl -sS https://raw.githubusercontent.com/twsnmp/twsla/main/install/install.sh | sh

Linux/Mac OSはhomebrewでもインストールできます。

$brew install twsnmp/tap/twsla

Windowsは、リリースからZIPファイルをダウンロードするかscoop でインストールします。

>scoop bucket add twsnmp https://github.com/twsnmp/scoop-bucket
>scoop install twsla

基本的な使い方

作業用のディレクトリを作成します。
そのディレクトリに移動します。
ログをimportコマンドでインポートします。
searchコマンドで検索します。
結果をCSVなどに出力できます。

~$mkdir test
~$cd test
~$twsla import -s <Log file path>
~$twsla search

コマンドの説明

コマンド体系

コマンド体系の図解

helpコマンドで対応しているコマンドを確認できます。

Simple Log Analyzer by TWSNMP

Usage:
  twsla [command]

Available Commands:
  ai          AI-powered log analysis
  anomaly     Anomaly log detection
  completion  Generate the autocompletion script for the specified shell
  count       Count log
  delay       Search for delays in the access log
  email       Search or count email logs
  extract     Extract data from log
  heatmap     Command to tally log counts by day of the week and time of day
  help        Help about any command
  import      Import log from source
  mcp         MCP server
  model       Manage local LLM models
  relation    Relation Analysis
  search      Search logs.
  sigma       Detect threats using SIGMA rules
  tfidf       Log analysis using TF-IDF
  time        Time analysis
  twlogeye    Import notify,logs and report from twlogeye (deprecated: use 'import twlogeye://...' instead)
  twsnmp      Get information and logs from TWSNMP FC
  update      Update twsla to the latest or specified version
  version     Show twsla version

Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -h, --help               help for twsla
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

Use "twsla [command] --help" for more information about a command.

コマンドを図示すると

importコマンド

ログをインポートするためのコマンドです。時系列に検索可能なデータベースに保存します。コマンドの引数は、

$ twsla help import
Import log from source
source is file | dir | scp | ssh | twsnmp | imap | pop3

Usage:
  twsla import [flags]

Flags:
      --api              TWSNMP FC API Mode
  -c, --command string   SSH Command
      --emailPassword string   IMAP or POP3 password
      --emailTLS               IMAP use start TLS
      --emailUser string       IMAP or POP3 user name
  -p, --filePat string   File name pattern
  -h, --help             help for import
      --imapFolder             List IMAP folder names
  -k, --key string       SSH Key
  -l, --logType string   TWSNMP FC log type (default "syslog")
      --noDelta          Disable delta check
      --noTS             Import no time stamp file
  -b, --size int         Batch Size (default 10000)
      --skip             TWSNMP FC API skip verify certificate (default true)
  -s, --source string    Log source
      --tls              TWSNMP FC API TLS
      --utc              Force UTC
      --mlStart string   Multiline log start pattern (regex)
      --mlSep string     Multiline log separator pattern (regex)
      --mlLines int      Multiline log fixed lines
      --mlInspect        Inspect log to suggest multiline settings

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

v1.22.0から複数行にまたがるログのインポートに対応しました。以下のオプションでログの結合方法を指定できます。

--mlStart '正規表現': ログの開始行のパターンを指定します。次の開始行が現れるまで、それ以降の行を1つのログとして結合します。
--mlSep '正規表現': ログの区切り行のパターンを指定します。
--mlLines 数値: 指定した行数ごとに1つのログとして結合します。

どの設定を使えばよいかわからない場合は、--mlInspectフラグを付けて実行すると、ログの先頭を分析して推奨される設定を提案します。

$ twsla import -s testlog/multi.log --mlInspect
Inspecting testlog/multi.log...
Found 4 timestamps in 9 lines.
Suggested settings:
  --mlStart '^\d{4}/\d{2}/\d{2}'
  --mlLines 3

-sまたは–sourceで読み込むログの場所を指定します。最新のバージョンでは-sオプションなしでファイルやディレクトリ名を引数で指定できます。ファイルを指定すれば、指定したファイルだけ読み込みます。これはわかりやすいです。実行すれば

$ twsla import ~/Downloads/SSH.tar.gz
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│/ Loading path=/Users/ymi/Downloads/SSH.tar.gz:SSH.log line=655,147 byte=72 MB           │
│  Total file=1 line=655,147 byte=72 MB time=1.709061625s                                 │
│▆▆▆▆▆▆▆▆▆▆▆▆▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇█████████████████████████ 72 MB/Sec│
└─────────────────────────────────────────────────────────────────────────────────────────┘

のような感じで、読み込んだログの件数、サイズ、かかった時間を表示します。ディレクトリを指定するとディレクトリの中のファイルを読み込みます。-pまたは–filePatで、ファイルのパターンを指定すれば、ディレクトリの中のファイルを限定できます。パターンの指定は、シンプルフィルターです。

$ twsla import -s ~/Downloads -p "Linux*"

/ Loading path=/Users/ymimacmini/Downloads/Linux_2k.log line=2,000 byte=212 kB

v1.17.0からインポートのステータス表示が変わりました。

スパークラインを表示します。

ZIPファイルやtar.gz形式のファイルから読み込む場合もファイル名のパターンを指定できます。

読み込む時に、シンプルフィルター、正規表現のフィルターや時間範囲を指定することができます。読み込む量を減らすことができます。

SCP、SSHやTWSNMPのログを読み込むためには、URLを指定します。 scp://root@192.168.1.210/var/log/messages のような形式です。SSHの鍵の登録が必要です。 v1.4.0からTWSNMP FCのWeb APIに対応しました。 -sオプションのURLにtwsnmp://192.168.1.250:8080 と指定して –apiを指定すれば、Web API経由でログをインポートできます。 –logTypeでsyslog以外のログも取得可能です。

v1.20.0からIMAP/POP3サーバーからのメール取り込み、emlファイルの読み込みに対応しました。 -sまたは–sourceに imap://192.168.1.1 imaps://192.168.1.1 pop3://192.168.1.1 pop3s://192.168.1.1 のようなURLを指定することでメールサーバーからメールを取り込んでログとして保存します。メールのヘッダーがログになります。ユーザーID、パスワードはURLに含めることもできますが、 –emailUser –emailPassword で指定することもできます。 IMAPでTLS通信を行いたい場合は –emailTLS を指定します。 IMAPのフォルダを確認したい場合は –imapFolder を指定します。

twlogeyeからのインポートにも対応しています。 twlogeye://192.168.1.1:8081 twlogeye://192.168.1.1:8081/logs/syslog twlogeye://192.168.1.1:8081/report/anomaly/monitor のように指定することで、twlogeyeの通知、ログ、レポートを取り込めます。オプションとして --twlogeyeTarget、--twlogeyeSubTarget、--twlogeyeLevel、--twlogeyeAnomaly、--ca、--cert、--key が利用可能です。

Grafana Lokiからのインポート: loki://192.168.1.1:3100 または lokis://... --lokiQuery で LogQL クエリ（例: --lokiQuery '{job="varlog"}'）、--lokiOrgId でテナントID、--lokiToken で認証トークンを指定できます。

Elasticsearch / OpenSearch からのインポート: es://user:pass@192.168.1.1:9200/logs-* opensearch://user:pass@192.168.1.1:9200/logs-* --esIndex（インデックス指定）、--esQuery（Lucene検索文字列またはQuery DSL）、--esTimeField（タイムスタンプフィールド、デフォルト: @timestamp）、--esMessageField（メッセージフィールド、デフォルト: message）、--esApiKey（API Key）が利用可能です。

FTP / FTPS サーバーからのインポート: ftp://user:pass@192.168.1.1/var/log/syslog ftp://192.168.1.1/logs/ (ディレクトリ指定時は -p "syslog*" でファイル名パターン指定可能) ftps://user:pass@192.168.1.1/var/log/syslog ユーザー名・パスワードはURLに含めることも、--ftpUser / --ftpPassword で指定することもできます（未指定時は匿名ログイン anonymous）。 TLS接続は ftps:// または --ftpTLS で有効化され、--ftpSkip（デフォルト: true）で証明書検証スキップを設定できます。 .gz 圧縮ログファイルも自動的にストリーム解凍してインポートされます。

emlファイルを読み込む場合は、

$ twsla import sample.eml

のように指定します。

v1.1.0からevtxファイルを読み込む時に、Windowsのイベントログを読み込むことができます。

詳しい情報が表示できます。

ログの読み込み先は、-dオプションで指定します。bbolt (.db)、Badger (.badger)、Parquet (.parquet) のデータストアに対応しています。省略すれば、カレントディレクトリのtwsla.dbになります。 v1.8.0から–noDeltaを指定することで、時間差を取得して保存する処理を行わないようにできます。これで、少し速度アップします。 importの速度は、ログが時系列に並んでいるほうが高速です。タイムスタンプがランダムなログは遅くなります。

search コマンド

ログの読み込みが終われば、検索できます。

twsla  help search
Search logs.
Simple filters, regular expression filters, and exclusion filters can be specified.

Usage:
  twsla search [flags]

Flags:
  -c, --color string   Color mode
  -h, --help           help for search

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

シンプルフィルター、正規表現のフィルターや時間範囲を指定してログを絞り込んでいけます。現在のバージョンでは引数でシンプルフィルターと^から始めると反転フィルターです。

$ twsla search -f fail

のような感じで検索すると

検索結果の画面の右上にキー入力のヘルプが表示されます。ｓキーで結果を保存できます。rキーで表示を逆順にします。qキー終了です。 v1.5.0からログの検索結果をカラー表示できるようになっています。ログを検索するsearchコマンドのオプションに-c,–colorを指定します。キーには

Key	Description
ip	IPアドレスをカラー表示
mac	MACアドレスをカラー表示
email	メールアドレスをカラー表示
url	URLをカラー表示
filter	フィルターで指定した文字列をカラー表示
regexp/パターン/カラー	正規表現にマッチした文字列を指定した色で表示

を指定できます。

同じログを

twsla search -f Failed -c "regex/user\s+\S+/9,ip,filter"

のような指定で表示すると

のようにカラー表示できます。

v1.6.0からカラー表示の指定を検索結果画面からできるようになっています。 cキーを押すと入力画面が表示されます。mキーを押すと

マーカーの入力画面を表示します。シンプルフィルターかregex:に続けて正規表現フィルターを指定してログの該当文字列にマークをつけることができます。ipのカラーとfailにマーカーをつけた例です。

countコマンド

ログの件数を時間単位に集計したり、ログの中のデータをキーにして集計したりするコマンドです

$ twsla  help  count
Count the number of logs.
Count logs for each specified period
Number of occurrences of items extracted from the log.
Count normalized logs by pattern
 $twsla count -e normalize
Count word in logs.
 $twsla count -e word
Count json key.
 $twsla count -e json -n Score

Usage:
  twsla count [flags]

Flags:
      --delay int        Delay filter
  -e, --extract string   Extract pattern or mode. mode is json,grok,word,normalize
      --geoip string     geo IP database file
  -g, --grok string      grok pattern definitions
  -x, --grokPat string   grok pattern
  -h, --help             help for count
  -i, --interval int     Specify the aggregation interval in seconds.
      --ip string        IP info mode(host|domain|loc|country)
  -n, --name string      Name of key
  -p, --pos int          Specify variable location (default 1)
  -q, --timePos int      Specify second time stamp position
      --utc              Force UTC

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

検索と同じようにフィルターをかけることができます。 -e オプションで抽出するデータを指定した場合、このデータ単位で集計します。指定しない場合は、時間単位のログの数を集計します。時間単位の集計は、

$twsla  count -f fail

のような結果になります。時間の間隔は-iオプションで指定します。省略すれば、よしなに設定されるはずです。 v1.1.0から前のログからの差分時間(Delta)も表示されます。上部に、平均の間隔も表示されます。 cキーでカウント数によってソートできます。kキーで時間でソートです。 sキーで結果を保存できます。拡張子をpngにすれば、グラフになります。

v1.5.0から拡張子をhtmlで保存するとHTMLファイルのグラフを保存できます。インタラクティブに操作できるグラフです。

のような結果になります。こちらもソートできます。グラフに保存すると

のようにTOP10の割合がグラフになります。

v1.16.0から遅延時間のフィルターを追加しました。

--delay <数値>

を指定するとdelayコマンドで表示される遅延時間が指定の数値以上のログから集計します。

  -q, --timePos int      Specify second time stamp position
      --utc              Force UTC

は、delayコマンドと同様にログの中の２つのタイムスタンプの時差を検知するモードです。

extractコマンド

ログから特定のデータを取り出すコマンドです。

$twsla  help extract
Extract data from the log.
Numeric data, IP addresses, MAC addresses, email addresses
words, etc. can be extracted.

Usage:
  twsla extract [flags]

Flags:
  -e, --extract string   Extract pattern
      --geoip string     geo IP database file
  -h, --help             help for extract
  -n, --name string      Name of value (default "Value")
  -p, --pos int          Specify variable location (default 1)

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

検索と同じフィルターが指定できます。抽出するデータの指定もcountコマンドと同じです。

$twsla  extract -f fail -e ip

のようなコマンドで実行すると

のような時系列のデータになります。キーでソートもできます。結果をグラフに保存もできます。

数値データは、そのままグラフにしますが、IPアドレスなどの項目は、項目の番号をグラフにします。

のような数値データを抽出した状態でiキーを押すと数値データの統計情報を表示します。

sキーを押してCSVで保存することもできます。

tfidfコマンド

TF-IDFを使って、珍しいログを探します。

$ twsla help tfidf
Use TF-IDF to find rare logs.
You can specify a similarity threshold and the number of times the threshold is allowed to be exceeded.

Usage:
  twsla tfidf [flags]

Flags:
  -c, --count int     Number of threshold crossings to exclude
  -h, --help          help for tfidf
  -l, --limit float   Similarity threshold between logs (default 0.5)
  -n, --top int       Top N
      --noGPU         Disable GPU acceleration and use CPU/SIMD only

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

TF-IDFの全対類似度計算は、GPU（Metal / WebGPU）およびSIMD（AVX2）による行列積アクセラレーション（$S = X \cdot X^T$）に対応しており、大量のログでも高速に比較・分析されます。--noGPU（または --no-gpu）を指定するとGPUを使わずにCPU/SIMDモードで動作します。

実行すると

のような結果になります。２０００件の中の珍しいログ３件を見つけています。 -lでしきい値、-cで許容回数を指定できます。玄人向けなので詳しいことは別の記事に書くつもりです。 v1.10から-nで珍しい上位N件を取得できるようになりました。

anomalyコマンド

v1.1.0で追加したコマンドです。ログをAI分析して異常なものを見つけるコマンドです。

Anomaly log detection
Detect anomaly logs using various machine learning and statistical algorithms.

Feature Extraction Modes (-m, --mode):
  tfidf:       TF-IDF vectorized log tokens for finding rare/unusual log patterns (default)
  sql:         SQL injection detection features (UNION, SELECT, SQL syntax keywords)
  os:          OS command injection detection features (/bin/sh, cmd.exe, shell commands)
  dir:         Directory traversal detection features (../, /etc/passwd, path traversal)
  walu:        Web Access Log Unified composite features (status, method, latency, path)
  number:      Numerical values extracted from logs (specify position with -e pattern)

Algorithms (-a, --algo):
  iforest:     Isolation Forest outlier detection (tree-based) (default)
  autoencoder: Deep Learning Autoencoder via tensai (reconstruction loss)
  lstm:        Sequential transition anomaly detection via tensai
  lof:         Local Outlier Factor (density-based outlier detection)
  knn:         k-Nearest Neighbor distance (distance-based anomaly detection)
  mahalanobis: Mahalanobis distance (multivariate covariance outlier detection)
  zscore:      Statistical Z-Score (standard deviation deviations)

Usage:
  twsla anomaly [flags]

Flags:
  -a, --algo string      Anomaly algorithm: iforest, autoencoder, lstm, lof, knn, mahalanobis, zscore (default "iforest")
  -e, --extract string   Extract pattern for number mode (e.g. start*end)
  -h, --help             help for anomaly
  -m, --mode string      Detection modes: tfidf, sql, os, dir, walu, number (default "tfidf")
      --noGPU            Disable GPU acceleration and use CPU/SIMD only

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

-mで特徴抽出モードを指定します。

tfidf: TF-IDFでログの特徴ベクターを作成します。
sql, os, dir: SQLインジェクション、OSインジェクション、パストラバーサルに登場するキーワードの頻度から特徴ベクターを作成します。
walu: Webアクセスログ向けの複合特徴量を抽出します。
number: ログに登場する数値から特徴ベクターを作成します。-e オプション（例: start*end）で数値の位置を指定可能です。

-a（–algo）で異常検知アルゴリズムを指定します。

iforest (デフォルト): 孤立木（Isolation Forest）による外れ値検知。
autoencoder: tensai を利用したニューラルネットワーク自己符号化器（Autoencoder）。再構成誤差から異常を検出します。
lstm: tensai による時系列・シーケンス遷移予測誤差検知。
lof: Local Outlier Factor（局所外れ値因子法）。密度ベースの外れ値検知。
knn: k-Nearest Neighbor（k近傍平均距離）による距離ベース検知。
mahalanobis: マハラノビス距離による多変量異常検知。
zscore: 統計的偏差（Z-Score）による高速検知。

分析結果は

のような感じで表示されます。Scoreが大きいほど異常と判断しています。SQLインジェクションやWALUはWebサーバーのアクセスログの分析に効果があります。

delayコマンド

v1.3.0で追加したコマンドです。Accessログから処理の遅延を検知するためのコマンドです。ApacheのAccessログはHTTPのリクエストを受け付けた時点の時刻をタイムスタンプに記録します。実際にログに出力するのは、処理が終わって応答を返してからです。このためにログのタイムスタンプが前後して記録される場合があります。先に記録されたものより前の時刻のログが後から記録されるという意味です。この逆転現象を利用すると処理の遅延を検知できます。リクエストの処理や大きなファイルのダウンロードに時間がかかるなどの遅延です。 ApacheのAccessログをSyslogに転送して記録するとタイムスタンプが２つあるログになります。この２つ以上タイムスタンプのあるログの時間差が処理の遅延を表している場合があります。これを検知するモードも作りました。

Search for delays in the access log

Usage:
  twsla delay [flags]

Flags:
  -h, --help          help for delay
  -q, --timePos int   Specify second time stamp position
      --utc           Force UTC

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

-q のオプションに1以上の値をつけると２つ以上のタイムスタンプを処理するモードになります。-qを省略するか0を指定するとAccessログの逆転現象を利用して遅延を検知するモードになります。

遅延を検知できない場合は、何も表示されません。右端が遅延時間です。ログを選択してEnterキーを押せばログを詳しく表示します。tキーで時刻順にソートします。dキーで遅延の大きさ順にソートします。sキーでファイルに保存できます。拡張子をpngにするとグラフ画像を保存します。

twsnmpコマンド

v1.4.0で追加したTWSNMP FCと連携するためのコマンドです。

Get information and logs from TWSNMP FC
[target] is node | polling | eventlog | syslog | trap |
  netflow | ipfix | sflow |sflowCounter | arplog | pollingLog

Usage:
  twsla twsnmp [target] [flags]

Flags:
      --checkCert       TWSNMP FC API verify certificate
  -h, --help            help for twsnmp
      --jsonOut         output json format
      --twsnmp string   TWSNMP FC URL (default "http://localhost:8080")

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

–twsnmpで連携するTWSNMP FCのURLを指定します。ユーザーID、パスワードを変更している場合は、このURLで指定します。 http://ユーザーID:パスワード@192.168.1.250:8080などです。ノードリストの取得は

twsla twsnmp node --twsnmp http://192.168.1.253:8081
17ea9e198e6dce8e        eve-ng-ymi.     normal  192.168.13.1
17ea9e1c9574f616        192.168.13.2    low     192.168.13.2    00:50:79:66:68:05(Private)
17ea9f2747b86b64        Switch1 repair  192.168.13.3    50:00:00:01:80:01(Unknown)
17eaa033358f42c5        Switch2 low     192.168.13.4    50:00:00:02:80:01(Unknown)
17eaa11396dcdfa5        Switch3 low     192.168.13.5    50:00:00:03:80:01(Unknown)
17eaa113ae173e88        Switch4 low     192.168.13.6    50:00:00:04:80:01(Unknown)
17eb3bd030fd9f81        Router  low     192.168.1.242   24:FE:9A:07:D2:A9(CyberTAN Technology Inc.)

のようなコマンドでできます。基本的にTAB区切りのテキストで出力します。ファイルにリダイレクトで保存できます。 –jsonOutを指定すれば、JSON形式の出力になります。プログラムから利用する時は、こちらが便利だと思います。

emailコマンド

インポートしたメールのログを検索したり集計したりするためのコマンドです。検索結果では、メールヘッダーから計算した遅延時間とリレー回数を確認できます。 dキーで遅延時間、rキーでリレー回数でソートできます。

Search or count email logs from the database.
It provides subcommands to search for specific emails or count emails by various fields such as From, To, Subject, Sender IP, and SPF status.

Usage:
  twsla email [search|count] [flags]

Flags:
      --checkSPF            Check SPF
      --emailCountBy string Count by field (default "time")
  -h, --help                help for email

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

searchサブコマンドでメールを検索します。検索結果からEnterキーでメールの詳細を表示できます。 countサブコマンドで、送信元、宛先、件名、送信元IPアドレス、ドメイン、SPFの状態などで集計できます。

集計可能なフィールド（–emailCountByに指定）:

time: 時間単位（デフォルト）
from: 送信元
to: 宛先
matrix: 送信元=>宛先
subject: 件名
ip: 送信元IPアドレス
domain: 送信元ドメイン
spf: SPFの状態
spf.list: SPFの詳細リスト

–checkSPFを指定すると、集計時にSPFのチェックを行います。

relationコマンド

ログの行にある２つ以上の項目の関係をリストアップします。有指向グラフに出力することもできます。

$twsla help relation
Analyzes the relationship between two or more pieces of data extracted from a log,
such as the relationship between an IP address and a MAC address.
data entry is ip | mac | email | url | regex/<pattern>/<color>

Usage:
  twsla relation <data1> <data2>... [flags]

Flags:
  -h, --help   help for relation

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

指定可能な項目は

Key	Description
IP	IPアドレス
Mac	MACアドレス
Email	メールアドレス
URL	URL
REGEXP/Pattern/	正規表現にマッチした文字列

です。

$twsla relation  -f Failed -r user "regex/user\s+\S+/" ip

のようなコマンドで

のように集計できます。フィルターを工夫して件数を絞れば

のようなグラフも出力できます。s:Saveコマンドの出力ファイルの拡張子をhtmlに指定します。

heatmapコマンド

曜日または日付単位でログの多い時間帯をヒートマップで表示するためのコマンドです。

twsla help heatmap
Command to tally log counts by day of the week and time of day
	Aggregate by date mode is also available.

Usage:
  twsla heatmap [flags]

Flags:
  -h, --help   help for heatmap
  -w, --week   Week mode

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

-w オプションを指定すると曜日単位で集計します。指定しない場合に日付単位です。

日付単位は

拡張子htmlのファイルの保存すると

のようなグラフを保存できます。曜日単位は

です。

timeコマンド

ログ間の時間差を分析するコマンドです。v1.6.0で追加したコマンドです。

Time analysis

Usage:
  twsla time [flags]

Flags:
  -h, --help   help for time

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

実行すると

マークしたログとの時間差がDiffです。前のログとの時間差がDeltaです。選択すると２行目にDiffとDeltaを人間がわかりやすい形式で表示します。また、２行目にはDeltaの平均値(Mean)、中央値(Median)、最頻値(Mode)、標準偏差(StdDiv)を表示します。この例だと、約24時間毎にログが記録されているところがわかります。 mキーを押すと選択したログにマークをつけます。 htmlまたは、pngで保存すると Deltaをグラフに出力します。

sigmaコマンド

脅威検知の標準フォーマットsigma

https://sigmahq.io/

による検査を行うコマンドです。

Detect threats using SIGMA rules.
	About SIGAMA
	https://sigmahq.io/

Usage:
  twsla sigma [flags]

Flags:
  -c, --config string    config path
  -g, --grok string      grok definitions
  -x, --grokPat string   grok pattern if empty json mode
  -h, --help             help for sigma
  -s, --rules string     Sigma rules path
      --strict           Strict rule check

Global Flags:
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

twsla には標準で 11種類の組み込みルールパック（合計75ルール） を内蔵しており、外部ルールファイルを用意しなくても twsla sigma を実行するだけですぐに高精度な脅威検知を開始できます（各パックの対象ログや収録ルール一覧は組み込みルールパック詳細ガイドを参照）。

-p, --sigmaPacks オプションで特定のパック（windows-essential, linux-auth, wazuh-compliance 等）に絞り込むことや、-s オプションで外部カスタムルールディレクトリを指定することも可能です（外部ルールと同一IDのルールがある場合、外部ルールが組み込みパックを自動的にオーバーライドします）。

また、Windows、Linux、ネットワーク機器、Web サーバーアクセスログ用の各種 Sigma 設定ファイル（windows, linux, network, web）が組み込まれており、ログのタイムスタンプに基づいたスライディングウィンドウによる相関検知（短時間での複数回認証失敗など）も自動で判定されます。

ログは JSON 形式のほか、Syslog、Splunk 風 key=val 形式、名前付き正規表現キャプチャ（wazuh-linux 有効時は SSHD/Sudo/PAM デコーダーを自動適用）および GROK パターンでの抽出に対応しています。組み込みのGROK定義は

https://github.com/elastic/go-grok

を参照してください。

sigmaコマンドを実行すると

のような結果表示になります。検知したsigmaルールの情報（重要度、時刻、ルール名、MITRE ATT&CK / 規格タグ等）を表示します。リターンキーを押せば、対象のログを含む詳しいログを表示します。

c キーを押すことで、イベント一覧 ⇄ ルール別集計 ⇄ タグ別集計（MITRE ATT&CK / コンプライアンス規格） を順次切り替えることができます。

g キーまたは h キーで、表示中のモード（ルール別・タグ別）に応じた集計グラフ（ブラウザ表示 HTML または Sixel / PNG）を表示できます。 s キーでデータやグラフをファイルに保存できます。

CLI サブアクション・Wazuh 変換コマンド

# 利用可能なパックの一覧表示
twsla sigma packs

# ルール総数、ログソース数、Top Tags（MITRE / コンプライアンス規格別）の統計
twsla sigma stat

# 有効なルール一覧の確認
twsla sigma list -p linux-auth

# 単一ログに対するルールマッチングテスト
twsla sigma test '{"content":"Failed password for invalid user admin from 192.168.1.100 port 45678 ssh2"}'

# Wazuh ルール XML から Sigma YAML への一括/個別変換
twsla sigma convert-wazuh -o ./converted-rules ./ruleset/rules/0095-sshd_rules.xml

# Wazuh デコーダー XML から名前付き正規表現パターンへの変換
twsla sigma convert-wazuh-decoder -o ./captures ./0310-ssh_decoders.xml

twlogeyeコマンド

TwLogEye

https://github.com/twsnmp/twlogeye

https://twsnmp.github.io/twlogeye/

というログサーバーからgRPCで脅威検知通知やログをインポートします。

Import notify,logs and report from twlogeye
twsla twlogeye <target> [<sub target>] [<anomaly report type>]
  target: notify | logs | report
	logs sub target: syslog | trap | netflow | winevent | otel | mqtt
	report sub target: syslog | trap | netflow | winevent | otel | mqtt  | monitor | anomaly
	anomaly report type: syslog | trap | netflow | winevent |otel | mqtt | monitor | anomaly

Usage:
  twsla twlogeye [flags]

Flags:
      --anomaly string     Anomaly report type (default "monitor")
      --apiPort int        twlogeye api port number (default 8081)
      --apiServer string   twlogeye api server IP address
      --ca string          CA Cert file path
      --cert string        Client cert file path
      --filter string      Log search text
  -h, --help               help for twlogeye
      --key string         Client key file path
      --level string       Notify level

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

ai コマンド

LLMと連携してログを分析するためのコマンドです。 tensai による組み込み（Embedded）推論に対応しており、外部APIやOllamaサーバーなしでローカルにAI分析を実行することもできます。

AI-powered log analysis
Using environment variable for API key.
 GOOGLE_API_KEY : gemini
 ANTHROPIC_API_KEY : claude
 OPENAI_API_KEY: openai

Usage:
  twsla ai <filter>... [flags]

Flags:
      --aiBaseURL string       AI base URL
      --aiErrorLevels string   Words included in the error level log (default "error,fatal,fail,crit,alert")
      --aiLang string          Language of the response
      --aiModel string         LLM Model name or preset (e.g. qwen2.5-0.5b, smollm2-135m)
      --aiProvider string      AI provider(tensai|embedded|ollama|gemini|openai|claude)
      --aiSampleSize int       Number of sample log to be analyzed by AI (default 50)
      --aiTopNError int        Number of error log patterns to be analyzed by AI (default 10)
      --aiWarnLevels string    Words included in the warning level log (default "warn")
      --aiNoMask               Do not mask PII in logs
      --noGPU                  Disable GPU acceleration and use CPU/SIMD only
  -h, --help                   help for ai

プロバイダの選択とGPU/CPU切り替え

--aiProvider を明示的に指定した場合、指定したプロバイダ（ollama, gemini, openai, claude, tensai / embedded）が使用されます。
--aiModel でモデルを指定できます。tensaiプロバイダでは、ファイル名だけでなくプリセット名（例: qwen2.5-coder-0.5b, smollm2-135m）での直接指定も可能です。
--aiProvider を省略した場合：
1. ローカルモデル（~/.twsla/models/）が存在すれば自動的に組み込みの tensai を使用します。
2. 存在しない場合、APIキー環境変数（OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY）を検索します。
3. APIキーも見つからない場合は ollama にフォールバックします。
--noGPU（または --no-gpu）を指定すると、GPUアクセラレーションを使用せずCPU/SIMDモードで推論を実行します（速度比較や省電力用途に利用可能）。

v1.21.0から、AIに分析を依頼する前にログ内のPII（個人情報：IPアドレス、メールアドレス、電話番号など）を自動的にマスクするようになりました。マスクせずに元のログを送信したい場合は、--aiNoMaskフラグを使用してください。

model コマンド

組み込みAI分析で使用するLLMモデルをローカルにダウンロード・管理するコマンドです。

Manage local LLM models for embedded AI analysis.
Download, list, and remove models stored locally.

Usage:
  twsla model [command]

Available Commands:
  download      Download a model from Hugging Face or URL
  download-gpu  Download and install wgpu-native library for GPU acceleration
  list          List locally downloaded models (alias: ls)
  presets       List available preset models
  remove        Remove a local model (alias: rm)
  status        Show model directory and hardware acceleration status

モデルおよびGPUライブラリの管理

プリセット名またはHugging FaceのGGUF URLを指定してダウンロードします。また、GPUアクセラレーションライブラリ（wgpu-native）をダウンロードしてGPU推論（Metal / Vulkan / D3D12）を有効化できます。

# ハードウェアアクセラレーションとモデル状態の確認
$ twsla model status

# GPUアクセラレーションライブラリ（wgpu-native）のダウンロード・セットアップ
$ twsla model download-gpu

# プリセット一覧の確認
$ twsla model presets

# プリセットモデルのダウンロード（例: qwen2.5-coder-0.5b）
$ twsla model download qwen2.5-coder-0.5b

# ダウンロード済みモデル一覧（短縮コマンド: ls）
$ twsla model list
$ twsla model ls

# モデルの削除（短縮コマンド: rm、プリセット名でも指定可能）
$ twsla model rm qwen2.5-coder-0.5b

利用可能なプリセットモデル:

プリセット名	モデル	サイズ目安	特徴・用途
`qwen2.5-0.5b`	Qwen2.5-0.5B-Instruct (Q8_0)	約 500MB	標準軽量モデル（汎用）
`qwen2.5-1.5b`	Qwen2.5-1.5B-Instruct (Q4_K_M)	約 1.0GB	高精度軽量モデル（汎用）
`qwen2.5-coder-0.5b`	Qwen2.5-Coder-0.5B-Instruct (Q8_0)	約 500MB	ログ・JSON・コード構造解析特化
`qwen2.5-coder-1.5b`	Qwen2.5-Coder-1.5B-Instruct (Q4_K_M)	約 1.0GB	高精度コード・ログ解析
`smollm2-135m`	SmolLM2-135M-Instruct (Q8_0)	約 145MB	極小超軽量・高速（IoT/省リソース向け）
`smollm2-360m`	SmolLM2-360M-Instruct (Q8_0)	約 380MB	軽量バランスモデル
`smollm2-1.7b`	SmolLM2-1.7B-Instruct (Q4_K_M)	約 1.1GB	SmolLM2上位高精度モデル
`deepseek-r1-1.5b`	DeepSeek-R1-Distill-Qwen-1.5B (Q4_K_M)	約 1.1GB	`<think>` 思考プロセスを持つ推論型モデル
`llama-3.2-1b`	Llama-3.2-1B-Instruct (Q4_K_M)	約 800MB	Meta Llama 3.2 1B モデル
`tinyllama`	TinyLlama-1.1B-Chat-v1.0 (Q4_K_M)	約 670MB	クラシック軽量モデル

ログ検索して

のような画面が表示されます。

ログを選択してeキーを押すと

AIによるログに関する説明が表示されます。

aキーを押すと検索したログ全体に関するAIの分析が表示されます。

AIの回答は画面を閉じるまで記憶しています。aキーやログを選択してeキーを押した時に、即座に画面が表示されます。

mcp コマンド

MCPサーバー

$twsla help mcp
MCP server for AI agent

Usage:
  twsla mcp [flags]

Flags:
      --clients string     IP address of MCP client to be allowed to connect Specify by comma delimiter
      --endpoint string    MCP server endpoint(bind address:port) (default "127.0.0.1:8085")
      --geoip string       geo IP database file
  -h, --help               help for mcp
      --transport string   MCP server transport(stdio/sse/stream) (default "stdio")

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

MCP Serverツールを利用するためのシステムプロンプト

# TWSLAログ分析AI - システムプロンプト

あなたはTWSLA（TWSNMP Log Analyzer）のAIアシスタントです。あなたの主な役割は、ユーザーがTWSLAデータベースに保存されているログを分析するのを支援することです。ログの検索、カウント、データ抽出、要約ができます。

## 利用可能なツール

TWSLAログデータベースと対話するために、以下のツールにアクセスできます。

### 1. `search_log`

このツールを使用して、特定の基準に一致するログエントリを検索します。

**パラメータ:**

*   `filter` (string, optional): ログをフィルタリングするための正規表現。空の場合はフィルタは適用されません。
*   `limit` (integer, optional): 返されるログエントリの最大数。（最小: 100, 最大: 10000, デフォルト: 100）
*   `start` (string, optional): 検索の開始日時（例: "2025/10/26 11:00:00"）。空の場合は最初からになります。
*   `end` (string, optional): 検索の終了日時（例: "2025/10/26 12:00:00"）。空の場合は現在時刻になります。

**例:**
過去1時間に「error」という単語を含むログを検索する場合:
`search_log(filter="error", start="-1h")`

### 2. `count_log`

このツールを使用して、特定の単位でグループ化してログエントリをカウントします。これは統計分析に役立ちます。

**パラメータ:**

*   `filter` (string, optional): カウントする前にログをフィルタリングするための正規表現。
*   `unit` (string, optional): カウントの単位。（デフォルト: "time"）
    *   `time`: 時間間隔でグループ化します。
    *   `ip`: 送信元IPアドレスでグループ化します。
    *   `email`: メールアドレスでグループ化します。
    *   `mac`: MACアドレスでグループ化します。
    *   `host`: ホスト名でグループ化します（DNS解決が必要です）。
    *   `domain`: ドメイン名でグループ化します。
    *   `country`: 国でグループ化します（GeoIPデータベースが必要です）。
    *   `loc`: 地理的な場所でグループ化します（GeoIPデータベースが必要です）。
    *   `word`: ログメッセージ内の個々の単語でグループ化します。
    *   `field`: 特定のフィールド（スペース区切り）でグループ化します。
    *   `normalize`: 正規化されたログパターンでグループ化します。
*   `unit_pos` (integer, optional): `unit`が "field" の場合の単位の位置。（デフォルト: 1）
*   `top_n` (integer, optional): 返す上位の結果の数。（デフォルト: 10）
*   `interval` (integer, optional): `unit`が "time" の場合の集計間隔（秒）。（デフォルト: 自動）
*   `start` (string, optional): 検索の開始時刻。
*   `end` (string, optional): 検索の終了時刻。

**例:**
過去24時間の上位10件の送信元IPアドレスをカウントする場合:
`count_log(unit="ip", top_n=10, start="-24h")`

### 3. `extract_data_from_log`

このツールを使用して、ログエントリから特定の情報（IPアドレス、メールアドレス、カスタムパターンなど）を抽出します。

**パラメータ:**

*   `filter` (string, optional): 抽出前にログをフィルタリングするための正規表現。
*   `pattern` (string, required): 抽出するデータのパターン。
    *   `ip`, `mac`, `email`, `number`
    *   またはカスタム正規表現。
*   `pos` (integer, optional): パターンが複数のマッチを見つけた場合に抽出するデータの位置。（デフォルト: 1）
*   `start` (string, optional): 検索の開始時刻。
*   `end` (string, optional): 検索の終了時刻。

**例:**
過去1日間に「failed login」を含むログからすべてのIPアドレスを抽出する場合:
`extract_data_from_log(filter="failed login", pattern="ip", start="-1d")`

### 4. `import_log`

このツールを使用して、ファイルまたはディレクトリから新しいログをTWSLAデータベースにインポートします。

**パラメータ:**

*   `path` (string, required): ログファイルまたはディレクトリへのパス。`.zip`、`.tar.gz`、`.gz`などの圧縮ファイルを処理できます。
*   `pattern` (string, optional): ディレクトリまたはアーカイブ内のファイル名をフィルタリングするための正規表現。

**例:**
`/var/log/`ディレクトリからすべての`.log`ファイルをインポートする場合:
`import_log(path="/var/log/", pattern=".*\.log")`

### 5. `get_log_summary`

このツールを使用して、指定された期間のログの概要を取得します。概要には、合計エントリ数、エラーと警告の数、および上位のエラーパターンが含まれます。

**パラメータ:**

*   `filter` (string, optional): ログをフィルタリングするための正規表現。
*   `top_n` (integer, optional): 返す上位のエラーパターンの数。（デフォルト: 10）
*   `start` (string, optional): サマリーの開始時刻。
*   `end` (string, optional): サマリーの終了時刻。

**例:**
昨日のすべてのログのサマリーを取得する場合:
`get_log_summary(start="-1d", end="today")`

### 6. `detect_threats_sigma`

SIGMAルールを使用してログ内の脅威を検出します。組み込みのルール定義またはカスタムルールファイルを指定できます。

**パラメータ:**

*   `rules` (string, optional): SIGMAルールファイルまたはディレクトリへのパス。
*   `config` (string, optional): 組み込みSIGMA設定マッピング名（例: "windows"）。
*   `strict` (boolean, optional): 厳密なルール構文チェックを行うか（デフォルト: false）。

### 7. `detect_anomalies`

機械学習・統計アルゴリズム（Isolation Forest, Autoencoder, LSTM, LOF, k-NN, Mahalanobis, Z-Score）を用いて異常ログを検出します。

**パラメータ:**

*   `mode` (string, optional): 特徴抽出モード（`tfidf`, `sql`, `os`, `dir`, `walu`, `number`、デフォルト: `tfidf`）。
*   `algo` (string, optional): 異常検知アルゴリズム（`iforest`, `autoencoder`, `lstm`, `lof`, `knn`, `mahalanobis`, `zscore`、デフォルト: `iforest`）。
*   `filter` (string, optional): 分析対象のログフィルタ。
*   `extract` (string, optional): `number` モード等での数値抽出パターン。
*   `top_n` (integer, optional): 取得する上位異常ログ件数（デフォルト: 10）。

### 8. `analyze_relations`

ログ内に登場する複数の要素（IPアドレス、MACアドレス、メール、URL、正規表現パターン）の共起関係・関連性を分析します。

**パラメータ:**

*   `data` (array of string, required): 分析対象のデータ種別・パターン指定（例: `["ip", "mac"]`, `["ip", "regex/failed/red"]`）。
*   `filter` (string, optional): 分析対象ログの正規表現フィルタ。
*   `top_n` (integer, optional): 上位関連性の取得数（デフォルト: 10）。

### 9. `analyze_tfidf`

TF-IDFを用いて類似度閾値を超えない珍しいログや外れ値パターンを発見・抽出します。

**パラメータ:**

*   `filter` (string, optional): フィルタ。
*   `limit` (number, optional): ログ間の類似度閾値（デフォルト: 0.5）。
*   `count` (integer, optional): 類似ログの上限出現回数。
*   `top_n` (integer, optional): 取得件数（デフォルト: 10）。

## 利用可能なリソース (Resources)

*   `twsla://db/status`: TWSLAデータベースのデータストア種別、総レコード数、記録期間（最初と最後のタイムスタンプ）をJSON形式で提供します。
*   `twsla://sigma/rules`: TWSLAに組み込まれているSigma設定定義一覧を提供します。

## 利用可能なプロンプト (Prompts)

*   `incident_investigation`: セキュリティインシデントやシステム障害調査のためのタイムライン、異常値、相関分析ワークフロー。
*   `security_threat_hunt`: SIGMA検知およびWeb攻撃異常検知を活用したプロアクティブな脅威ハンティング。
*   `anomaly_audit`: 孤立木（Isolation Forest）やTF-IDFを用いた外れ値パターンの体系的監査。

## 一般的な指示

*   常にユーザーの要求を注意深く分析して、最も適切なツールを選択してください。
*   時間を扱うときは、相対的な期間（例: "-1h"、"-24h"）または絶対的なタイムスタンプを使用できます。
*   複雑な質問に答えるためにツールを組み合わせてください。たとえば、最初に`get_db_info`や`search_log`を使用してデータの概要を把握し、次に`count_log`、`detect_anomalies`、`analyze_relations`を使用して詳細な分析を行うことができます。
*   ユーザーの要求が曖昧な場合は、ツールを実行する前に明確化を求めてください。

MCP サーバーの設定

トランスポート: stdio (console), sse (server-sent events), or stream (HTTP with client filtering).
エンドポイント: Default 127.0.0.1:8085.
クライアント: IPのホワイトリストをカンマ区切りで指定.

updateコマンド

GitHubのリリースページからtwslaを最新または指定したバージョンに更新します。

$ twsla help update
Update twsla to the latest or specified version from GitHub releases.

Usage:
  twsla update [flags]

Flags:
  -c, --check            Check for updates only
  -h, --help             help for update
      --version string   Update to specified version
  -y, --yes              Update without confirmation

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
      --sixel              show chart by sixel
  -t, --timeRange string   Time range

completionコマンド

コマンドの補完をするためのスクリプトを生成するコマンドです。対応しているシェルは、

  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

Linuxのbash環境では /etc/bash_completion.d/ にスクリプトを保存すればよいです。

$twsla completion bash > /etc/bash_completion.d/twsla

です。 Mac OSのzshでは、 ~/.zsh/completion/ にスクリプトを保存します。

$mkdir -p ~/.zsh/completion/
$twsla completion zsh > ~/.zsh/completion/_twsla

その後、 ~/.zshrcに

fpath=(~/.zsh/completion $fpath)
autoload -Uz compinit && compinit -i

を追加します。シェルを再起動します。

$exec $SHELL -l

か、簡単なのは、ターミナルを閉じてもう一度開けばよいです。

WindowsのPowerShellの場合は、

>twsla completion powershell | Out-String | Invoke-Expression

でよいみたいです。twsla.ps1とスクリプトファイルを保存して、PowerShellのプロファイルに登録すればよいらしいです。

versionコマンド

TWSLAのバージョンを表示します。

$twsla version
twsla v2.2.0(commit) 2026-09-10T00:00:00Z

補足説明

対応しているログ

テキストファイルで１行毎にタイムスタンプがあるもの（複数行ログ対応）
Windowsのevtx形式
TWSNMP FCの内部ログ
電子メール(.eml)
IMAP/POP3サーバー上のメール
Grafana Loki (loki://, lokis://)
Elasticsearch (es://) / OpenSearch (opensearch://)
twlogeye (twlogeye://)

です。テキスト形式のファイルはZIPやtar.gzの中にあっても直接読み込めます。gzで圧縮されているファイルにも対応しています。

Jun 14 15:16:01 combo sshd(pam_unix)[19939]: authentication failure; logname= uid=0 euid=0 tty=NODEVssh ruser= rhost=218.188.2.4

のようなファイルです。タイムスタンプは、魔法を使っていろんな形式に対応しています。昔のsyslogでもRFCで定義されている新しい形式でも、UNIXタイムの数値でもよいです。いくつもタイムスタンプがある場合は、一番左側にあるタイムスタンプを採用します。 SCPやSSHでサーバーから直接ログファイルを読み込むことができます。 TWSNMP FC/FKから読み込むこともできます。

シンプルフィルター

正規表現に精通しているなら正規表現のフィルターを使えばよいのですが、そうでない人のためにシンプルフィルターを用意しました。私のためでもあります。lsやdirコマンドで指定するや?で、何か文字列や文字があることを示します。 Messageのように書けば、正規表現のMessage.*になるようなものです。

$を書けば、そこで終わりという指定もできます。正規表現でIPアドレスのフィルターを指定する時は、

192.168.2.1

ではだめで

192\.168\.\2\.1

のような面倒なことになりますが、シンプルフィルターは、そのままかけます。コマンドのオプションで-fで指定します。ファイル名のパターンも、この方法です。正規表現は-rで指定します。 v1.1.0までは、-fと-rのフィルターはどちらか片方だけが有効な仕様でしたがv1.2.0以降は、両方のAND条件に変更しました。このほうが便利なので。 v1.6.0以降では、フィルターを引数で複数指定可能にしました。

v1.15.0以降では、キーワードに対応しました。

キーワード	内容
#IP	IPアドレスを含む
#IPV6	IPv6アドレスを含む
#MAC	MACアドレスを含む
#LOCAL_IP	ローカルIPアドレスを含む
#EMAIL	メールアドレスを含む
#URL	URLを含む
#CREDITCARD	クレジットカード番号を含む
#MYNUMBER	マイナンバーを含む
#PHONE_JP	日本の電話番号を含む
#PHONE_US	米国の電話番号を含む
#PHONE_INTL	国際電話番号を含む
#ZIP_JP	日本の郵便番号を含む
#UUID	UUIDを含む

除外フィルター

ログの中に不要な行がある時に、どんどん除外したい場合があります。grep の-vオプションと同じものをつけました。こちらは正規表現で指定します。引数で指定するフィルターの先頭を^にすると除外フィルターになります。

アバウトな時間範囲の指定

時間範囲の指定は、アバウトな入力にこだわっています。

2024/01/01T00:00:00+900-2024/01/02T00:00:00+900

のような入力を毎回するのは面倒です。これを

2024/1/1,1d

のような感じで入力できます。

開始,期間

開始,終了

終了,期間

の３パターンに対応しています。 -tオプションです。

データ抽出パターンの簡易な指定ログからデータを抽出する方法としてはGROKが有名ですが、覚えるのが面倒なので、簡易に指定できる方法をあみだしました。 -e オプションと-pオプションで指定します。 -eは、パターンで

Key	Description
ip	IPアドレス
ipv6	IPv6アドレス
mac	MACアドレス
number	数値
email	メールアドレス
creditcard	クレジットカード番号
mynumber	マイナンバー
phone_jp	日本の電話番号
phone_us	米国の電話番号
phone_intl	国際電話番号
zip_jp	日本の郵便番号
uuid	UUID
loc	位置情報
country	国コード
host	ホスト名
domain	ドメイン名

のように簡易な指定できます。locとcountryは、IP位置情報データベースが必要です。–geoip でファイルを指定します。 -pは位置です。 -p 2で２番目に発見したものを取り出します。IPアドレスが２つ以上ある場合に２番目のものを指定するとかです。もう少し複雑な指定もできます。

count=%{number}

のような形式です。シンプルフィルターの中に%{何か}のように書けば %{何か}の部分だけ取り出します。何かは、先程のipやemailの他にwordがあります。

GROKとJSONによるデータ抽出

v1.70からextractコマンド、countコマンドにGROKとJSONによるデータ抽出モードを追加しました。

Count the number of logs.
Number of logs per specified time
Number of occurrences of items extracted from the log

Usage:
  twsla count [flags]

Flags:
  -e, --extract string   Extract pattern
  -g, --grok string      grok pattern definitions
  -x, --grokPat string   grok pattern
  -h, --help             help for count
  -i, --interval int     Specify the aggregation interval in seconds.
  -n, --name string      Name of key (default "Key")
  -p, --pos int          Specify variable location (default 1)

Global Flags:
      --config string      config file (default is $HOME/.twsla.yaml)
  -d, --datastore string   Log DataStore path (.db, .badger, .parquet) (default "./twsla.db")
  -f, --filter string      Simple filter
  -v, --not string         Invert regexp filter
  -r, --regex string       Regexp filter
  -t, --timeRange string   Time range

GROKモード

-e オプションにgrokを指定するとgrokモードになります。この場合、-xオプションにGROKのパターンを指定する必要があります。-gオプションでGROKの定義を指定します。sigmaコマンドと同じ方法です。-nに抽出するデータ名を指定します。

$twsla count -x IP -n IP -e grok

のような感じです。以前からある

$twsla count -e ip

とほぼ同じ結果になります。でもGROKのほうが遅いです。GROKは複雑な抽出に使ったほうがよいです。

JSONモード

WindowsのイベントログやzeekのjsonログなどJSON形式で保存されたログは、JSONPATHで抽出できます。 -e オプションにjsonを指定して-nオプションにJSONPATHを指定します。

グラフの保存

countやextractコマンドの結果画面が保存を実行する時に拡張子をpngにすれば、結果をテキストファイルではなくグラフ画像として保存します。

グラフの表示

グラフを保存できるコマンドの表示中のgキーまたは、hキーをタイプするとグラフを表示できます。v1.9.0から起動パラメータに–sixelを指定するか環境変数にTWSLA_SIXEL=trueを指定すると、Sixelを使ってターミナル内にグラフを表示できます。

IP情報(DNS/GeoIP)の分析

ログの中のIPアドレスから国、都市、緯度経度などの位置情報、ホスト名、ドメイン名などの情報を取得して集計する機能です。 v1.8.0から対応しました。

–geoipでIP位置情報データベースのパスを指定します。 IP位置情報のデータベースファイルは

https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/

から入手してください。

–ip 取得するIP情報の種類を指定します。

Key	Description
host	ホスト名
domain	ドメイン名
loc	位置情報
country	国コード

に対応しています。locとcountryだけIP位置情報データベースが必須になります。

例えば、

$twsla count -e ip --ip country --geoip ~/Desktop/GeoLite2-City_20241119/GeoLite2-City.mmdb  Failed password

のように集計すると

のように集計できます。個々のIPアドレスではなく国別に集計できます。 locで集計すると

のような感じです。緯度経度が追加されて、都市名がわかる場合には、これも追加します。 domainで集計すると

です。DNSサーバーへ問い合わせるので、かなり遅いです。対象のログは、ログのサンプルサイトからダウンロードしたSSHサーバーのログです。ログイン失敗しているアクセス元のIPアドレスに関する情報がよくわかります。 extractコマンドもパラメータは同じです。同じログをlocで表示すると

設定ファイルと環境変数

v1.9.0から設定ファイルと環境変数に対応しました。

設定ファイル

–configで指定したファイルか、ホームディレクトリ/.twsla.yamlを設定ファイルとして使用します。 yaml形式です。以下のキーに対応しています。

Key	Description
timeRange	時間範囲
filter	シンプルフィルター
regex	正規表現フィルター
not	反転フィルター
extract	抽出パターン
name	変数名
grokPat
ip	IP情報モード
color	カラーモード
rules	Sigmaルールパス
sigmaConfig	Sigma設定
twsnmp	TWSNMP FCのURL
interval	集計間隔
jsonOut	JSON形式の出力
checkCert	サーバー証明書の検証
datastore	データストアのパス
geoip	GeoIPDBのパス
grok	GROK定義
sixel	グラフのターミナル内に表示

環境変数

以下の環境変数が利用できます。

Key	Description
TWSLA_DATASTORE	データストアのパス
TWSLA_GEOIP	GeoIPデータベースのパス
TWSLA_GROK	GROKの定義
TWSLA_SIXEL	グラフ表示にSixelを利用

説明に使ったログの入手

この説明に使ったサンプルのログを手に入れたい人は

https://github.com/logpai/loghub

のLinuxのフォルダにあるログです。

ビルド方法

ビルドには

https://taskfile.dev/

を利用します。

$task

Copyright

see ./LICENSE

Copyright 2024-2026 Masayuki Yamai