Development Guide

This document covers the project architecture, how to set up a development environment, run tests, and contribute.

Architecture

aetherion/
├── cli/                 Typer command definitions (thin dispatch layer)
│   ├── main.py          Root app, callback, interactive launcher
│   ├── local_cmd.py     Device management commands
│   ├── exploit_cmd.py   CVE exploitation commands
│   ├── post_cmd.py      Post-exploitation commands
│   ├── extras_cmd.py    Extras (chats, mic, logcat)
│   ├── shodan_cmd.py    Shodan integration
│   ├── ngrok_cmd.py     Ngrok tunnel commands
│   ├── msf_cmd.py       Metasploit bridge commands
│   ├── obfus_cmd.py     Obfuscation engine commands
│   ├── ops_cmd.py       Operations (state, plugins, history)
│   ├── persist_cmd.py   Persistence & stealth commands
│   ├── intel_cmd.py     Intelligence gathering commands
│   └── report_cmd.py    Reporting commands
│
├── core/                Foundation layer (no external tool deps)
│   ├── adb_client.py    ADB client — connect, shell, push/pull
│   ├── protocol.py      ADB wire protocol (binary framing)
│   ├── crypto.py        Certificate generation + AES encryption
│   ├── scanner.py       Network scanner (ARP + TCP)
│   ├── session.py       Multi-device session manager (singleton)
│   ├── types.py         Shared enums and dataclasses
│   └── exceptions.py    Custom exception hierarchy
│
├── modules/             Business logic (grouped by domain)
│   ├── exploit/         CVE-2026-0073, patch checker, auto-root
│   ├── post/            Extractor, screen, remote, filesystem, APK, extras
│   ├── obfus/           String obfuscator, APK repacker, traffic camo
│   ├── persist/         Boot persistence, process hider, log wiper
│   ├── intel/           Fingerprinter, credential harvester, SOCKS5 proxy
│   ├── ops/             State manager, plugin system, interactive console
│   ├── shodan/          Shodan scanner + batch exploit
│   ├── ngrok/           Tunnel manager
│   ├── msf/             Payload gen, handler, session bridge
│   └── report/          HTML/PDF report generator
│
└── utils/               Shared utilities
    ├── config.py        YAML config loader
    ├── console.py       Rich console singleton + theme
    ├── logging.py       JSON-lines audit logger
    ├── validators.py    IP, port, subnet validation
    ├── shell_detect.py  Shell detection + RC block generation
    └── setup_wizard.py  Post-install dependency checker

Design Principles

CLI is thin — cli/ files only parse arguments and call into modules/. No business logic in CLI layer.
Core has no external deps — core/ only depends on stdlib + cryptography. It can be used as a library.
Modules are independent — each module directory is self-contained. Modules communicate through core/session.py.
Single entry point — main.py registers all subcommands. Running without args launches the interactive console.

Development Setup

git clone https://github.com/your-username/aetherion.git
cd aetherion

# Create venv
python3 -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

This installs:

pytest, pytest-cov, pytest-asyncio — testing
black — formatting
ruff — linting
mypy — type checking

Running Tests

# All tests
pytest

# With coverage report
pytest --cov=aetherion --cov-report=html

# Specific test file
pytest tests/test_core/test_scanner.py -v

# Specific test module
pytest tests/test_cli/ -v

# Only tests matching a pattern
pytest -k "test_subnet"

Test Structure

tests/
├── test_cli/           CLI command tests (argument parsing, exit codes)
├── test_core/          Core layer tests (protocol, crypto, scanner, session)
├── test_modules/       Module tests (exploit, post, msf, shodan, etc.)
└── test_utils/         Utility tests (config, validators, setup wizard)

Tests use unittest.mock extensively to avoid requiring real ADB devices or network access.

Linting & Formatting

# Lint (check only)
ruff check aetherion/

# Lint (auto-fix)
ruff check --fix aetherion/

# Format
black aetherion/

# Type check
mypy aetherion/

Configuration

Linting and formatting are configured in pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]

[tool.mypy]
python_version = "3.10"
strict = true

Adding a New Command

Create aetherion/cli/your_cmd.py:

import typer

your_app = typer.Typer()

@your_app.command()
def action(target: str = typer.Argument(..., help="Target IP")):
    """Description of what this does."""
    from aetherion.modules.your_module import do_thing
    do_thing(target)

from aetherion.cli.your_cmd import your_app
app.add_typer(your_app, name="your", help="Your module description")

Add tests in tests/test_cli/test_your_cmd.py.

Adding a New Module

Create directory: aetherion/modules/your_module/
Add __init__.py with public API
Implement logic in separate files
Wire it up via a CLI command (see above)
Add tests in tests/test_modules/test_your_module.py

Commit Convention

Use conventional commits:

feat: add new intel harvester for browser cookies
fix: validate subnet before scan to prevent crash
docs: update plugin API reference
test: add coverage for edge case in crypto module
refactor: extract ADB framing into protocol.py

Python Version Support

Version	Status
3.10	Minimum supported
3.11	Supported
3.12	Supported
3.13	Supported
3.14	Tested, passing

The requires-python = ">=3.10" constraint is set in pyproject.toml.

File Locations at Runtime

Path	Purpose
`~/.aetherion/`	Home directory
`~/.aetherion/venv/`	Python virtual environment
`~/.aetherion/platform-tools/`	ADB binary
`~/.aetherion/state.db`	Session state (SQLite)
`~/.aetherion/logs/`	Log directory
`~/.aetherion/output/`	Default output directory
`~/.aetherion/modules/`	User plugins
`config.yaml`	Project config (or `~/.aetherion/config.yaml`)
`aetherion.log`	Audit log (JSON-lines)

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History