Aether

Анализ бинарных файлов и прошивок, основанный на доказательствах.

Aether опирается на зрелые движки — Ghidra headless, binwalk — и добавляет то, чего им не хватает: модель проекта, в которой каждая находка — это структурированное утверждение, связанное с точными артефактами, которые его подтверждают.

Свободные текстовые утверждения о безопасности здесь не просто не приветствуются. Они непредставимы. Утверждение — это зарегистрированный предикат с типизированными полями, и оно не может быть сохранено без идентификаторов артефактов тех видов, которые требует этот предикат. Агент, пытающийся записать «это выглядит эксплуатируемым», получит ошибку схемы с указанием проблемного поля.

Aether не создаёт дизассемблер и не создаёт декомпилятор, и никогда не будет. Эта работа уже сделана хорошо; пробел — всё вокруг неё.

Статус: Фаза 0 завершена

Все 25 проверок ворот пройдены, 172 теста проходят.

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

Фазы 1–3 (режим естественного языка, мультиагентная оркестрация, картография прошивок) намеренно не начаты. Модель доказательств должна быть подтверждена, прежде чем на ней будет что-то построено.

Related MCP server: pyghidra-mcp

Что работает сегодня

Две строки «ещё не запускалось» указаны прямо, потому что это важно. Слои трансляции на обеих сторонах полностью протестированы; не выполнялся только вызов подпроцесса, потому что ни один из движков не установлен на машине, на которой строилась Фаза 0. См. Включение полных движков.

Быстрый старт

Python 3.10+ и без зависимостей времени выполнения. Ничего устанавливать не нужно:

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

Работа с проектом напрямую:

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

Примеры бинарных файлов генерируются, а не фиксируются. examples/demo_phase0.py и тестовый набор создают их по требованию; чтобы собрать их вручную:

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

Установка помещает aether в PATH:

pip install -e .
aether doctor

Запуск тестов

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

Набор генерирует собственные примеры бинарных файлов при первом запуске. Тесты, специфичные для PE, корректно пропускаются на хостах, которые не могут создать PE — обратите внимание, что нативный gcc на Linux компилирует пример в ELF, поэтому наличия компилятора недостаточно, и вывод проверяется на наличие заголовка MZ. Установите кросс-компилятор mingw-w64 для покрытия PE на Linux.

CI запускает набор тестов, демонстрацию ворот, проверку детерминизма экспорта и оценочные наборы на Linux, Windows и macOS на Python 3.10 и 3.12.

Как это выглядит

$ 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...

Каждая находка ведёт к байтам. В этом вся суть.

Модель

Три типа записей несут всё.

Артефакт — конкретное, локализуемое доказательство: файл, функция, строка, перекрёстная ссылка, секция, декомпилированное тело, совпадение сигнатуры. Его идентификатор — это хэш только его полей идентичности, поэтому обогащение артефакта никогда не меняет его идентификатор, и два движка, наблюдающие одно и то же, попадают в одну строку.

Утверждение — структурированное утверждение: зарегистрированный предикат, типизированные поля и артефакты, подтверждающие его в именованных ролях (locus, support, context, counter). Оно не содержит производителя и временной метки, поэтому одно и то же утверждение от двух движков — это одно утверждение.

Аттестация — один производитель, стоящий за одним утверждением в один момент, с уверенностью. Уверенность никогда не является свойством утверждения; она выводится из аттестаций — максимум внутри производителя, шумное ИЛИ для независимых производителей. Два движка, согласных с уверенностью 0.9, дают 0.99, а не два почти дублирующихся результата.

Это разделение — центральное проектное решение: ADR 0003.

Что обеспечивается, а не просто рекомендуется

У свободного текста ровно один дом: аннотации, в собственной таблице и собственном потоке экспорта, где их нельзя спутать с находками.

Включение полных движков

Aether работает без Ghidra или binwalk, с уменьшенной глубиной, и сообщает об этом. aether doctor сообщает, чего не хватает и сколько стоит каждый пробел:

$ 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

Предоставляет восстановление функций, перекрёстные ссылки, декомпиляцию и точно локализованные строки. Без него триаж на уровне заголовков всё равно выполняется.

1. Установите Ghidra (рекомендуется 11.x).

2. Установите JDK 21 или новее и убедитесь, что java находится в PATH, или установите JAVA_HOME. Ghidra headless не запустится без этого.

3. Укажите Aether путь к установке:

   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 и GHIDRA_HOME также учитываются, и support/analyzeHeadless в PATH тоже работает. Если ничего из этого не подходит, Aether проверяет стандартные каталоги установки.

4. Проверьте и запустите:

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

Вам не нужен локальный Ghidra для использования результатов Ghidra. Мост разделяет запуск и импорт, поэтому экспорт, созданный на любой машине, можно импортировать где угодно:

# 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 работает внутри собственного интерпретатора Ghidra (Jython 2.7 или CPython под PyGhidra) и остаётся в подмножестве, которое принимают оба.

binwalk

Предоставляет squashfs, jffs2, ubifs и вендорские форматы. Без него встроенный карвер обрабатывает gzip, bzip2, xz, zip, tar и cpio и сообщает о том, что он мог только найти, а не молча пропускает.

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

Для полного извлечения также нужны sasquatch, jefferson и ubi_reader, которые неудобны на Windows — причина, по которой существует запасной карвер (ADR 0005).

MCP

MCP-сервер — это интерфейс, с которым будут работать будущие агенты, и он является равноправным с CLI — оба являются тонкими фронтендами над одной библиотекой.

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

Пятнадцать инструментов: инвентаризация, запросы артефактов и утверждений, поиск строк, получение декомпиляции, обход графа, обнаружение схемы, происхождение, плюс aether_submit_claim и aether_annotate для записи. Утверждения, отправленные агентом, проходят точно такую же проверку, как и адаптер, и попадают как proposed.

Git-дружественный экспорт

aether export записывает два дерева, и разделение — в этом суть:

• graph/ — артефакты, утверждения, связи. Адресация по содержимому, сортировка по идентификатору, без временных меток и идентификаторов запусков. Два независимых анализа одних и тех же байтов дают байт-идентичные файлы. Коммитьте это; diff показывает, что было обнаружено.

• ledger/ — запуски, аттестации, наблюдения. Происхождение — это запись событий, поэтому оно растёт. Это правильно.

Оценка

Эталонные данные находятся в 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

Ожидание может требовать минимального уровня уверенности, минимального числа независимых производителей и — что важно — чтобы совпавшее утверждение ссылалось на доказательства конкретного вида. Утверждение contains_hardcoded_secret, указывающее на файл, а не на строку, не проходит, даже если формулировка идентична.

Полнота — реальная цифра, потому что набор может перечислить, что должно быть найдено. Точность оценивается только по явно запрещённым шаблонам, поскольку ни один набор не может перечислить всё, что верно о бинарном файле; неожиданные утверждения сообщаются как неоценённый объём, а не включаются в лестную цифру. Стенд имеет отрицательные контроли в тестовом наборе — стенд, который не может провалиться, ничего не доказывает.

Структура

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

Документация

• Архитектура — слои, модель данных и почему каждая часть устроена именно так

• Записи решений — выборы, где разумный инженер спросил бы «почему так?»:

  • 0001 Python для ядра, ноль зависимостей времени выполнения

  • 0002 Идентификаторы на основе содержимого и что из них исключено

  • 0003 Утверждения и аттестации — отдельные записи

  • 0004 MCP-сервер говорит на протоколе напрямую

  • 0005 Ограниченный запасной вариант извлечения при отсутствии binwalk

Примечание о примерах данных

examples/src/ генерирует бинарные файлы, содержащие намеренно поддельные учётные данные — опубликованный пример ключа AWS (AKIAIOSFODNN7EXAMPLE), синтетический токен ghp_A1b2C3d4..., PEM-заголовки без ключевого материала и шуточные пароли. Ничего из этого не является реальным и не является действующим. Это существует, чтобы у оценочного набора была цель, чья эталонная истина известна точно.

Лицензия

Apache-2.0.