AegisCLI - Modular Recon Framework

Framework Architecture

AegisCLI follows a strict separation-of-concerns model with isolated modules, uniform interfaces, and zero global state. Every component is designed for predictability, extensibility, and real-world workflow integration.

aegiscli/cli

Central entry point responsible for command routing, argument parsing, and global flag resolution. Routes through Profiler_Selector rather than instantiating tool classes directly, following the aegiscli <module> <submodule> [flags] <target> pattern without carrying any state of its own.

core/utils

Runtime services shared across every module. logger.py handles timestamped logging to ~/.aegiscli/logs — JSON is the ground truth format when --log is active. exporter.py builds structured JSON envelopes for all tool output, while flagger.py manages verbose mode state without coupling to the CLI layer.

core/helpers

Presentation layer for terminal output. formatter.py provides color-coded styling, smart truncation for long data lists, and consistent section formatting — ensuring every module produces visually uniform output regardless of its data source.

aegiscli/tools

All recon capability lives here, fully isolated under tools/<module>/<submodule>. Currently active: profiler/ with WHOIS, DNS, and Web submodules; scanner/ with port.py and host.py. Planned: enumerator/, analyser/, and injector/ — each independently developed with no cross-module dependencies.

Entry Point

CLI

Command Router

Core Utilities

Logger

Flagger

Formatter

Exporter

Tool Modules

Profiler

Active

WHOIS DNS Web

Scanner

In Progress

Port Host UDP

Enumerator

Planned

Dirs Files Subdomains

Analyser

Planned

APIs OSINT Reports

Zero Global State

Isolated Modules

Uniform Interfaces

Current Features

Scanner Module NEW

Host Discovery — ICMP echo (raw sockets, provides TTL), TCP fallback on ports 22/80/443 for no-root environments, CIDR range support, TTL-based OS fingerprinting
Port Scanner — async TCP connect via asyncio, semaphore-controlled concurrency (400 cap), flexible port targeting
Banner grabbing — passive read (SSH, FTP, SMTP, Redis etc.), HTTP GET probe, SSL/TLS upgrade with SNI
Service Discovery — banner strings parsed into structured identity (protocol, software, version); included in JSON log output alongside raw banner; service is null when banner is empty or unrecognised
Two-step detection — plain TCP confirms open status, banner grab fully decoupled
Verbose diagnostics across both submodules — per-host method/result, per-port banner status

Profiler Module

WHOIS / RDAP Lookup with intelligent fallback
DNS Resolver (A/AAAA, MX, TXT, NS, CNAME, SOA)
Reverse DNS (PTR) Lookups
Web Fingerprinter with SSL/TLS inspection
HTTP header profiling and cookie parsing

Framework Capabilities

Verbose Mode (-v) for step-by-step execution
Structured JSON logging (--log) to ~/.aegiscli/logs
Centralized color-coded terminal output
ABC-enforced submodule contracts — fetch(), display(), export(), result()
Packaged as pip-installable Python project

Design Principles

No global mutable state
Isolated tool modules with uniform ABC interfaces
Errors always visible — never silently swallowed
Predictable output for automation and scripting
Consistent CLI patterns across all modules

Usage Examples

// Interactive Demo

$ aegiscli profiler whois -v example.com

✓ Querying WHOIS for example.com...

✓ Domain: example.com

✓ Registrar: IANA

✓ Status: clientTransferProhibited

$ aegiscli profiler dns --log example.com

✓ Resolving DNS records...

✓ A: 93.184.216.34

✓ AAAA: 2606:2800:220:1:248:1893:25c8:1946

✓ Logged to ~/.aegiscli/logs/dns_20250217.log

$ aegiscli profiler web httpbin.org

✓ Fingerprinting httpbin.org...

✓ Status: 200 OK

✓ Server: gunicorn/19.9.0

! Warning: HSTS header missing

$ aegiscli scanner host -v --log 192.168.1.0/24

▸ Hosts: 254 | ICMP: available | Concurrency: 100

✓ 192.168.1.1 alive TTL 64 Linux/macOS

✓ 192.168.1.5 alive TTL 128 Windows

✓ 192.168.1.20 alive TCP:80 (no root)

✓ Logged to ~/.aegiscli/logs/scanner_host_20260317.json

// Output Examples

WHOIS Output

DNS Resolution

Web Fingerprint

Verbose Mode

Future Plans

Short-Term

Immediate Priorities

Web Fingerprinter upgrade — deeper tech stack detection, framework fingerprinting
Scanner udp.py — UDP port scanning
Upgrade dns and whois submodules to actively interact with their discovery and dig deeper

Medium-Term

Core Expansion

settings.json configuration engine — user-configurable defaults for concurrency, timeouts, output behavior, and module-specific parameters
Enumerator module with ffuf or gobuster integration
Analyser module (third-party API enrichment — Shodan, VirusTotal, Censys, and more)

Long-Term

Advanced Features

Full blown tool chaining system
Injector module (SQLi testing, payload logic)
Log Analyser
Plugin ecosystem

Project Philosophy

AegisCLI is built intentionally as a framework. The priority is long-term stability, modular expansion, and real-world workflow integration.

Practitioner Workflow First

One tool replaces many. WHOIS, DNS, fingerprinting, scanning, and enumeration under a single consistent interface.

Architecture-First Development

Every decision prioritizes structural integrity and long-term maintainability over quick feature additions.

Minimize Complexity

Simple, isolated modules with clear boundaries. No hidden dependencies or unexpected side effects.

Strict Readability Standards

Code is written for humans first. Every function, module, and output is designed for clarity.

Incremental Refinement

Slow, deliberate progress over rushed releases. Each version builds on a solid foundation.

Predictable, Consistent Behavior

Uniform interfaces and output formats enable seamless automation and scripting integration.

Licensed under AGPLv3

Ensures full code transparency and enforces openness at every level — including network use. Any derivative work, modification, or hosted deployment must retain the same license and publish its source.

Free to use Free to modify Source must stay open Network use = distribution Attribution required Copyleft

AegisCLI Modular Recon Framework