Skip to main content
Glama

πŸ›‘οΈ AegisRe: Autonomous Binary Analysis & Vulnerability Triaging Copilot

License: MIT Python: 3.9+ Protocol: MCP Tests: Passing Security: Mitigations

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             β”‚
 β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Related MCP server: Ghidra MCP server for Cline

⚑ 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.

Available Tools

3 tools
aegis_calculate_entropyA

Calculates Shannon entropy (0.0 to 8.0) of a binary or byte payload to detect packing, obfuscation, or encryption.

Inputs: file_path (required).

aegis_inspect_binaryB

Inspects binary format, architecture, bitness, mitigations (NX, PIE, Canary), entropy, and high-risk API imports.

Inputs: file_path (required).

aegis_triage_vulnerabilitiesB

Scans decompiled C/C++ or source code for CWE security flaws (buffer overflow, command injection, format strings, weak RNG, hardcoded keys).

Inputs: code_or_file (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 3 tools

    Disambiguation3/5

    aegis_inspect_binary already reports entropy, while aegis_calculate_entropy is a dedicated entropy calculator, creating clear overlap. aegis_triage_vulnerabilities is distinct, and descriptions help clarify the broad-profile versus focused-entropy distinction, but the boundary is still blurry.

    Naming Consistency5/5

    All three tools use the same aegis_ prefix and follow a consistent verb_noun pattern: inspect_binary, triage_vulnerabilities, calculate_entropy. Naming is highly predictable and readable.

    Tool Count4/5

    Three tools is a lean but reasonable scope for a focused binary triage server, with no excessive surface. However, aegis_calculate_entropy is partially redundant with aegis_inspect_binary, so not every tool fully earns its place.

    Completeness3/5

    The set covers binary metadata/mitigations, vulnerability pattern scanning, and entropy/packing detection, which supports core triage workflows. But for a reverse-engineering server, it lacks obvious operations such as disassembly, string extraction, symbol/function listing, and report export.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to import binaries into Ghidra, trigger analysis, browse functions, symbols, strings, and imports, and read decompiled C code and disassembly via MCP tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to locally analyze and reverse engineer binaries through a compact 12-tool MCP interface for triage, function discovery, disassembly/decompilation, cross-references, strings/imports, call graphs, memory reads, annotations, and binary diffs.
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and LLMs to query a codebase’s structure and data flow by building Joern Code Property Graphs and exposing CPGQL queries, taint tracking, program slicing, and vulnerability analysis over MCP.
      -