# 🛡️ AegisRe: Autonomous Binary Analysis & Vulnerability Triaging Copilot

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.9+](https://img.shields.io/badge/Python-3.9%2B-brightgreen.svg)](https://python.org)
[![Protocol: MCP](https://img.shields.io/badge/Protocol-MCP%202024--11--05-purple.svg)](https://modelcontextprotocol.io)
[![Tests: Passing](https://img.shields.io/badge/Tests-9%20Passed-success.svg)](https://github.com/cloudauraa/aegis-re)
[![Security: Mitigations](https://img.shields.io/badge/Mitigations-NX%20%7C%20PIE%20%7C%20Canary-orange.svg)](https://cwe.mitre.org)

> **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

```text
 ┌────────────────────────────────────────────────────────┐
 │            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:

```bash
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
```bash
# Run security analysis on a Linux shared object or executable
aegis inspect ./target.so --strings
```

**Example Output:**
```text
[*] 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
```bash
# Scan decompiled C file and export Markdown audit report
aegis triage ./decompiled.c -o audit_report.md
```

### 3. Comprehensive Scan
```bash
# 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`):

```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:

```bash
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](LICENSE) - see the LICENSE file for details.  
Maintained by **[Sagar Beniwal](https://github.com/cloudauraa)**.