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.
| 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 with OS, Rust version, and bythos doctor output |
If a command fails, that may be a beta gap, not user error. Please report it.
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.
| 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. |
| 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 |
# 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
cargo build --release
# binaries: target/release/bythos · target/release/bythos-server| Component | Notes |
|---|---|
| Rust 1.70+ (stable) | rustup.rs |
| Git | Clone |
| Modern browser | Web workbench |
| binutils / file (Linux) | External tools stage |
| Docker (optional) | Network / crash-oracle harness |
Windows (PowerShell)
# after rustup install:
$env:PATH = "$env:USERPROFILE\.cargo\bin;" + $env:PATH
rustc --version
cargo --versionKali / Debian
sudo apt update
sudo apt install -y build-essential pkg-config file binutils binutils-multiarch docker.io| Binary | Package | Description |
|---|---|---|
bythos |
bythos-cli |
Terminal client (analyze, exploit, serve, …) |
bythos-server |
bythos-api |
HTTP API + static web UI |
cargo run -p bythos-cli --bin bythos -- <command>
cargo run -p bythos-api --bin bythos-serverUpload / 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.
- SHA-256, strings, section entropy, imports/symbols
- x86_64-oriented disassembly heuristics
- Host tools when present:
file,strings,readelf,objdump,nm, checksec-style summary
- Soft-MMU / step budget, syscalls, branches, coverage hooks
- Runtime adapters: Docker when available, in-process fallback
- Unified intermediate representation with sink classes (overflow, format, UAF risk, …)
- Always-populated UIR C-like decomp text
- Optional radare2 / Ghidra ExportC hybrid (
tools/ghidra/)
| 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 |
- CLI — scriptable lab commands
- Interactive terminal — themed line UI when launched without a subcommand
- Web — dock layout, upload, live activity, exploit panel, graphs, logs
bythos
bythos analyze FILE [flags]
bythos vuln | checksec | exploit | bypass | poc | dynamic | libc FILE [flags]
bythos server | doctor | plugins | demo | help
| Command | Description |
|---|---|
analyze <file> |
Static + dynamic + engine path |
--static-only · --max-steps N · --save DIR · --no-engine · --json |
|
vuln <file> |
Vulnerability search (IR + heap + sinks) |
checksec <file> |
NX / PIE / RELRO / canary style summary |
exploit <file> |
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 <file> |
ASLR / canary / NX / heap / BROP plan |
poc <file> |
Pwntools PoC skeleton |
dynamic <file> |
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
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 64Reports go to bythos-out/ or --save DIR (local only — not part of the git tree).
cargo run -p bythos-cli --bin bythos -- serve| 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/. The browser is presentation only — no analysis algorithms and no SQL in the UI.
┌──────────┐ ┌──────────┐ ┌─────────────┐
│ Web UI │ │ CLI/TUI │ │ bythos-api │
└────┬─────┘ └────┬─────┘ └──────┬──────┘
└──────────────┼────────────────┘
▼
┌────────────────────┐
│ Event bus · KB/log │
└─────────┬──────────┘
┌───────────────┼───────────────┐
▼ ▼ ▼
Static Dynamic Offensive
Tools Runtime Exploit
UIR Coverage Plugins
Principles
- One concern per crate — no monolith.
- Communication via events + artifacts only.
- Prefer honest degradation over fake green paths.
- ELF / Linux quality bar first; PE is dual-path.
| 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).
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.
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.
See 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
cargo fmt
cargo test -p bythos-exploit --lib
cargo test -p bythos-api --libIssues: github.com/Ar1sto/BythosEngine/issues
Release history: CHANGELOG.md
Dual-licensed under:
MIT OR Apache-2.0
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)