Analyzing files

FileAnalysis is the entry point for sending a file or hash to Intezer Analyze, polling for results, and inspecting sub-analyses.

Submit a file and wait for the verdict

from pprint import pprint
from intezer_sdk import api
from intezer_sdk.analysis import FileAnalysis

api.set_global_api('<api_key>')

analysis = FileAnalysis(file_path='/path/to/sample.exe')
analysis.send(wait=True)
pprint(analysis.result())

Submit asynchronously

When wait=False (the default), send() returns immediately. Poll with wait_for_completion() or check_status().

import datetime

analysis = FileAnalysis(file_path='/path/to/sample.exe')
analysis.send()

# Block with a timeout, raising TimeoutError if the analysis is not finished.
analysis.wait_for_completion(timeout=datetime.timedelta(minutes=5))
pprint(analysis.result())

The wait pattern

There are three equivalent ways to wait for an analysis to finish; pick whichever fits the surrounding flow:

import datetime

# 1. Send and block until done.
analysis = FileAnalysis(file_path='/path/to/sample.exe')
analysis.send(wait=True)

# 2. Send and block until done, with a timeout.
analysis = FileAnalysis(file_path='/path/to/sample.exe')
analysis.send(wait=True, wait_timeout=datetime.timedelta(minutes=2))

# 3. Send asynchronously, do other work, then wait separately.
analysis = FileAnalysis(file_path='/path/to/sample.exe')
analysis.send()
...  # do other work
analysis.wait_for_completion(timeout=datetime.timedelta(minutes=2))

All three raise TimeoutError when the timeout elapses. The same pattern applies to UrlAnalysis and EndpointAnalysis.

Submit by hash

If the file has already been seen by Intezer you can analyze it by sha256 without uploading the bytes. If the hash is unknown, HashDoesNotExistError is raised.

from intezer_sdk import errors

try:
    analysis = FileAnalysis(file_hash='<sha256>')
    analysis.send(wait=True)
except errors.HashDoesNotExistError:
    # Fall back to uploading the bytes.
    analysis = FileAnalysis(file_path='/path/to/sample')
    analysis.send(wait=True)

Reuse the latest analysis

Skip re-analysis when a recent result already exists:

analysis = FileAnalysis.from_latest_hash_analysis(file_hash='<sha256>')
if analysis is None:
    print('No prior analysis — submit one explicitly.')
else:
    pprint(analysis.result())

Inspect sub-analyses

Composed files (archives, installers, packed binaries, …) yield a tree of SubAnalysis objects after the parent finishes:

analysis = FileAnalysis(file_path='/path/to/installer.msi')
analysis.send(wait=True)

for sub_analysis in analysis.get_sub_analyses():
    print(sub_analysis.sha256, sub_analysis.source)
    print(sub_analysis.code_reuse)
    print(sub_analysis.metadata)

Use get_root_analysis() to access the root sub-analysis directly.

Submission options

Common keyword arguments for FileAnalysis:

• disable_dynamic_unpacking — skip dynamic unpacking.

• disable_static_unpacking — skip static unpacking.

• code_item_type — one of CodeItemType (e.g. file, memory_module).

• zip_password — password used to extract a zipped sample.

• sandbox_command_line_arguments — arguments passed to the sample inside the sandbox.

• file_name — display name to use in Intezer Analyze.

See intezer_sdk.analysis.FileAnalysis for the full signature.