Base64 Tool

Multi-format encoding/decoding CLI with recursive layer peeling for security analysis.

Overview

A Python CLI tool that handles Base64, Base64URL, Base32, hex, and URL encoding with automatic format detection and recursive multi-layer decoding. The standout feature is layer peeling — the same technique used to analyze obfuscated malware payloads and WAF bypass attempts.

Status: Complete | Difficulty: Beginner

Tech Stack

Technology	Version	Purpose
Python	3.14+	Modern syntax, native type hints
Typer	-	CLI framework
Rich	-	Terminal formatting

Features

Core Functionality

Encode/decode across 5 formats (Base64, Base64URL, Base32, Hex, URL)
Automatic format detection with confidence scoring
Recursive layer peeling (decodes stacked encodings)
Chain encoding (apply multiple encodings in sequence)
Pipe/stdin support

Security Relevance

Analyze obfuscated malware payloads (e.g., DARKGATE multi-layer encoding)
Decode WAF bypass attempts
Inspect JWT tokens, certificates, and hex dumps
Understand why encoding is not encryption

Architecture

User Command
    ↓
cli.py (Typer commands: encode, decode, detect, peel, chain)
    ↓
┌──────────────┬──────────────┬──────────────┐
│  encoders.py │  detector.py │   peeler.py  │
│  Pure encode │  Format      │  Recursive   │
│  /decode +   │  detection + │  multi-layer │
│  registry    │  confidence  │  decoding    │
└──────────────┴──────────────┴──────────────┘
    ↓
formatter.py (Rich terminal output)

Quick Start

cd PROJECTS/beginner/base64-tool

# Install dependencies
uv sync

# Encode/decode
uv run b64tool encode "Hello World"
uv run b64tool decode "SGVsbG8gV29ybGQ="

# Auto-detect format
uv run b64tool detect "SGVsbG8gV29ybGQ="

# Multi-layer peeling
uv run b64tool chain "alert('xss')" --steps base64,hex
uv run b64tool peel "5957786c636e516f4a33687a63796370"

# Pipe support
echo "SGVsbG8=" | uv run b64tool decode

Project Structure

base64-tool/
├── src/base64_tool/
│   ├── cli.py          # Typer commands
│   ├── constants.py    # Enums, thresholds, character sets
│   ├── encoders.py     # Pure encode/decode functions + registry
│   ├── detector.py     # Format detection with confidence scoring
│   ├── peeler.py       # Recursive multi-layer decoding
│   ├── formatter.py    # Rich terminal output
│   └── utils.py        # Input resolution, text helpers
├── tests/              # 78 tests across all modules
├── pyproject.toml
└── Justfile

Development

# Run tests
uv run pytest tests/ -v

# Linting
uv run ruff check .

# Format
uv run ruff format .

Source Code

View on GitHub

Home

Beginner Projects

Intermediate Projects

Advanced Projects

Guides

Resources

Progress: 14/60