ファイルを保護して解析

Protect Mode では、コンテンツ管理 policy により、実行可能コード、対話型フォームコンテンツ、さまざまなアクション（例: 外部リンクや JavaScript の実行）など、各種ファイルコンテンツタイプを制御できます。これらのファイル要素は、ファイル内で検出された場合に一般的な攻撃ベクトルとなることが知られています。コンテンツ管理 policy は、Glasswall Embedded Engine がこれらの構造をどのように処理するかを定義します。Analysis Mode では、これらは SanitisationItems として報告されます。コンテンツ管理 policy は、サポートされるファイルタイプごとに異なります。

ファイルの再生成時には、ファイル仕様への自動修正も実行されます。その目的は、Glasswall Embedded Engine がファイル構造内に隠された脅威を除去できるようにするとともに、ファイル内の構造コンポーネントの誤用によってエクスプロイトが有効化される可能性を防ぐことです。Analysis Mode では、これらは RemedyItems として報告されます。

ファイルは、protect_file または protect_directory メソッドを使用して、ファイルパスから、またはメモリ内で個別に保護できます。

保護

ファイルパスからファイルパスへ保護

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to sanitise a file, writing the sanitised file to a new path
editor.protect_file(
    input_file=r"C:\gwpw\input\TestFile_11.doc",
    output_file=r"C:\gwpw\output\editor\protect_f2f\TestFile_11.doc",
)

ファイルパスからメモリへ保護

protect_file は保護されたファイルのバイト列を返します。以下の例では、変数 file_bytes への代入を示しています。サニタイズ後、file_bytes の先頭 8 バイトが、Microsoft Compound File Binary (CFB) 形式のファイルシグネチャである D0 CF 11 E0 A1 B1 1A E1 と一致していることがわかります。

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to sanitise a file in memory, returning the file bytes in memory
file_bytes = editor.protect_file(
    input_file=r"C:\gwpw\input\TestFile_11.doc"
)

assert file_bytes[:8] == b'\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1'

メモリから保護

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Read file from disk to memory
with open(r"C:\gwpw\input\TestFile_11.doc", "rb") as f:
    input_bytes = f.read()

# Use the default policy to sanitise a file
file_bytes = editor.protect_file(
    input_file=input_bytes,
)

assert file_bytes[:8] == b'\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1'

ディレクトリ内のファイルを保護

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to protect a directory of files, writing the sanitised files to a new directory.
editor.protect_directory(
    input_directory=r"C:\gwpw\input",
    output_directory=r"C:\gwpw\output\editor\protect_directory"
)

サポートされていないファイルタイプが含まれる可能性のあるディレクトリ内のファイルを保護

Glasswall Python ラッパーのデフォルトの動作では、処理に失敗した場合に該当する例外を発生させます（参照: glasswall.libraries.editor.errors）。raise_unsupported=False を渡すと例外の発生を防ぐことができ、サポート対象と非サポート対象のファイル形式が混在するディレクトリを扱う際に、最初の失敗で終了するのではなく、できるだけ多くのファイルを処理したい場合に便利です。

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to protect a directory of files, writing the sanitised files to a new directory.
editor.protect_directory(
    input_directory=r"C:\gwpw\input_with_unsupported_file_types",
    output_directory=r"C:\gwpw\output\editor\protect_directory_unsupported",
    raise_unsupported=False
)

カスタムコンテンツ管理policyを使用してディレクトリ内のファイルを保護する

glasswall.content_management.policies.Editor を使用:

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use a custom Editor policy to sanitise all files in the input directory
# and write them to the input_sanitised directory. If macros are present
# in ppt or word files, the file will be marked as non-conforming and blocked.
# If internal or external hyperlinks are present in word files they will not
# be sanitised, and will remain in the regenerated document.
editor.protect_directory(
    input_directory=r"C:\gwpw\input",
    output_directory=r"C:\gwpw\output\editor\protect_directory_custom",
    content_management_policy=glasswall.content_management.policies.Editor(
        default="sanitise",
        config={
            "pptConfig": {
                "macros": "disallow",
            },
            "wordConfig": {
                "internal_hyperlinks": "allow",
                "external_hyperlinks": "allow",
                "macros": "disallow",
            }
        }
    )
)

ファイル形式に基づいて条件付きでディレクトリ内のファイルを保護する

以下の例では、複数のファイル形式を含むネストされたディレクトリから、.doc および .docx ファイルのみを処理する方法を示します。

import os

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

input_directory = r"C:\gwpw\input"
output_directory = r"C:\gwpw\output\editor\protect_directory_file_format"

# Iterate relative file paths from input_directory
for relative_file in glasswall.utils.list_file_paths(input_directory, absolute=False):
    # Construct absolute paths
    input_file = os.path.join(input_directory, relative_file)
    output_file = os.path.join(output_directory, relative_file)

    # Get the file type of the file
    file_type = editor.determine_file_type(
        input_file=input_file,
        as_string=True,
        raise_unsupported=False
    )

    # Protect only doc and docx files
    if file_type in ["doc", "docx"]:
        editor.protect_file(input_file, output_file)

分析

Embedded Engine レポートは、データの詳細でファイルタイプに依存しない説明を提供し、XML 形式で記録されます。このレポートの構造は Analysis Report XSD に従っており、解析と処理を簡素化するよう設計されているため、データの統合と分析をより容易に行えます。Engine Reporting を参照してください。

ファイルは、analyse_file メソッドを使用してファイルパスまたはメモリ内から個別に解析でき、また、ディレクトリ内のすべてのファイルは analyse_directory メソッドを使用して解析できます。

ファイルパスからファイルパスへ分析する

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to analyse a file, writing the analysis report to a new path
editor.analyse_file(
    input_file=r"C:\gwpw\input\TestFile_11.doc",
    output_file=r"C:\gwpw\output\editor\analyse_f2f\TestFile_11.doc.xml",
)

ファイルパスからメモリへ分析する

analyse_file は分析レポート xml ファイルの bytes を返します。以下の例では、変数 analysis_report への代入と、Editor 分析レポートの先頭部分の内容を確認する方法を示します。

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to analyse a file
analysis_report = editor.analyse_file(
    input_file=r"C:\gwpw\input\TestFile_11.doc",
)

assert analysis_report[:500] == b'<?xml version="1.0" encoding="utf-8"?>\n<gw:GWallInfo xsi:schemaLocation="http://glasswall.com/namespace/gwallInfo.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:gw="http://glasswall.com/namespace">\n\t<gw:DocumentStatistics>\n\t\t<gw:DocumentSummary>\n\t\t\t<gw:TotalSizeInBytes>35840</gw:TotalSizeInBytes>\n\t\t\t<gw:FileType>doc</gw:FileType>\n\t\t\t<gw:Version>Not Applicable</gw:Version>\n\t\t\t<gw:InputSHA256>9FDE85B8800C1019D2865FA298A7F75873E09870B71F9825827E354B865686A6</gw:InputSHA256>\n\t\t\t<gw'

メモリから分析する

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Read file from disk to memory
with open(r"C:\gwpw\input\TestFile_11.doc", "rb") as f:
    input_bytes = f.read()

# Use the default policy to analyse a file
analysis_report = editor.analyse_file(
    input_file=input_bytes,
)

assert analysis_report[:500] == b'<?xml version="1.0" encoding="utf-8"?>\n<gw:GWallInfo xsi:schemaLocation="http://glasswall.com/namespace/gwallInfo.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:gw="http://glasswall.com/namespace">\n\t<gw:DocumentStatistics>\n\t\t<gw:DocumentSummary>\n\t\t\t<gw:TotalSizeInBytes>35840</gw:TotalSizeInBytes>\n\t\t\t<gw:FileType>doc</gw:FileType>\n\t\t\t<gw:Version>Not Applicable</gw:Version>\n\t\t\t<gw:InputSHA256>9FDE85B8800C1019D2865FA298A7F75873E09870B71F9825827E354B865686A6</gw:InputSHA256>\n\t\t\t<gw'

ディレクトリ内のファイルを解析する

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to analyse a directory of files, writing the analysis reports to a new directory.
editor.analyse_directory(
    input_directory=r"C:\gwpw\input",
    output_directory=r"C:\gwpw\output\editor\analyse_directory"
)

サポートされていないファイルタイプが含まれる可能性のあるディレクトリ内のファイルを解析する

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use the default policy to analyse a directory of files, writing the analysis reports to a new directory.
editor.analyse_directory(
    input_directory=r"C:\gwpw\input_with_unsupported_file_types",
    output_directory=r"C:\gwpw\output\editor\analyse_directory_unsupported",
    raise_unsupported=False
)

カスタムコンテンツ管理policyを使用してディレクトリ内のファイルをanalyseする

glasswall.content_management.policies.Editor を使用:

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

# Use a custom Editor policy to analyse all files in the input directory
# and write them to analyse_directory_custom directory. If macros are
# present in ppt or word files, a GeneralFail exception will be raised if the
# raise_unsupported argument is left at its default value of False, but the
# analysis report will still be written to file and will contain IssueItems.
# If internal or external hyperlinks are present in word files they will not
# be sanitised, and will remain in the regenerated document.
editor.analyse_directory(
    input_directory=r"C:\gwpw\input",
    output_directory=r"C:\gwpw\output\editor\analyse_directory_custom",
    content_management_policy=glasswall.content_management.policies.Editor(
        default="sanitise",
        config={
            "pptConfig": {
                "macros": "disallow",
            },
            "wordConfig": {
                "internal_hyperlinks": "allow",
                "external_hyperlinks": "allow",
                "macros": "disallow",
            }
        }
    ),
    raise_unsupported=False
)

ファイル形式に基づいて条件付きでディレクトリ内のファイルをanalyseする

以下の例では、複数のファイル形式を含むネストされたディレクトリから、.doc および .docx ファイルのみを処理する方法を示します。

import os

import glasswall


# Load the Glasswall Editor library
editor = glasswall.Editor(r"C:\gwpw\libraries\10.0")

input_directory = r"C:\gwpw\input"
output_directory = r"C:\gwpw\output\editor\analyse_directory_file_format"

# Iterate relative file paths from input_directory
for relative_file in glasswall.utils.list_file_paths(input_directory, absolute=False):
    # Construct absolute paths
    input_file = os.path.join(input_directory, relative_file)
    output_file = os.path.join(output_directory, relative_file + ".xml")

    # Get the file type of the file
    file_type = editor.determine_file_type(
        input_file=input_file,
        as_string=True,
        raise_unsupported=False
    )

    # Analyse only doc and docx files
    if file_type in ["doc", "docx"]:
        editor.analyse_file(input_file, output_file)

ProtectとAnalyse

これらの高水準関数を使用すると、単一のセッション内でAnalysisメソッドを伴うProtectを実行できます。詳細については、以下のドキュメントリンクを参照してください。

例​

保護​

ファイルパスからファイルパスへ保護​

ファイルパスからメモリへ保護​

メモリから保護​

ディレクトリ内のファイルを保護​

サポートされていないファイルタイプが含まれる可能性のあるディレクトリ内のファイルを保護​

カスタムコンテンツ管理policyを使用してディレクトリ内のファイルを保護する​

ファイル形式に基づいて条件付きでディレクトリ内のファイルを保護する​

分析​

ファイルパスからファイルパスへ分析する​

ファイルパスからメモリへ分析する​

メモリから分析する​

ディレクトリ内のファイルを解析する​

サポートされていないファイルタイプが含まれる可能性のあるディレクトリ内のファイルを解析する​

カスタムコンテンツ管理policyを使用してディレクトリ内のファイルをanalyseする​

ファイル形式に基づいて条件付きでディレクトリ内のファイルをanalyseする​

ProtectとAnalyse​

例

保護