MySQL 8.0 リファレンスマニュアル


6.4.5.8 監査ログフィルタ定義の書込み

フィルタ定義は JSON 値です。 MySQL での JSON データの使用の詳細は、セクション11.5「JSON データ型」 を参照してください。

フィルタ定義の形式は次のとおりです。ここで、actions はフィルタリングの実行方法を示します:

{ "filter": actions }

次の説明では、フィルタ定義で許可される構成要素について説明します。

すべてのイベントのロギング

すべてのイベントのロギングを明示的に有効または無効にするには、フィルタで log 要素を使用します:

{
  "filter": { "log": true }
}

log の値は、true または false のいずれかです。

前述のフィルタは、すべてのイベントのロギングを有効にします。 これは次と同等です:

{
  "filter": { }
}

ロギングの動作は、log の値、および class アイテムと event アイテムのどちらが指定されているかによって異なります:

  • log が指定されている場合は、指定された値が使用されます。

  • log が指定されていない場合、class または event アイテムが指定されていないとロギングは true になり、それ以外の場合は false になります (この場合、class または event に独自の log アイテムを含めることができます)。

ロギング固有のイベントクラス

特定のクラスのイベントをログに記録するには、ログに記録するクラスの名前を示す name フィールドとともに、フィルタで class 要素を使用します:

{
  "filter": {
    "class": { "name": "connection" }
  }
}

name の値は、それぞれ connectiongeneral または table_access で、接続、一般またはテーブルアクセスイベントをログに記録できます。

前述のフィルタは、connection クラスでのイベントのロギングを有効にします。 これは、明示的に作成された log アイテムの次のフィルタと同等です:

{
  "filter": {
    "log": false,
    "class": { "log": true,
               "name": "connection" }
  }
}

複数のクラスのロギングを有効にするには、クラスを指定する JSON 配列要素として class 値を定義します:

{
  "filter": {
    "class": [
      { "name": "connection" },
      { "name": "general" },
      { "name": "table_access" }
    ]
  }
}
注記

特定のアイテムの複数のインスタンスがフィルタ定義内の同じレベルに表示される場合、アイテム値を配列値内のそのアイテムの単一のインスタンスに結合できます。 前述の定義は、次のように記述できます:

{
  "filter": {
    "class": [
      { "name": [ "connection", "general", "table_access" ] }
    ]
  }
}
特定のイベントサブクラスのロギング

特定のイベントサブクラスを選択するには、サブクラスを指定する name アイテムを含む event アイテムを使用します。 event アイテムによって選択されたイベントのデフォルトのアクションは、それらをログに記録することです。 たとえば、このフィルタは、指定されたイベントサブクラスのロギングを有効にします:

{
  "filter": {
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect" },
          { "name": "disconnect" }
        ]
      },
      { "name": "general" },
      {
        "name": "table_access",
        "event": [
          { "name": "insert" },
          { "name": "delete" },
          { "name": "update" }
        ]
      }
    ]
  }
}

event 品目には、適格なイベントをログに記録するかどうかを示す明示的な log 品目を含めることもできます。 この event アイテムは、複数のイベントを選択し、それらのロギング動作を明示的に示します:

"event": [
  { "name": "read", "log": false },
  { "name": "insert", "log": true },
  { "name": "delete", "log": true },
  { "name": "update", "log": true }
]

event 項目に abort 項目が含まれている場合は、該当するイベントをブロックするかどうかも指定できます。 詳細は、特定のイベントの実行のブロックを参照してください。

表6.29「イベントクラスとサブクラスの組合せ」 は、各イベントクラスに許可されるサブクラス値を記述します。

表 6.29 イベントクラスとサブクラスの組合せ

イベントクラス イベントサブクラス 説明
接続 connect 接続の開始 (成功または失敗)
接続 change_user セッション中に異なるユーザー/パスワードでユーザーを再認証
接続 disconnect 接続の終了
general status 一般的な操作情報
message internal 内部で生成されたメッセージ
message user audit_api_message_emit_udf() によって生成されたメッセージ
table_access read SELECTINSERT INTO ... SELECT などのテーブル読取りステートメント
table_access delete DELETETRUNCATE TABLE などのテーブル削除ステートメント
table_access 挿入 INSERTREPLACE などのテーブル挿入ステートメント
table_access update UPDATE などのテーブル更新ステートメント

表6.30「イベントクラスとサブクラスの組合せごとのログおよび中断特性」 では、イベントサブクラスごとに、ログに記録できるか中断できるかが記述されます。

表 6.30 イベントクラスとサブクラスの組合せごとのログおよび中断特性

イベントクラス イベントサブクラス 記録可能 中断可能
接続 connect はい いいえ
接続 change_user はい いいえ
接続 disconnect はい いいえ
general status はい いいえ
message internal はい はい
message user はい はい
table_access read はい はい
table_access delete はい はい
table_access 挿入 はい はい
table_access update はい はい

包括的および排他的ロギング

フィルタは包含モードまたは排他モードで定義できます:

  • 包含モードでは、明示的に指定された項目のみが記録されます。

  • 排他モードでは、明示的に指定された項目以外はすべてログに記録されます。

包括的ロギングを実行するには、ロギングをグローバルに無効にし、特定のクラスのロギングを有効にします。 このフィルタは、connect および disconnect イベントを connection クラスに記録し、イベントを general クラスに記録します:

{
  "filter": {
    "log": false,
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect", "log": true },
          { "name": "disconnect", "log": true }
        ]
      },
      { "name": "general", "log": true }
    ]
  }
}

排他的ロギングを実行するには、ロギングをグローバルに有効にし、特定のクラスのロギングを無効にします。 このフィルタは、general クラスのイベントを除くすべてのログを記録します:

{
  "filter": {
    "log": true,
    "class":
      { "name": "general", "log": false }
  }
}

このフィルタは、他のすべてをログに記録しないことによって、change_user イベントを connection クラス、message イベントおよび table_access イベントに記録します:

{
  "filter": {
    "log": true,
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect", "log": false },
          { "name": "disconnect", "log": false }
        ]
      },
      { "name": "general", "log": false }
    ]
  }
}
イベントフィールド値のテスト

特定のイベントフィールド値に基づいてロギングを有効にするには、フィールド名と予想される値を示す field アイテムを log アイテム内で指定します:

{
  "filter": {
    "class": {
    "name": "general",
      "event": {
        "name": "status",
        "log": {
          "field": { "name": "general_command.str", "value": "Query" }
        }
      }
    }
  }
}

各イベントには、カスタムフィルタリングを実行するためにフィルタ内からアクセスできるイベントクラス固有のフィールドが含まれます。

接続イベントは、ユーザーがサーバーに接続したり、サーバーから切断したりするなど、セッション中に接続関連のアクティビティが発生したときを示します。表6.31「接続イベントフィールド」 は、接続イベントに許可されているフィールドを示します。

表 6.31 接続イベントフィールド

フィールド名 フィールドタイプ 説明
status 整数

イベントステータス:

0: OK

それ以外の場合: 失敗

connection_id unsigned integer 接続 ID
user.str 文字列 認証時に指定されたユーザー名
user.length unsigned integer ユーザー名の長さ
priv_user.str 文字列 認証されたユーザー名 (アカウントユーザー名)
priv_user.length unsigned integer 認証済ユーザー名の長さ
external_user.str 文字列 外部ユーザー名 (サードパーティの認証プラグインによって提供される)
external_user.length unsigned integer 外部ユーザー名の長さ
proxy_user.str 文字列 プロキシユーザー名
proxy_user.length unsigned integer プロキシユーザー名の長さ
host.str 文字列 接続ユーザーホスト
host.length unsigned integer 接続ユーザーホストの長さ
ip.str 文字列 接続ユーザーの IP アドレス
ip.length unsigned integer 接続ユーザーの IP アドレスの長さ
database.str 文字列 接続時に指定されたデータベース名
database.length unsigned integer データベース名長
connection_type 整数

接続タイプ:

または"::undefined" : 未定義

または"::tcp/ip" : TCP/IP

または"::socket" : Socket

または"::named_pipe" : 名前付きパイプ

または"::ssl" : 暗号化を使用した TCP/IP

または"::shared_memory" : 共有メモリー


"::xxx"値は、リテラルの数値のかわりに指定できるシンボリック擬似定数です。 これらは文字列として引用符で囲む必要があり、大/小文字が区別されます。

一般イベントは、操作のステータスコードとその詳細を示します。表6.32「一般イベントフィールド」 は、一般イベントに許可されているフィールドを示します。

表 6.32 一般イベントフィールド

フィールド名 フィールドタイプ 説明
general_error_code 整数

イベントステータス:

0: OK

それ以外の場合: 失敗

general_thread_id unsigned integer 接続/スレッド ID
general_user.str 文字列 認証時に指定されたユーザー名
general_user.length unsigned integer ユーザー名の長さ
general_command.str 文字列 コマンド名
general_command.length unsigned integer コマンド名長
general_query.str 文字列 SQL ステートメントテキスト
general_query.length unsigned integer SQL ステートメントのテキスト長
general_host.str 文字列 ホスト名
general_host.length unsigned integer ホスト名長
general_sql_command.str 文字列 SQL コマンドタイプ名
general_sql_command.length unsigned integer SQL コマンドタイプ名の長さ
general_external_user.str 文字列 外部ユーザー名 (サードパーティの認証プラグインによって提供される)
general_external_user.length unsigned integer 外部ユーザー名の長さ
general_ip.str 文字列 接続ユーザーの IP アドレス
general_ip.length unsigned integer 接続ユーザー IP アドレスの長さ

general_command.str はコマンド名を示します: Query, Execute, Quit または Change user

general_command.str フィールドが Query または Execute に設定された一般イベントには、SQL コマンドのタイプを指定する値に設定された general_sql_command.str が含まれます: alter_db, alter_db_upgrade, admin_commands など。 これらの値は、次のステートメントによって表示されるパフォーマンススキーマインストゥルメントの最後のコンポーネントとして表示できます:

mysql> SELECT NAME FROM performance_schema.setup_instruments
       WHERE NAME LIKE 'statement/sql/%' ORDER BY NAME;
+---------------------------------------+
| NAME                                  |
+---------------------------------------+
| statement/sql/alter_db                |
| statement/sql/alter_db_upgrade        |
| statement/sql/alter_event             |
| statement/sql/alter_function          |
| statement/sql/alter_instance          |
| statement/sql/alter_procedure         |
| statement/sql/alter_server            |
...

テーブルアクセスイベントは、特定のテーブルアクセスに関する情報を提供します。表6.33「テーブルアクセスイベントフィールド」 は、テーブルアクセスイベントに許可されているフィールドを示します。

表 6.33 テーブルアクセスイベントフィールド

フィールド名 フィールドタイプ 説明
connection_id unsigned integer イベント接続 ID
sql_command_id 整数 SQL コマンド ID
query.str 文字列 SQL ステートメントテキスト
query.length unsigned integer SQL ステートメントのテキスト長
table_database.str 文字列 イベントに関連付けられたデータベース名
table_database.length unsigned integer データベース名長
table_name.str 文字列 イベントに関連付けられたテーブル名
table_name.length unsigned integer テーブル名の長さ

次のリストに、どのステートメントがどのテーブルアクセスイベントを生成するかを示します:

  • read イベント:

    • SELECT

    • INSERT ... SELECT (SELECT 句で参照されるテーブルの場合)

    • REPLACE ... SELECT (SELECT 句で参照されるテーブルの場合)

    • UPDATE ... WHERE (WHERE 句で参照されるテーブルの場合)

    • HANDLER ... READ

  • delete イベント:

    • DELETE

    • TRUNCATE TABLE

  • insert イベント:

    • INSERT

    • INSERT ... SELECT (INSERT 句で参照されるテーブルの場合)

    • REPLACE

    • REPLACE ... SELECT (REPLACE 句で参照されるテーブルの場合)

    • LOAD DATA

    • LOAD XML

  • update イベント:

    • UPDATE

    • UPDATE ... WHERE (UPDATE 句で参照されるテーブルの場合)

特定のイベントの実行のブロック

event 品目には、適格イベントが実行されないようにするかどうかを示す abort 品目を含めることができます。 たとえば、abort では、特定の SQL ステートメントの実行をブロックするルールを記述できます。

abort 品目は、event 品目内に表示される必要があります。 例:

"event": {
  "name": qualifying event subclass names
  "abort": condition
}

name アイテムによって選択されたイベントサブクラスの場合、abort アクションは condition 評価に応じて true または false です。 条件が true と評価された場合、イベントはブロックされます。 それ以外の場合、イベントは引き続き実行されます。

condition 仕様は、true または false のように単純にすることも、イベント特性に依存するようにより複雑にすることもできます。

このフィルタは、INSERTUPDATE および DELETE ステートメントをブロックします:

{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "insert", "update", "delete" ],
        "abort": true
      }
    }
  }
}

この複雑なフィルタは、特定のテーブル (finances.bank_account) に対してのみ同じステートメントをブロックします:

{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "insert", "update", "delete" ],
        "abort": {
          "and": [
            { "field": { "name": "table_database.str", "value": "finances" } },
            { "field": { "name": "table_name.str", "value": "bank_account" } }
          ]
        }
      }
    }
  }
}

フィルタによって一致およびブロックされたステートメントは、クライアントにエラーを返します:

ERROR 1045 (28000): Statement was aborted by an audit log filter

すべてのイベントをブロックできるわけではありません (表6.30「イベントクラスとサブクラスの組合せごとのログおよび中断特性」 を参照)。 できないイベントの場合、監査ログは警告をブロックするのではなく、エラーログに書き込みます。

abort アイテムが event アイテム以外の場所に表示されるフィルタを定義しようとすると、エラーが発生します。

論理演算子

論理演算子 (and, or, not) は、log アイテムで使用できます。 これにより、より高度なフィルタリング構成を構築できます:

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "or": [
            {
              "and": [
                { "field": { "name": "general_command.str",    "value": "Query" } },
                { "field": { "name": "general_command.length", "value": 5 } }
              ]
            },
            {
              "and": [
                { "field": { "name": "general_command.str",    "value": "Execute" } },
                { "field": { "name": "general_command.length", "value": 7 } }
              ]
            }
          ]
        }
      }
    }
  }
}
事前定義変数の参照

log 条件で事前定義済の変数を参照するには、特定の値と等しいかどうかをテストする variable アイテムを使用します:

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "variable": {
            "name": "audit_log_connection_policy_value", "value": "::none"
          }
        }
      }
    }
  }
}

事前定義された各変数は、システム変数に対応します。 事前定義された変数をテストするフィルタを記述することで、フィルタを再定義しなくても、対応するシステム変数を設定してフィルタ操作を変更できます。 たとえば、audit_log_connection_policy_value の事前定義済変数の値をテストするフィルタを記述することで、audit_log_connection_policy システム変数の値を変更することでフィルタ操作を変更できます。

audit_log_xxx_policy システム変数は、レガシーモードの監査ログに使用されます (セクション6.4.5.9「レガシーモード監査ログのフィルタリング」 を参照)。 ルールベースの監査ログフィルタリングでは、これらの変数は表示されたままになりますが (たとえば、SHOW VARIABLES を使用して)、変数を参照する構成を含むフィルタを記述しないかぎり、変更は効果がありません。

次のリストでは、variable 品目に許可されている事前定義済変数について説明します:

  • audit_log_connection_policy_value

    この変数は、audit_log_connection_policy システム変数の値に対応します。 値は符号なし整数です。表6.34「audit_log_connection_policy_value の値」 には、許可された値および対応する audit_log_connection_policy 値が表示されます。

    表 6.34 audit_log_connection_policy_value の値

    対応する audit_log_connection_policy 値
    0 または"::none" NONE
    1 または"::errors" ERRORS
    2 または"::all" ALL

    "::xxx"値は、リテラルの数値のかわりに指定できるシンボリック擬似定数です。 これらは文字列として引用符で囲む必要があり、大/小文字が区別されます。

  • audit_log_policy_value

    この変数は、audit_log_policy システム変数の値に対応します。 値は符号なし整数です。表6.35「audit_log_policy_value の値」 には、許可された値および対応する audit_log_policy 値が表示されます。

    表 6.35 audit_log_policy_value の値

    対応する audit_log_policy 値
    0 または"::none" NONE
    1 または"::logins" LOGINS
    2 または"::all" ALL
    3 または"::queries" QUERIES

    "::xxx"値は、リテラルの数値のかわりに指定できるシンボリック擬似定数です。 これらは文字列として引用符で囲む必要があり、大/小文字が区別されます。

  • audit_log_statement_policy_value

    この変数は、audit_log_statement_policy システム変数の値に対応します。 値は符号なし整数です。表6.36「audit_log_statement_policy_value の値」 には、許可された値および対応する audit_log_statement_policy 値が表示されます。

    表 6.36 audit_log_statement_policy_value の値

    対応する audit_log_statement_policy 値
    0 または"::none" NONE
    1 または"::errors" ERRORS
    2 または"::all" ALL

    "::xxx"値は、リテラルの数値のかわりに指定できるシンボリック擬似定数です。 これらは文字列として引用符で囲む必要があり、大/小文字が区別されます。

事前定義関数の参照

log 条件で事前定義済関数を参照するには、function アイテムを使用します。このアイテムは、name および args の値を使用して、関数名とその引数をそれぞれ指定します:

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "function": {
            "name": "find_in_include_list",
            "args": [ { "string": [ { "field": "user.str" },
                                    { "string": "@"},
                                    { "field": "host.str" } ] } ]
          }
        }
      }
    }
  }
}

name 項目に指定されている関数は、カッコや引数リストを含まない関数名のみである必要があります。 args アイテムに引数がある場合は、関数の説明にリストされている順序で引数を指定する必要があります。 引数は、事前定義済の変数、イベントフィールド、文字列定数または数値定数を参照できます。

前述のフィルタは、現在のユーザーが audit_log_include_accounts システム変数で見つかったかどうかに応じて、general クラスの status イベントをログに記録するかどうかを決定します。 そのユーザーは、イベントのフィールドを使用して作成されます。

次のリストでは、function 品目に許可されている事前定義済関数について説明します:

  • audit_log_exclude_accounts_is_null()

    audit_log_exclude_accounts システム変数が NULL かどうかを確認します。 この関数は、レガシー監査ログの実装に対応するフィルタを定義する場合に役立ちます。

    引数:

    なし

  • audit_log_include_accounts_is_null()

    audit_log_include_accounts システム変数が NULL かどうかを確認します。 この関数は、レガシー監査ログの実装に対応するフィルタを定義する場合に役立ちます。

    引数:

    なし

  • debug_sleep(millisec)

    指定されたミリ秒数スリープします。 この関数は、パフォーマンス測定時に使用されます。

    debug_sleep() はデバッグビルドにのみ使用できます。

    引数:

    • millisec: スリープするミリ秒数を指定する符号なし整数。

  • find_in_exclude_list(account)

    アカウント文字列が監査ログ除外リスト (audit_log_exclude_accounts システム変数の値) に存在するかどうかを確認します。

    引数:

    • account: ユーザーアカウント名を指定する文字列。

  • find_in_include_list(account)

    アカウント文字列が監査ログインクルードリスト (audit_log_include_accounts システム変数の値) に存在するかどうかを確認します。

    引数:

    • account: ユーザーアカウント名を指定する文字列。

  • string_find(text, substr)

    substr 値が text 値に含まれているかどうかを確認します。 この検索では大文字と小文字が区別されます。

    引数:

    • text: 検索するテキスト文字列。

    • substr: text で検索する部分文字列。

ユーザーフィルタの置換

場合によっては、フィルタ定義を動的に変更できます。 これを行うには、既存の filter 内で filter 構成を定義します。 例:

{
  "filter": {
    "id": "main",
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "update", "delete" ],
        "log": false,
        "filter": {
          "class": {
            "name": "general",
            "event" : { "name": "status",
                        "filter": { "ref": "main" } }
          },
          "activate": {
            "or": [
              { "field": { "name": "table_name.str", "value": "temp_1" } },
              { "field": { "name": "table_name.str", "value": "temp_2" } }
            ]
          }
        }
      }
    }
  }
}

サブフィルタ内の activate 要素が true と評価されると、新しいフィルタがアクティブ化されます。 最上位の filter での activate の使用は許可されていません。

サブフィルタ内の ref アイテムを使用して元のフィルタ id を参照することで、新しいフィルタを元のフィルタに置き換えることができます。

表示されるフィルタは次のように動作します:

  • main フィルタは、update または delete のいずれかの table_access イベントを待機します。

  • temp_1 または temp_2 テーブルで update または deletetable_access イベントが発生した場合、フィルタは内部イベントに置き換えられます (明示的に参照する必要がないため、id はありません)。

  • コマンドの終了が通知されると (general / status イベント)、エントリが監査ログファイルに書き込まれ、フィルタが main フィルタに置き換えられます。

このフィルタは、次のような temp_1 または temp_2 テーブルに対して更新または削除を行うステートメントをログに記録する場合に役立ちます:

UPDATE temp_1, temp_3 SET temp_1.a=21, temp_3.a=23;

このステートメントでは複数の table_access イベントが生成されますが、監査ログファイルには general / status エントリのみが含まれます。

注記

定義で使用されている id 値は、その定義に対してのみ評価されます。 これらは、audit_log_filter_id システム変数の値とは関係ありません。


関連キーワード:  イベント, フィルタ, general, 定義, 変数, 接続, audit, ログ, event, ロギング