Aether

Análisis de binarios y firmware basado en evidencia.

Aether se apoya en motores maduros — Ghidra headless, binwalk — y aporta lo que ellos no tienen: un modelo de proyecto donde cada hallazgo es una afirmación estructurada vinculada a los artefactos exactos que la respaldan.

Las afirmaciones de seguridad en texto libre no solo están desaconsejadas aquí. Son irrepresentables. Una afirmación es un predicado registrado con campos tipados, y no puede almacenarse sin los identificadores de artefacto del tipo que ese predicado exige. Un agente que intente escribir "esto parece explotable" recibe un error de esquema que nombra el campo infractor.

Aether no construye desensamblador ni descompilador, y nunca lo hará. Ese trabajo ya está bien hecho; el vacío está en todo lo que lo rodea.

Estado: Fase 0 completada

Las 25 comprobaciones de puerta pasan, 172 pruebas pasan.

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

Las fases 1–3 (modo de lenguaje natural, orquestación multiagente, cartografía de firmware) están deliberadamente no iniciadas. El modelo de evidencia existe para ser probado antes de construir nada sobre él.

Related MCP server: pyghidra-mcp

Lo que funciona hoy

Las dos filas "aún no ejecutado" se indican claramente porque importan. Las capas de traducción en ambos lados están completamente probadas; lo que no se ha ejecutado es la invocación del subproceso, porque ninguno de los motores está instalado en la máquina donde se construyó la Fase 0. Ver Habilitando los motores completos.

Inicio rápido

Python 3.10+ y sin dependencias de tiempo de ejecución. Nada que instalar:

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

Trabajando con un proyecto directamente:

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

Los binarios de muestra se generan, no se incluyen. examples/demo_phase0.py y el conjunto de pruebas los construyen bajo demanda; para construirlos a mano:

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

Instalar pone aether en el PATH:

pip install -e .
aether doctor

Ejecutando las pruebas

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

El conjunto genera sus propios binarios de muestra en la primera ejecución. Las pruebas específicas de PE se omiten limpiamente en hosts que no pueden producir un PE; ten en cuenta que un gcc nativo en Linux compila la muestra en un ELF, por lo que la presencia de un compilador no es suficiente y la salida se comprueba para una cabecera MZ. Instala un compilador cruzado mingw-w64 para cobertura de PE en Linux.

CI ejecuta el conjunto, la demostración de puerta, una comprobación de determinismo de exportación y los conjuntos de evaluación en Linux, Windows y macOS con Python 3.10 y 3.12.

Cómo se ve

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

Cada hallazgo se remonta a bytes. Ese es el punto.

El modelo

Tres tipos de registros lo llevan todo.

Artefacto — una pieza de evidencia concreta y localizable: un archivo, una función, una cadena, una referencia cruzada, una sección, un cuerpo descompilado, una coincidencia de firma. Su id es un hash de sus campos de identidad únicamente, por lo que enriquecer un artefacto nunca cambia su id, y dos motores que observan lo mismo llegan a la misma fila.

Afirmación — una aserción estructurada: un predicado registrado, campos tipados, y los artefactos que la respaldan en roles nombrados (locus, support, context, counter). No lleva productor ni marca de tiempo, por lo que la misma aserción de dos motores es una afirmación.

Atestación — un productor que respalda una afirmación en un momento, con una confianza. La confianza nunca es una propiedad de una afirmación; se deriva de las atestaciones — máximo dentro de un productor, OR ruidoso entre productores independientes. Dos motores que coinciden en 0.9 da 0.99, no dos hallazgos casi duplicados.

Esa división es la decisión de diseño central: ADR 0003.

Lo que se aplica, no solo se recomienda

El texto libre tiene exactamente un hogar: anotaciones, en su propia tabla y su propio flujo de exportación, donde nunca pueden confundirse con hallazgos.

Habilitando los motores completos

Aether funciona sin Ghidra o binwalk, con profundidad reducida, y lo dice. aether doctor informa qué falta y cuánto cuesta cada brecha:

$ 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

Proporciona recuperación de funciones, referencias cruzadas, descompilación y cadenas ubicadas con precisión. Sin él, la clasificación a nivel de cabecera aún se ejecuta.

1. Instala Ghidra (se recomienda 11.x).

2. Instala un JDK 21 o más reciente y asegúrate de que java esté en PATH, o establece JAVA_HOME. Ghidra headless no se iniciará sin él.

3. Apunta Aether a la instalación:

   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 y GHIDRA_HOME también se respetan, y support/analyzeHeadless en PATH también funciona. Si todo eso falla, Aether comprueba los directorios de instalación convencionales.

4. Verifica y ejecuta:

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

No necesitas Ghidra localmente para usar los resultados de Ghidra. El puente separa la ejecución de la importación, por lo que una exportación producida en cualquier máquina puede ingerirse en cualquier lugar:

# 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 se ejecuta dentro del intérprete propio de Ghidra (Jython 2.7, o CPython bajo PyGhidra) y permanece en el subconjunto que ambos aceptan.

binwalk

Proporciona squashfs, jffs2, ubifs y formatos de proveedor. Sin él, el carver integrado maneja gzip, bzip2, xz, zip, tar y cpio, y informa cualquier cosa que solo pueda localizar en lugar de omitirla silenciosamente.

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

La extracción completa también quiere sasquatch, jefferson y ubi_reader, que son incómodos en Windows — la razón por la que existe el carver de respaldo (ADR 0005).

MCP

El servidor MCP es la interfaz contra la que trabajarán los futuros agentes, y es un par de la CLI — ambos son frontales delgados sobre una sola biblioteca.

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

Quince herramientas: inventario, consultas de artefactos y afirmaciones, búsqueda de cadenas, recuperación de descompilación, recorrido de grafo, descubrimiento de esquema, procedencia, además de aether_submit_claim y aether_annotate para escrituras. Las afirmaciones enviadas por agentes pasan exactamente por la validación que hace un adaptador y llegan como proposed.

Exportación amigable con Git

aether export escribe dos árboles, y la división es el punto:

• graph/ — artefactos, afirmaciones, enlaces. Direccionados por contenido, ordenados por id, sin marcas de tiempo ni ids de ejecución. Dos análisis independientes de los mismos bytes producen archivos byte-idénticos. Haz commit de esto; el diff muestra lo que se descubrió.

• ledger/ — ejecuciones, atestaciones, observaciones. La procedencia es un registro de eventos, por lo que crece. Eso es correcto.

Evaluación

La verdad de referencia vive en 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

Una expectativa puede exigir un umbral de confianza, un número mínimo de productores independientes y — importante — que la afirmación coincidente cite evidencia de un tipo específico. Una afirmación contains_hardcoded_secret que apunta a un archivo en lugar de una cadena falla, aunque la declaración se lea idénticamente.

El recall es una cifra real porque un conjunto puede enumerar lo que debe encontrarse. La precisión se puntúa solo contra patrones explícitamente prohibidos, ya que ningún conjunto puede enumerar todo lo verdadero sobre un binario; las afirmaciones inesperadas se informan como volumen no puntuado en lugar de plegarse en un número halagador. El arnés tiene controles negativos en el conjunto de pruebas — un arnés que no puede fallar no prueba nada.

Estructura

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

Documentación

• Arquitectura — capas, modelo de datos y por qué cada pieza tiene la forma que tiene

• Registros de decisiones — las elecciones donde un ingeniero razonable preguntaría "¿por qué así?":

  • 0001 Python para el núcleo, cero dependencias de tiempo de ejecución

  • 0002 Identificadores con direccionamiento por contenido, y qué se excluye de ellos

  • 0003 Las afirmaciones y las atestaciones son registros separados

  • 0004 El servidor MCP habla el protocolo directamente

  • 0005 Un respaldo de extracción acotado cuando binwalk está ausente

Una nota sobre los datos de muestra

examples/src/ genera binarios que contienen credenciales deliberadamente falsas — la clave de ejemplo publicada por AWS (AKIAIOSFODNN7EXAMPLE), un token sintético ghp_A1b2C3d4..., cabeceras PEM sin material de clave y contraseñas de broma. Nada de eso es real, y nada de eso está activo. Existe para que el conjunto de evaluación tenga un objetivo cuya verdad de referencia se conoce exactamente.

Licencia

Apache-2.0.