注目の機能: ファイルベースのルールの置換

このドキュメントでは、機密値 (パスワード、API キー、トークン) を保持する方法について説明します。 FUZZY_MAP_pre / FUZZY_MAP ソース コードと Git 履歴から、 ハードコーディングする代わりに、実行時に別のファイルからテキストを「置換」します。

これは、マップが表示されないライブストリームまたは画面共有中に特に便利です。 ソース コード自体は表示される場合がありますが、参照されるファイルは表示されません。

1. コンセプト

通常、ルールの「replacement」フィールドはリテラルの出力テキストです。

('my-secret-value', r'^(trigger)$', 85, {'command_flags': re.IGNORECASE})

ファイルベースの置換が有効な場合、「replacement」値は 設定されたプレフィックス (デフォルトでは - または .) は、代わりに ファイル名 として扱われます。 Aura は、プラグイン自身のディレクトリを基準にしてそのファイル名を解決し、そのファイルを読み取ります。 コンテンツを作成し、そのコンテンツを置換テキストとして使用します。

('-api_key.txt', r'^(show api key)$', 85, {'command_flags': re.IGNORECASE})

api_key.txt がプラグインの FUZZY_MAP_pre.py の隣に存在する場合、その (削除された) コンテンツが置き換えとして使用されます。ファイルが存在しない場合、リテラル 代わりに文字列 -api_key.txt が返されます (フェイルセーフ: 偶発的な漏洩はありません) 「ファイルが見つかりません」というメッセージが使用可能なテキストとして表示され、クラッシュは発生しません）。

2. 設定

config/settings.py (ローカルの場合は config/settings_local.py) で設定します オーバーライド):

設定

タイプ

デフォルト

説明

FILE4REPLACEMENT_USE

ブール

本当です

機能全体のマスタースイッチ。 「False」の場合、「replacement」は常に文字通りに使用されます。

FILE4REPLACEMENT_ALLOWED_PREFIXES

タプル[str]

('-', '.')

ファイル検索をトリガーするには、「replacement」値がこれらの接頭辞のいずれかで始まる必要があります。空/なし = 文字で始まらない値は、潜在的なファイル名として扱われます。

FILE4REPLACEMENT_ALLOW_PATH_TRAVERSAL

ブール

偽

「True」の場合、プラグイン自身のディレクトリの外側にあるファイルの解決が許可されます (例: 絶対パス、または ../ シーケンス)。以下の「セキュリティ」セクションを参照してください。

FILE4REPLACEMENT_DENY_PREFIXES

タプル[str]

例えば('/etc', '/proc', '/dev', '/var/lib', '/root', 'C:\\Windows', 'C:\\Program Files')

これらのいずれかで始まる解決された絶対パスは、「FILE4REPLACEMENT_ALLOW_PATH_TRAVERSAL」に関係なく常に拒否されます。システム ディレクトリに対するハード セキュリティ境界。

3. パスの解決

ファイルは次のように解決されます。

  1. プラグインの source_path (マップ ローダーによって自動的に記録される) は次のとおりです。 SL5NET_AURA_PROJECT_ROOT に対して結合されました (SL5NET_AURA_PROJECT_ROOT から読み取ります) 環境変数) を使用してプラグインのディレクトリを取得します。

  2. 「replacement」値がそのディレクトリに結合されます。

  3. FILE4REPLACEMENT_ALLOW_PATH_TRAVERSAL が True でない限り、解決されたパス プラグインのディレクトリ内に存在する必要があります。そうでない場合、検索は拒否されます。

  4. 上記に関係なく、次のエントリで始まる解決されたパスはすべて FILE4REPLACEMENT_DENY_PREFIXES は常に拒否されます。

  5. ファイルが存在する場合は、その削除されたコンテンツが返されます。それ以外の場合は、 元の「置換」文字列が変更されずに返されます。

4. セキュリティに関する注意事項

  • 理解している場合のみ、「FILE4REPLACEMENT_ALLOW_PATH_TRAVERSAL」を有効にしてください。 意味: FUZZY_MAP_pre ファイルを編集できるすべてのユーザーが許可されます (例: オンライン マップ エディターを介して)、Aura プロセスが実行できる任意のファイルを読み取ります。 にアクセスし、そのコンテンツをライブ出力テキストとして表示します。

  • FILE4REPLACEMENT_DENY_PREFIXES は、 パストラバーサルが許可されている場合でも、共通のシステムディレクトリは使用されますが、 そもそもマップ ファイルを編集できるユーザーを制限する代わりにはなりません。

  • 参照ファイルはディスク上ではプレーンテキストです。 OSのファイルと組み合わせる コンテンツが機密性の高い場合は許可を与えます。

5. 例

プラグインの実際のサンプルについては、「config/maps/plugins/TEST_FILE4REPLACEMENT/」を参照してください。 および、実行するテスト スクリプトの「tools/tests/TEST_FILE4REPLACEMENT.sh」 ディレクトリ内検索とプラグイン ディレクトリ外の検索の両方です。

# config/maps/plugins/TEST_FILE4REPLACEMENT/de-DE/FUZZY_MAP_pre.py
FUZZY_MAP_pre = [
    ('.Zebra.txt', r'^(Zebra)$', 85, {'command_flags': re.IGNORECASE}),
]

このファイルの隣に、必要な置換テキストを含む .Zebra.txt を作成し、 「s Zebra」と言う (またはコンソールから入力する) とトリガーします。