Aether

Evidenzbasierte Binär- und Firmware-Analyse.

Aether setzt auf ausgereiften Engines auf — Ghidra headless, binwalk — und trägt das bei, was ihnen fehlt: ein Projektmodell, in dem jede Erkenntnis eine strukturierte Behauptung ist, die mit den exakten Artefakten verknüpft ist, die sie stützen.

Freitext-Sicherheitsbehauptungen sind hier nicht nur verpönt. Sie sind unrepräsentierbar. Eine Behauptung ist ein registriertes Prädikat mit typisierten Feldern, und sie kann nicht ohne Artefakt-IDs der Art gespeichert werden, die dieses Prädikat verlangt. Ein Agent, der versucht, „das sieht ausnutzbar aus" zu schreiben, erhält einen Schemafehler, der das fehlerhafte Feld benennt.

Aether baut keinen Disassembler und keinen Decompiler, und das wird es auch nie tun. Diese Arbeit ist bereits gut gemacht; die Lücke ist alles drumherum.

Status: Phase 0 abgeschlossen

Alle 25 Gate-Checks bestehen, 172 Tests bestehen.

python examples/demo_phase0.py

  [PASS] ELF identified with architecture and word size
  [PASS] functions, xrefs, and decompilation imported
  [PASS] Ghidra converged onto existing artifacts instead of duplicating
  [PASS] nested container chain unpacked (uImage -> gzip -> cpio)
  [PASS] findings attributed to the member file, not the container blob
  [PASS] claim resolves to a string artifact at a concrete location
  [PASS] free-text claim from an agent is refused
  [PASS] two independent analyses produce byte-identical graphs
  [PASS] suite 'elf_sample' passes  -  recall 1.00, 0 false positive(s)
  ...
  25/25 gate checks passed

Die Phasen 1–3 (Natural-Language-Modus, Multi-Agent-Orchestrierung, Firmware- Kartografie) sind bewusst nicht gestartet. Das Evidenzmodell muss bewiesen werden, bevor etwas darauf aufgebaut wird.

Related MCP server: pyghidra-mcp

Was heute funktioniert

Die beiden „noch nicht ausgeführt"-Zeilen werden klar angegeben, weil sie wichtig sind. Die Übersetzungsebenen auf beiden Seiten sind vollständig getestet; was nicht ausgeführt wurde, ist der Subprozess-Aufruf, weil keine der beiden Engines auf der Maschine installiert ist, auf der Phase 0 aufgebaut wurde. Siehe Vollständige Engines aktivieren.

Schnellstart

Python 3.10+ und keine Laufzeitabhängigkeiten. Nichts zu installieren:

git clone https://github.com/n-3-0-l-d-3-v/aether-platform.git
cd aether-platform
python examples/demo_phase0.py

Direkt mit einem Projekt arbeiten:

python cli/aether.py init ./work
python cli/aether.py -P ./work analyze examples/demo_firmware.bin
python cli/aether.py -P ./work query objects
python cli/aether.py -P ./work query claims --predicate contains_hardcoded_secret
python cli/aether.py -P ./work query claim clm_1284ca2d2406
python cli/aether.py -P ./work export ./work/export

Beispiel-Binärdateien werden generiert, nicht eingecheckt. examples/demo_phase0.py und die Testsuite bauen sie bei Bedarf; um sie von Hand zu bauen:

python examples/src/build_elf_sample.py examples/firmware_agent.elf
python examples/src/build_firmware_sample.py examples/demo_firmware.bin

Die Installation setzt aether auf den PATH:

pip install -e .
aether doctor

Tests ausführen

python -m pytest              # 172 tests
python -m pytest -q tests/test_evidence_model.py   # the invariants alone

Die Suite generiert ihre eigenen Beispiel-Binärdateien beim ersten Lauf. PE-spezifische Tests überspringen sauber auf Hosts, die kein PE erzeugen können – beachten Sie, dass ein nativer gcc unter Linux die Beispiel-Datei in ein ELF kompiliert, also das Vorhandensein eines Compilers nicht ausreicht und die Ausgabe auf einen MZ-Header geprüft wird. Installieren Sie einen mingw-w64-Cross-Compiler für PE-Abdeckung unter Linux.

CI führt die Suite, die Gate-Demonstration, einen Export-Determinismus-Check und die Evaluierungs-Suiten auf Linux, Windows und macOS mit Python 3.10 und 3.12 aus.

So sieht es aus

$ aether analyze demo_firmware.bin
[binwalk] run run_e65361591a1e...
  engine aether-carver   extracted 7 file(s)
    bin/diagnostics.exe                    pe          132.4 KiB
    bin/firmware_agent                     elf         1.8 KiB
    etc/dropbear/dropbear_rsa_host_key.pem certificate 196 B
    etc/telemetry.conf                     data        219 B

$ aether query claims --predicate contains_hardcoded_secret
id                predicate                  conf  prod  ev  subject             statement
----------------  -------------------------  ----  ----  --  -----------------  --------------------
clm_1284ca2d2406  contains_hardcoded_secret  0.95  1     1   etc/telemetry.conf  {"detector": "rul...
clm_0217e368bbeb  contains_hardcoded_secret  0.98  1     1   etc/dropbear/dro..  {"detector": "rul...

$ aether query claim clm_1284ca2d2406
claim   clm_1284ca2d2406f45deb3f680afb7914f5
schema  aether.claim.contains_hardcoded_secret/1
stated  {"detector": "rule:github-token", "redacted_preview": "ghp_****", "secret_kind": "api_token"}
conf    0.95 (max 0.95 across 1 producer(s))

evidence
role   kind    addr  artifact          name
-----  ------  ----  ----------------  ----------------------------------------
locus  string  0x56  art_6a75100355c5  api_key=ghp_A1b2C3d4E5f6G7h8I9j0K1l2...

Jede Erkenntnis führt zurück zu Bytes. Das ist der ganze Punkt.

Das Modell

Drei Datensatztypen tragen alles.

Artefakt — ein konkretes, lokalisierbares Beweisstück: eine Datei, eine Funktion, ein String, ein Xref, eine Sektion, ein dekompilierter Körper, ein Signaturtreffer. Seine ID ist ein Hash seiner Identitätsfelder nur, sodass die Anreicherung eines Artefakts seine ID nie ändert, und zwei Engines, die dasselbe beobachten, landen in derselben Zeile.

Behauptung — eine strukturierte Aussage: ein registriertes Prädikat, typisierte Felder und die Artefakte, die sie in benannten Rollen stützen (locus, support, context, counter). Sie trägt keinen Produzenten und keinen Zeitstempel, sodass dieselbe Aussage von zwei Engines eine Behauptung ist.

Attestierung — ein Produzent, der hinter einer Behauptung zu einem Zeitpunkt steht, mit einer Konfidenz. Konfidenz ist nie eine Eigenschaft einer Behauptung; sie wird aus den Attestierungen abgeleitet — Maximum innerhalb eines Produzenten, Noisy-OR über unabhängige Produzenten. Zwei Engines, die mit 0,9 übereinstimmen, ergeben 0,99, nicht zwei fast duplizierte Erkenntnisse.

Diese Trennung ist die zentrale Designentscheidung: ADR 0003.

Was erzwungen wird, nicht nur empfohlen

Freitext hat genau ein Zuhause: Annotationen, in ihrer eigenen Tabelle und ihrem eigenen Exportstrom, wo sie nie mit Erkenntnissen verwechselt werden können.

Vollständige Engines aktivieren

Aether läuft ohne Ghidra oder binwalk, mit reduzierter Tiefe, und sagt das. aether doctor berichtet, was fehlt und was jede Lücke kostet:

$ aether doctor
aether 0.1.0  (python 3.12.2)

  ok      triage     0.1.0        built in; no external engine required
  MISSING ghidra     unknown      analyzeHeadless was not found
  MISSING binwalk    unknown      binwalk was not found on PATH

Ghidra

Bietet Funktionsrekonstruktion, Querverweise, Dekompilierung und präzise lokalisierte Strings. Ohne sie läuft die Header-Level-Triage trotzdem.

1. Installieren Sie Ghidra (11.x empfohlen).

2. Installieren Sie ein JDK 21 oder neuer und stellen Sie sicher, dass java auf PATH ist, oder setzen Sie JAVA_HOME. Ghidra headless startet sonst nicht.

3. Weisen Sie Aether auf die Installation hin:

   export GHIDRA_INSTALL_DIR=/opt/ghidra_11.1.2_PUBLIC     # Linux/macOS
   setx GHIDRA_INSTALL_DIR "C:\ghidra_11.1.2_PUBLIC"       # Windows

   AETHER_GHIDRA_HOME und GHIDRA_HOME werden ebenfalls berücksichtigt, und support/analyzeHeadless auf PATH funktioniert auch. Wenn all das fehlschlägt, prüft Aether die üblichen Installationsverzeichnisse.

4. Verifizieren und ausführen:

   aether doctor
   aether -P ./work analyze ./target.elf --engine ghidra

Sie benötigen Ghidra nicht lokal, um Ghidra-Ergebnisse zu nutzen. Die Brücke trennt Ausführen vom Importieren, sodass ein auf einer beliebigen Maschine erzeugter Export überall importiert werden kann:

# on the machine that has Ghidra
analyzeHeadless /tmp/proj aether -import target.elf \
    -scriptPath aether/adapters/ghidra/scripts \
    -postScript AetherExport.py /tmp/export 40 "" -deleteProject

# anywhere
aether -P ./work import-ghidra /tmp/export --target ./target.elf

AetherExport.py läuft in Ghidras eigenem Interpreter (Jython 2.7 oder CPython unter PyGhidra) und bleibt in der Teilmenge, die beide akzeptieren.

binwalk

Bietet squashfs, jffs2, ubifs und Herstellerformate. Ohne sie behandelt der eingebaute Carver gzip, bzip2, xz, zip, tar und cpio und meldet alles, was er nur lokalisieren konnte, anstatt es still zu überspringen.

pip install binwalk
# or: https://github.com/ReFirmLabs/binwalk

Die vollständige Extraktion benötigt außerdem sasquatch, jefferson und ubi_reader, die unter Windows unhandlich sind — der Grund, warum der Fallback-Carver existiert (ADR 0005).

MCP

Der MCP-Server ist die Schnittstelle, gegen die zukünftige Agenten arbeiten, und er ist ein Peer der CLI — beide sind dünne Frontends über einer Bibliothek.

aether mcp              # stdio JSON-RPC
aether mcp --read-only  # hide and refuse every write tool

Fünfzehn Tools: Inventar, Artefakt- und Behauptungsabfragen, String-Suche, Dekompilierungsabruf, Graph-Traversierung, Schema-Entdeckung, Provenienz, plus aether_submit_claim und aether_annotate für Schreibvorgänge. Agenten-eingereichte Behauptungen durchlaufen genau die Validierung, die ein Adapter durchläuft, und landen als proposed.

Git-freundlicher Export

aether export schreibt zwei Bäume, und die Trennung ist der Punkt:

• graph/ — Artefakte, Behauptungen, Links. Inhaltsadressiert, nach ID sortiert, keine Zeitstempel oder Ausführungs-IDs. Zwei unabhängige Analysen derselben Bytes erzeugen byte-identische Dateien. Committen Sie das; der Diff zeigt, was entdeckt wurde.

• ledger/ — Ausführungen, Attestierungen, Beobachtungen. Provenienz ist eine Aufzeichnung von Ereignissen, also wächst sie. Das ist korrekt.

Evaluierung

Ground Truth liegt in eval/suites/*.json:

$ aether eval
[PASS] elf_sample       required 22/22   recall 1.00   false positives 0
[PASS] firmware_image   required 12/12   recall 1.00   false positives 0

Eine Erwartung kann eine Konfidenzuntergrenze, eine Mindestanzahl unabhängiger Produzenten und — wichtig — verlangen, dass die passende Behauptung Beweise einer spezifischen Art zitiert. Eine contains_hardcoded_secret-Behauptung, die auf eine Datei statt auf einen String zeigt, schlägt fehl, auch wenn die Aussage identisch liest.

Recall ist eine echte Zahl, weil eine Suite aufzählen kann, was gefunden werden muss. Präzision wird nur gegen explizit verbotene Muster bewertet, da keine Suite alles Wahre über eine Binärdatei aufzählen kann; unerwartete Behauptungen werden als unbewertetes Volumen gemeldet, nicht in eine schmeichelhafte Zahl gefaltet. Der Harness hat Negativkontrollen in der Testsuite — ein Harness, der nicht scheitern kann, beweist nichts.

Layout

aether/
  canonical.py       deterministic serialization, hashing, id minting
  evidence/          artifact kinds, claim predicates, and their invariants
  project/           SQLite schema, migrations, and the only sanctioned store
  adapters/
    triage/          ELF/PE headers, strings, rule-based detectors
    ghidra/          headless runner, export script, importer
    binwalk/         firmware unpacking with a standard-library fallback
  export/            deterministic JSONL export
  mcp/               stdio MCP server and its tool surface
  eval/              evaluation harness
cli/                 entry point runnable without installing
docs/                architecture and decision records
eval/suites/         ground truth
examples/            sample generators and the gate demonstration
tests/               172 tests

Dokumentation

• Architektur — Schichten, Datenmodell und warum jedes Stück so geformt ist, wie es ist

• Entscheidungsprotokolle — die Entscheidungen, bei denen ein vernünftiger Ingenieur fragen würde: „Warum so?":

  • 0001 Python für den Kern, null Laufzeitabhängigkeiten

  • 0002 Inhaltsadressierte IDs und was davon ausgeschlossen ist

  • 0003 Behauptungen und Attestierungen sind getrennte Datensätze

  • 0004 Der MCP-Server spricht das Protokoll direkt

  • 0005 Ein begrenzter Extraktions-Fallback, wenn binwalk fehlt

Ein Hinweis zu den Beispieldaten

examples/src/ generiert Binärdateien, die absichtlich gefälschte Anmeldeinformationen enthalten — AWS' eigenen veröffentlichten Beispielschlüssel (AKIAIOSFODNN7EXAMPLE), ein synthetisches ghp_A1b2C3d4...-Token, PEM-Header ohne Schlüsselmaterial und Scherz-Passwörter. Nichts davon ist echt, und nichts davon ist live. Es existiert, damit die Evaluierungssuite ein Ziel hat, dessen Ground Truth genau bekannt ist.

Lizenz

Apache-2.0.