Unleashing AegisEye: Elevating Digital Forensics and OSINT with a Custom Model Context Protocol (MCP) Server
Unleashing AegisEye: AI-Powered Digital Forensics & OSINT Triage
Bridging the gap between automated incident response and human-auditable digital forensics using a secure Custom Model Context Protocol (MCP) server.
by neeshant
Introduction
In the modern cybersecurity landscape, threat mitigation is a race against time. Offensive AI tools, automated vulnerability scanners, and automated script suites can execute complex multi-stage attacks, elevate privileges, and establish persistent backdoors in a matter of seconds. When a system is compromised, security teams face the arduous task of manual incident response—sorting through EXIF metadata, verifying SSL certificates, performing domain WHOIS query searches, checking phone registries, and auditing suspicious system files.
Historically, these tasks required human analysts to context-switch between dozens of disjointed tools. For example, a digital forensic investigator might use exiftool for image headers, a custom hex editor to search for binary overlays, openssl to debug certificate handshakes, and command-line network queries to check domain DNS records. By the time a responder compiles these metrics, critical evidence may have been overwritten, and the adversary may have successfully moved laterally across the network.
Enter AegisEye. Developed as a comprehensive, modular digital forensics and Open-Source Intelligence (OSINT) suite, AegisEye introduces a state-of-the-art approach to threat hunting. By wrapping low-level forensic engines in a custom, read-only Model Context Protocol (MCP) server, AegisEye connects autonomous incident response agents (such as Claude Code, Cline, and Cursor) to high-fidelity diagnostic tools. This enables defensive agents to triage compromise anomalies, detect pixel-level image manipulations, extract location telemetry, and identify cryptographic algorithms at machine speed, all while maintaining absolute integrity.
The Core Problem: Manual Latency & Spoliation Risks
Integrating autonomous Large Language Model (LLM) agents into incident response workflows introduces two major challenges: spoliation of evidence and context window overload.
1. The Spoliation Risk: In digital forensics, preserving the original state of digital evidence is the most critical rule of law. A single modified file timestamp or an accidental file overwrite can destroy the chain of custody, making the evidence inadmissible in legal proceedings. When an LLM agent is given arbitrary terminal execution privileges (such as a bash shell access), there is a significant risk that the agent will hallucinate, execute a destructive command (like rm -rf or redirection operators >), or compile third-party scripts that permanently alter the target filesystem.
AegisEye solves this problem by establishing a strictly read-only Custom MCP Server. Instead of giving an agent broad terminal access, AegisEye exposes granular, type-safe functions. The agent can only read metadata, perform ELA compression calculations, or check network records. It has no physical means of executing arbitrary shell commands, thereby preserving the integrity of the underlying forensic environment.
2. Context Window Overload: Dumping a raw forensic binary dump, a complete certificate chain, or a 1000-line EXIF metadata dump into an LLM context instantly degrades its reasoning capabilities. Modern models struggle with needle-in-a-haystack problems when overloaded with raw, unstructured telemetry. AegisEye resolves this by incorporating a lightweight Response Compiler. The compiler digests raw outputs from socket connections and libraries, processes the findings, and packages them into structured, high-fidelity JSON payloads. This delivers precise, actionable data to the agent without consuming unnecessary context.
Detailed Feature Deep Dive
AegisEye is built upon a modular architecture consisting of five core analysis engines, each optimized for speed, reliability, and security.
1. Image Forensics & Error Level Analysis (ELA)
When an image is modified (for example, inserting text, changing a configuration parameter, or altering evidence screenshots), the manipulated pixels will exhibit a different level of compression error compared to the untouched areas. AegisEye's ELA engine programmatically saves the target image as a JPEG at a specific quality level (defaulting to 95) and computes the absolute pixel difference against the original canvas.
Here, Dmax represents the maximum absolute difference between the compressed and original pixels, and Sdefault is a configurable scaling cap (default: 10) to prevent background noise from blowing up. The resulting difference is scaled to generate a high-contrast ELA heatmap, revealing modified pixels as bright, glowing anomalies.
2. Steganographic Binary Scanning
Steganography is a common technique used by threat actors to hide malware payloads, configuration files, or exfiltrated data within benign-looking images. AegisEye scans files for format spoofing (e.g. comparing the file extension with header magic bytes) and overlay detection. The engine scans the binary structure of files, seeking data appended after the standard file footer (such as \xff\xd9 for JPEG, IEND\xae\x42\x60\x82 for PNG, or \x00\x3b for GIF).
If appended data is detected, AegisEye automatically scans the payload overlay for indicators of malicious scripts, searching for:
- Executable script tags: PHP tags (
<?php,<?=) or JavaScript (<script>,javascript:). - Dangerous commands: Evaluation or execution sequences (
eval(,system(). - Archive Polyglots: ZIP headers (
PK\x03\x04), suggesting a zip file is embedded inside the image to create a dual-format polyglot.
3. Network Recon & DNS Auditing
AegisEye queries DNS servers for critical routing records (A, MX, TXT, NS). Furthermore, the tool establishes a direct socket connection to WHOIS databases over port 43, removing third-party library dependencies. It starts by querying the Internet Assigned Numbers Authority (IANA) at whois.iana.org, parses the response for referral registrars, and follows up with the corresponding referral registrar to retrieve detailed registration records.
The network engine also audits SSL/TLS certificates. It establishes a secure socket handshake over port 443, parses validity dates, determines Days Remaining, and extracts the subject and issuer Distinguished Names (DNs). This allows autonomous agents to verify whether a domain's transport layer is active and secure or if certificate expiry poses an imminent risk.
4. Phone & Email OSINT Validation
For OSINT investigations, AegisEye validates target phone numbers using the Google phonenumbers port. When provided a phone number in standard E.164 international format (e.g., +919876543210), the tool maps the telecom carrier, geolocates the registered country, determines the number type (Mobile vs. Landline), and lists registered timezone records.
For email investigations, it parses the domain from the address, runs a regex syntax validity check, and executes a Mail Exchanger (MX) DNS query using the host environment's networking stack. This checks whether the target domain has active mail-handling configurations, distinguishing valid communicators from dead or spoofed domains.
5. Cryptography & Password Strength Entropy
AegisEye classifies cryptographic hash formats by checking character length and hex syntax. It can instantly recognize MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, NTLM, Bcrypt, PBKDF2, and UNIX crypt formats.
To audit credentials, AegisEye evaluates password complexity by checking against common dictionary lists and calculating its Shannon Entropy:
Where L is the password character length, and R is the dynamic pool size based on character variety (lowercase: 26, uppercase: 26, numbers: 10, special characters: 32). Using the computed entropy, the system estimates the brute-force cracking time assuming a fast attack setup performing 10 billion guesses per second.
6. Forensic DoD File Shredder
When sensitive evidence, compromised malware files, or system dumps must be permanently destroyed to prevent recovery, AegisEye provides a secure shredding algorithm. Based on the DoD 5220.22-M military standard, the shredder performs multiple overwrite passes directly on the filesystem:
- Odd Passes: Overwrite target file data with cryptographically secure random bytes generated via
os.urandom. - Even Passes: Overwrite data with null bytes (
\x00).
After writing the payloads, it clears buffers using f.flush() and forces hard disk write sync with os.fsync(f.fileno()). Finally, to eliminate all directory-level metadata traces, it renames the file to a random 10-character alphabetic string before performing final deletion.
System Architecture
The repository is structured to separate core diagnostic utilities from interface wrappers. Below is the system directory layout:
aegiseye-forensics/
├── aegiseye.py # Main entry CLI & interactive TUI menu
├── aegiseye_mcp.py # Custom MCP Server implementing JSON-RPC 2.0
├── requirements.txt # Package dependencies (Pillow, phonenumbers, rich)
├── core/ # Deep Analysis Engines
│ ├── __init__.py
│ ├── channels.py # Splits image RGB channels & computes perceptual hash
│ ├── crypto.py # Shannon entropy calculations & password auditing
│ ├── ela.py # JPEG compression and absolute difference heatmaps
│ ├── metadata.py # Audits EXIF data and extracts GPS coordinates
│ ├── network.py # WHOIS socket queries, active DNS, SSL certificate checks
│ ├── osint.py # Telecom carrier and email MX validation
│ ├── reporter.py # Compiles full forensic results to dynamic HTML reports
│ ├── shred.py # DoD 5220.22-M military-grade file shredding
│ └── stego.py # Scans image overlays & identifies spoofed extensions
└── evidence/ # Sample forensic test dataset
├── clean_evidence.jpg
└── tampered_evidence.jpg
The main CLI interface aegiseye.py exposes subcommands or boots the interactive TUI. The core/ folder holds modules containing specific forensic logic. The aegiseye_mcp.py handles requests using standard input/output streams, mapping incoming JSON-RPC calls from agents to the appropriate Python utility classes.
Comprehensive Installation Guide
Follow this step-by-step setup guide to download and configure AegisEye on your local system or testing lab.
Step 1: Clone the Repository
Open your command line interface and clone the remote repository:
git clone https://github.com/Neeshant01/aegiseye-forensics.git cd aegiseye-forensics
Step 2: Configure a Virtual Environment
Setting up a virtual environment isolates project modules, avoiding conflicts with system packages and preventing externally-managed-environment errors:
python3 -m venv venv source venv/bin/activate
Step 3: Install Required Dependencies
Install the required Python libraries using pip:
pip install -r requirements.txt
Pillow (for image processing), phonenumbers (for international phone formatting and lookup), and rich (for rendering clean terminal tables and progress bars).
Practical Usage & Commands
AegisEye operates in two modes: an interactive Terminal User Interface (TUI) and direct Command-Line Interface (CLI) subcommands.
1. Interactive TUI Menu
To run all module diagnostics inside a interactive menu, execute the main script without any arguments:
python3 aegiseye.py
This starts a text interface with options to scan images, check phone/email OSINT, wipe files, or perform network audits.
2. Direct CLI Subcommands
For scripting and pipeline integration, you can call specific subcommands directly:
# General help menu python3 aegiseye.py --help # Perform image ELA and EXIF scanning on a file python3 aegiseye.py image photo.jpg # Securely shred a target file with 5 overwrite passes python3 aegiseye.py shred secret_key.pem --passes 5 # Audit network profile of a target domain python3 aegiseye.py domain target-site.org --whois # Scan password strength complexity python3 aegiseye.py crypto --password P@ssw0rd123!
3. Model Context Protocol (MCP) Configuration
To connect AegisEye to agentic LLM platforms (like Claude Code or Cline) as an MCP server, add the server setup details to your agent's configuration file (e.g., claude_desktop_config.json or cline_config.json):
{
"mcpServers": {
"aegiseye-forensics": {
"command": "python3",
"args": [
"/absolute/path/to/aegiseye-forensics/aegiseye_mcp.py"
]
}
}
}
Once configured, your agent can access and execute these capabilities autonomously. For example, if you instruct the agent to: "Analyze evidence/tampered_evidence.jpg and check for edits," the agent calls the analyze_image tool through the MCP protocol, identifies the anomalies, and generates a dynamic HTML report.
Troubleshooting Common Issues
If you run into issues during execution, check these solutions:
| Common Issue | Likely Cause | Remediation Step |
|---|---|---|
| PIL/Pillow Import Error | Pillow failed to compile correctly on your local environment. | Reinstall Pillow inside your venv: pip install --force-reinstall Pillow |
| ELA Fails with Permission Denied | Image file is located in a protected system directory. | Copy the target file into your user workspace or the aegiseye-forensics directory. |
| Phone OSINT yields Empty Carrier | Phone number was not passed in international format. | Ensure number begins with country code and a "+" prefix (e.g., +919876543210). |
Secure Your Workflow with AegisEye
AegisEye bridges defensive agent automation with the strict controls required for digital forensics. Experience automated compromise triage without risking the integrity of your evidence.
View AegisEye on GitHub →