Share
## https://sploitus.com/exploit?id=ADB14477-EED1-5781-914E-3A48A9D53749
Bythos Engine
Modular binary analysis & exploit research platform
Linux-first · ELF primary · PE dual-path · event-driven · research-grade
Beta ·
Intro ·
Why Bythos ·
Quick start ·
Features ·
CLI ·
Web ·
Limitations ·
Disclaimer
---
> [!CAUTION]
> **Public Beta `v1.0.0-beta.1` — not a finished product.**
> Bythos is an active research codebase. Pipelines often work for lab and CTF-style samples, but **things can and will break**: incomplete panels, missing host tools, heuristic exploit plans, rough UX, panics on odd inputs, and **breaking changes** before a stable `1.0.0`.
> Use it as a **research lab**, not as guaranteed industrial AEG.
---
## Beta 1.0 — read this first
| | |
|--|--|
| **Version** | **`1.0.0-beta.1`** · git tag **`v1.0.0-beta.1`** |
| **Status** | Public research beta |
| **Stability** | APIs, reports, and UI can change without notice |
| **Best experience** | Linux / Kali with binutils (+ optional Docker) |
| **Windows** | Supported via in-process sandbox; host tools need WSL/Docker Desktop |
| **Support** | [Open an issue](https://github.com/Ar1sto/BythosEngine/issues) with OS, Rust version, and `bythos doctor` output |
If a command fails, that may be a **beta gap**, not user error. Please report it.
---
## Introduction
**Bythos Engine** is a **modular, event-driven platform** for analyzing native binaries and building **research-oriented** exploit plans.
Instead of one monolithic “black box” analyzer, Bythos is a **Cargo workspace** of independent crates that talk through a shared **event bus**, hierarchical logging, and knowledge surfaces. You get:
- **Static** analysis and optional host tooling (`readelf`, `objdump`, …)
- **Dynamic** soft-MMU style execution traces
- **Unified IR (UIR)** with sink annotations and always-on decompilation-style lift
- An **exploit research hub** (gadgets, leaks, ASLR/canary/NX bypass plans, PoC skeletons)
- Three frontends from one engine: **CLI**, interactive terminal, and a **web workbench**
**Audience:** security researchers, reverse engineers, CTF players, and students who want a single lab stack — not a turnkey “hack any service” appliance.
**Ethics:** exploit and AEG output is **scaffolding** (plans, oracles, pwntools skeletons). Only use it on systems you own or are authorized to test.
---
## What makes Bythos different
| Function | Why it matters |
|--------------|----------------|
| **Event-driven modularity** | Stages publish lifecycle events (`BinaryUploaded`, `ElfParsed`, …). UI and plugins **observe** the bus — no tangled monolith. |
| **Linux-first honesty** | Prefer real binutils, Docker, host `libc`. When tools are missing, Bythos returns **dry-runs / fallbacks** instead of fake success. |
| **Light upload, heavy AEG on demand** | Web upload stays responsive (light pipeline). Full oracle AEG is **explicit** via CLI/API so the browser does not hang. |
| **Research exploit hub** | Technique selection (ROP / BROP / ret2libc / heap / one_gadget), gadget DB, leak surfaces, multi-path security bypass, evidence-filled payload slots. |
| **Always-filled decomp surface** | UIR C-like lift always produces text; r2/Ghidra are optional upgrades. |
| **Product profiles** | nginx, OpenSSH, Apache, daemons, setuid — prune path explosion for operator-driven synthesis. |
| **Web dock workbench** | Free-float panels (upload, activity, exploit, graphs, logs) over a pure presentation UI. |
---
## Platform
| OS | Support level |
|----|----------------|
| **Linux / Kali** | **Primary** — build tools, binutils, Docker optional |
| **Windows** | Supported — MSVC Rust, in-process runtime; tools via WSL/Docker when available |
| **macOS** | Builds with Rust; Linux-tool depth varies |
| Environment variable | Default / values | Purpose |
|----------------------|------------------|---------|
| `BYTHOS_BIND` | `127.0.0.1:8080` | HTTP listen address |
| `BYTHOS_WEB_ROOT` | `web` | Static UI path |
| `BYTHOS_RUNTIME` | `auto` · `docker` · `inprocess` | Runtime backend |
| `BYTHOS_DECOMP` | `uir` · `r2` · `ghidra` | Prefer decomp backend |
| `BYTHOS_GHIDRA_HOME` | — | Ghidra install for headless export |
| `BYTHOS_LIBC_SO` | — | Explicit libc for catalog import |
| `BYTHOS_NO_ANIM` | `1` | Disable CLI animations |
---
## Quick start
```bash
# 1) Prerequisites: Rust stable (https://rustup.rs)
# Linux: sudo apt install -y build-essential pkg-config file binutils
git clone https://github.com/Ar1sto/BythosEngine.git
cd BythosEngine
git checkout v1.0.0-beta.1 # pin beta (optional)
cargo build
cargo test # smoke / unit tests — not a full product cert
# Interactive help
cargo run -p bythos-cli --bin bythos -- help
# Analyze a sample
cargo run -p bythos-cli --bin bythos -- analyze ./sample.elf
cargo run -p bythos-cli --bin bythos -- doctor
# Web workbench + API (run from repo root so web/ resolves)
cargo run -p bythos-cli --bin bythos -- serve
# → http://127.0.0.1:8080/
```
**Release build**
```bash
cargo build --release
# binaries: target/release/bythos · target/release/bythos-server
```
---
## Installation
### Prerequisites
| Component | Notes |
|-----------|--------|
| **Rust 1.70+** (stable) | [rustup.rs](https://rustup.rs) |
| **Git** | Clone |
| **Modern browser** | Web workbench |
| **binutils / file** (Linux) | External tools stage |
| **Docker** (optional) | Network / crash-oracle harness |
**Windows (PowerShell)**
```powershell
# after rustup install:
$env:PATH = "$env:USERPROFILE\.cargo\bin;" + $env:PATH
rustc --version
cargo --version
```
**Kali / Debian**
```bash
sudo apt update
sudo apt install -y build-essential pkg-config file binutils binutils-multiarch docker.io
```
### Binaries
| Binary | Package | Description |
|--------|---------|-------------|
| `bythos` | `bythos-cli` | Terminal client (analyze, exploit, serve, …) |
| `bythos-server` | `bythos-api` | HTTP API + static web UI |
```bash
cargo run -p bythos-cli --bin bythos --
cargo run -p bythos-api --bin bythos-server
```
---
## Features
### Analysis pipeline (overview)
```text
Upload / CLI
→ store binary
→ parse (ELF primary, PE tagged)
→ static (strings, entropy, disasm, findings)
→ optional host tools (file, readelf, objdump, …)
→ UIR / IR + vuln sink annotations + decomp lift
→ dynamic soft-MMU (steps, syscalls, trace)
→ defensive + offensive plugins (light AEG on bus)
→ artifacts / reports
```
Full **AEG** (`bythos exploit`) additionally runs gadget harvest, leak & bypass planning, payload/PoC fill, optional oracle loop and Docker harness.
### Static & tools
- SHA-256, strings, section entropy, imports/symbols
- x86_64-oriented disassembly heuristics
- Host tools when present: `file`, `strings`, `readelf`, `objdump`, `nm`, checksec-style summary
### Dynamic & runtime
- Soft-MMU / step budget, syscalls, branches, coverage hooks
- Runtime adapters: Docker when available, in-process fallback
### IR / decompilation
- Unified intermediate representation with sink classes (overflow, format, UAF risk, …)
- Always-populated UIR C-like decomp text
- Optional radare2 / Ghidra ExportC hybrid (`tools/ghidra/`)
### Exploit research hub
| Area | Capability |
|------|------------|
| **Techniques** | auto, ROP, BROP, ret2libc, SROP, heap, one_gadget |
| **Gadgets** | Per-segment RX harvest with roles |
| **Leaks** | Format, GOT/PLT, write, partial overwrite, canary, BROP, FSOP, TLS, network oracle |
| **Bypass** | ASLR multi-leak, canary, NX, RELRO, ret2csu, ret2dlresolve, pivot, mprotect ROP, SROP, FSOP, seccomp/CET notes |
| **libc** | Catalog + host auto-mirror under `data/libc/`, one_gadget candidates |
| **Payload / PoC** | Evidence-filled pwntools skeleton (`OFFSET`, gadgets, libc offs) |
| **Oracle / Docker** | Offset ranking + crash-oracle / Dockerfile dry-run when tools missing |
| **Validation** | Recursive structural plan checks |
### Frontends
- **CLI** — scriptable lab commands
- **Interactive terminal** — themed line UI when launched without a subcommand
- **Web** — dock layout, upload, live activity, exploit panel, graphs, logs
---
## CLI
```text
bythos
bythos analyze FILE [flags]
bythos vuln | checksec | exploit | bypass | poc | dynamic | libc FILE [flags]
bythos server | doctor | plugins | demo | help
```
| Command | Description |
|---------|-------------|
| `analyze ` | Static + dynamic + engine path |
| | `--static-only` · `--max-steps N` · `--save DIR` · `--no-engine` · `--json` |
| `vuln ` | Vulnerability search (IR + heap + sinks) |
| `checksec ` | NX / PIE / RELRO / canary style summary |
| `exploit ` | Full AEG / exploit synthesis |
| | `--class nginx\|openssh\|auto` · `--tech auto\|rop\|brop\|ret2libc\|heap\|one_gadget` |
| | `--proto local\|tcp\|http` · `--canary` · `--oracle` · `--attempts N` · `--save DIR` |
| `bypass ` | ASLR / canary / NX / heap / BROP plan |
| `poc ` | Pwntools PoC skeleton |
| `dynamic ` | Soft-MMU / trace |
| `libc` | Libc catalog status + host mirror |
| `server` / `serve` | HTTP API + web UI |
| `doctor` | Platform / runtime / tools probe |
| `plugins` | List research plugin hub |
| `demo` | Built-in mini ELF fixture |
| `help` | Command overview |
**Examples**
```bash
cargo run -p bythos-cli --bin bythos -- checksec ./vuln.elf
cargo run -p bythos-cli --bin bythos -- vuln ./vuln.elf
cargo run -p bythos-cli --bin bythos -- exploit ./vuln.elf --class auto --oracle --save ./bythos-out
cargo run -p bythos-cli --bin bythos -- bypass ./vuln.elf --canary
cargo run -p bythos-cli --bin bythos -- poc ./vuln.elf
cargo run -p bythos-cli --bin bythos -- dynamic ./vuln.elf --max-steps 64
```
Reports go to `bythos-out/` or `--save DIR` (local only — not part of the git tree).
---
## Web workbench
```bash
cargo run -p bythos-cli --bin bythos -- serve
```
Open **http://127.0.0.1:8080/**
| Capability | Notes |
|------------|--------|
| Upload / batch | Creates a case project; **light** pipeline (no full oracle AEG on the request thread) |
| Live activity | Stage + detail from the event bus |
| Panels | Dashboard, dynamic, hybrid, events, exploit, checksec, plugins, logs, graphs |
| Dock | Free-float with snap zones |
| Full exploit | Explicit exploit UI/API path |
Static assets: [`web/`](web/). The browser is **presentation only** — no analysis algorithms and no SQL in the UI.
---
## Architecture (summary)
```text
┌──────────┐ ┌──────────┐ ┌─────────────┐
│ Web UI │ │ CLI/TUI │ │ bythos-api │
└────┬─────┘ └────┬─────┘ └──────┬──────┘
└──────────────┼────────────────┘
▼
┌────────────────────┐
│ Event bus · KB/log │
└─────────┬──────────┘
┌───────────────┼───────────────┐
▼ ▼ ▼
Static Dynamic Offensive
Tools Runtime Exploit
UIR Coverage Plugins
```
**Principles**
1. One concern per crate — no monolith.
2. Communication via events + artifacts only.
3. Prefer honest degradation over fake green paths.
4. ELF / Linux quality bar first; PE is dual-path.
### Workspace map (selection)
| Group | Crates |
|-------|--------|
| Core | `bythos-event`, `bythos-logging`, `bythos-core`, `bythos-storage` |
| Binary | `bythos-parser`, `bythos-elf`, `bythos-protection`, `bythos-cfg`, `bythos-uir` |
| Analysis | `bythos-static`, `bythos-tools`, `bythos-dynamic`, `bythos-runtime`, `bythos-coverage` |
| Research | `bythos-offensive`, `bythos-exploit`, `bythos-defensive`, `bythos-security` |
| Frontends | `bythos-api`, `bythos-cli`, `bythos-dock` |
Optional helpers: `tools/ghidra/` (ExportC), `data/libc/README.md` (catalog layout).
---
## Known limitations — expect problems
This section is intentional. **Beta means imperfect.**
| Area | What you may hit |
|------|------------------|
| **Stability** | Panics or incomplete errors on unusual binaries |
| **Web UI** | Not every panel is equally deep; layout quirks possible |
| **Exploit synthesis** | Offsets/gadgets can be heuristic; not “pwn any binary” |
| **Upload** | Light path only — full AEG needs CLI/API |
| **Docker / QEMU** | Dry-run reports when CLI tools are missing |
| **r2 / Ghidra** | Optional; UIR always falls back |
| **PE / Windows tools** | Secondary quality vs ELF on Linux |
| **libc catalog** | Depends on host / mirrored data |
| **Performance** | Large binaries + full plugin catalog can be slow |
| **API surface** | May break before stable `1.0.0` |
Green unit tests are a **smoke floor**, not certification of real-world AEG success.
---
## Project layout (published)
```text
BythosEngine/
README.md ← you are here (main docs)
CHANGELOG.md
CONTRIBUTING.md
LICENSE-MIT
LICENSE-APACHE
Cargo.toml / Cargo.lock
crates/ ← Rust workspace
web/ ← research workbench
docs/assets/ ← cover art
tools/ghidra/ ← optional ExportC script
data/libc/README.md ← libc catalog notes
```
Build caches (`target/`), lab folders (`bythos-out/`, `bythos-projects/`), and local sessions (`.bythos/`) are **gitignored**.
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Short version:
- Keep crates decoupled (event bus only)
- Prefer honest dry-runs when tools are missing
- Add tests near exploit / upload / IR changes
- Never commit `target/` or lab dumps
```bash
cargo fmt
cargo test -p bythos-exploit --lib
cargo test -p bythos-api --lib
```
Issues: [github.com/Ar1sto/BythosEngine/issues](https://github.com/Ar1sto/BythosEngine/issues)
---
## Changelog
Release history: [CHANGELOG.md](CHANGELOG.md)
---
## License
Dual-licensed under:
- [LICENSE-MIT](LICENSE-MIT)
- [LICENSE-APACHE](LICENSE-APACHE)
```text
MIT OR Apache-2.0
```
---
## Disclaimer
Bythos is a **research and educational** platform for binary analysis and automated exploit *planning*.
- Do **not** use it against systems without authorization.
- PoCs and bypass plans may be incomplete, wrong, or unsafe — validate in an isolated lab.
- Authors accept **no liability** for misuse or damage.
- This **beta** does not claim industrial reliability or guaranteed exploitation of real services.
- Treat outputs as **hypotheses**, not guarantees.
---
Bythos Engine · v1.0.0-beta.1 · Public Beta
Binary Research / Exploit Research Studio · @Ar1sto (0mniscius)