🛡️ AegisRe: Autonomous Binary Analysis & Vulnerability Triaging Copilot

AegisRe is a lightweight, zero-dependency binary diagnostics and vulnerability triaging copilot engineered for reverse engineers, security auditors, and AI coding assistants like Claude Code.

🏛️ System Architecture

 ┌────────────────────────────────────────────────────────┐
 │            Claude Code / AI Coding Agents              │
 └──────────────────────────┬─────────────────────────────┘
                            │ (JSON-RPC 2.0 via stdio)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │               AegisRe MCP Gateway Server               │
 ├──────────────────────────┬─────────────────────────────┤
 │   aegis_inspect_binary   │ aegis_triage_vulnerabilities│
 └─────────────┬────────────┴──────────────┬──────────────┘
               │                           │
   ┌───────────▼────────────┐  ┌───────────▼────────────┐
   │ Binary Analyzer Engine │  │ Vulnerability Triager  │
   ├────────────────────────┤  ├────────────────────────┤
   │ - ELF / PE Header Parse│  │ - CWE-120 Buffer Oflow │
   │ - NX / PIE / Canaries  │  │ - CWE-134 Format Str   │
   │ - Shannon Entropy Calc │  │ - CWE-78 Command Inj   │
   │ - Dangerous Symbol Scan│  │ - CWE-798 Hardcoded Key│
   └───────────┬────────────┘  └───────────┬────────────┘
               │                           │
               └─────────────┬─────────────┘
                             ▼
 ┌────────────────────────────────────────────────────────┐
 │           Markdown & JSON Report Generator             │
 └────────────────────────────────────────────────────────┘

⚡ Key Capabilities

1. 🔍 Binary Hardening & Mitigation Auditing

Inspects executable formats (ELF, PE, Mach-O) across x86, x86_64, ARM, and AArch64 (ARM64) architectures without requiring external binary parser libraries:

• NX / DEP: Detects non-executable stack flags (PT_GNU_STACK).
• PIE / ASLR: Position Independent Executable verification.
• Stack Canaries: Identifies __stack_chk_fail protections.
• Entropy Analysis: Calculates Shannon entropy (0.0 to 8.0) to flag packed or encrypted payloads.
• High-Risk Symbols: Flags dangerous C library calls (strcpy, gets, sprintf, system, popen, mprotect).

2. 🛡️ Source & Decompiled Code Vulnerability Triaging

Automatically maps static vulnerabilities directly to the MITRE CWE Catalog:

• CWE-120: Unbounded string copies (strcpy, strcat).
• CWE-242: Inherently dangerous functions (gets).
• CWE-134: Uncontrolled format strings (printf(variable)).
• CWE-78: OS command injections (system, popen).
• CWE-338: Insecure pseudo-random number generation (rand()).
• CWE-798: Hardcoded secrets, API tokens, and credentials.
• CWE-416: Use-after-free and double-free anti-patterns.

3. 🤖 Model Context Protocol (MCP) for Claude Code

AegisRe ships with a native MCP server running over stdio. Once configured, Claude Code can autonomously invoke Aegis tools directly inside your terminal session.

🚀 Quick Start

Installation

Clone the repository and install in editable mode:

git clone https://github.com/cloudauraa/aegis-re.git
cd aegis-re
pip install -e .

Note: AegisRe runs entirely on standard library modules. Zero external dependencies required for core analysis.

💻 CLI Usage Guide

1. Inspect a Binary

# Run security analysis on a Linux shared object or executable
aegis inspect ./target.so --strings

Example Output:

[*] Inspecting: libtarget.so
    Format:       ELF (Linux / Android Shared Object / Executable)
    Architecture: AArch64 (ARM64) (64-bit, Little)
    Size:         5,689,536 bytes
    Entropy:      6.4586 [NORMAL]
    SHA-256:      85d3bda458c9dda73d0d5f539991ed785d2c1e86c5a2e8d6b69061cc2839ea01

[*] Mitigations & Protections:
    [+] NX / DEP:       ENABLED
    [+] PIE / ASLR:     ENABLED
    [+] Stack Canary:   ENABLED
    [+] RELRO:          None
    [+] Stripped:       NO

[!] Detected High-Risk APIs:
    - strcpy - Unbounded string copy (CWE-120)
    - sprintf - Potential format string / buffer overflow (CWE-134)
    - system - Command execution via shell interpreter (CWE-78)

2. Triage Decompiled C / Source Code

# Scan decompiled C file and export Markdown audit report
aegis triage ./decompiled.c -o audit_report.md

3. Comprehensive Scan

# Full spectrum inspection + vulnerability triage exported as JSON
aegis scan ./target_binary -o scan_results.json

🔌 Connecting to Claude Code (MCP Setup)

Add AegisRe to your Claude Code or Claude Desktop MCP configuration (mcp_config.json):

{
  "mcpServers": {
    "aegis-re": {
      "command": "python",
      "args": ["-m", "aegis.cli", "mcp"]
    }
  }
}

Now you can instruct Claude Code:

"Audit target.so using AegisRe and verify if stack canaries and NX are enabled."

🧩 IDA Pro Integration

To use Aegis inside IDA Pro 7.x, 8.x, or 9.x:

1. Copy aegis/integrations/ida_bridge.py into your IDA plugins folder:
   • Windows: %APPDATA%\Hex-Rays\IDA Pro\plugins\
   • Linux: ~/.idapro/plugins/
2. In IDA Pro, highlight any decompiled function in Hex-Rays and press:
   👉 Ctrl + Alt + A
3. AegisRe will instantly analyze the AST and print a CWE risk breakdown in the IDA output console.

🧪 Testing

Run the included unit test suite:

python -m unittest discover -s tests -v

All 9 test cases pass verifying entropy calculation, ELF/PE header heuristics, CWE rule matching, and CLI parsing.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.
Maintained by Sagar Beniwal.