GraphGuard 🛡️

GraphGuard is an advanced, high-fidelity post-exploitation toolkit targeting Microsoft Entra ID and M365 environments. It allows automated ingestion and management of access tokens using the OAuth Device Code flow natively, with a rich, cyber-tactical graphical user interface.

It is designed as an all-in-one Python framework simulating modern C2 infrastructure. The core concepts and functionalities are sourced from and inspired by GraphSpy and GraphRunner.

✨ Features

• FOCI Device Code Phishing: Exploit First-Party Application Client IDs (e.g., Microsoft Office, Microsoft Teams) dynamically via OAuth2 device code authorization.
• Persistent Token Vault: Automatically manages access, refresh, and id tokens into a local SQLite database (graphguard.db). Tokens are available persistently across sessions.
• Entra ID Enumeration: Fetch and parse Active Directory users and groups directly from the browser window.
• OneDrive / SharePoint File Explorer: Browse full directory trees across compromised user instances and directly download files locally using Microsoft's raw download hooks.
• Outlook Mail Viewer: Securely parse and read inbox contents.
• Custom Injection Engine: Target arbitrary untouched graph.microsoft.com endpoints with the active validated token directly from the GUI.
• Dark Mode Tactical UI: A highly polished Vanilla JavaScript/Jinja2 SPA with fluid micro-animations, glassmorphism layouts, and zero-bundle complexities.

---

🚀 Installation & Setup

1. Clone the repository:

   git clone https://github.com/guardiansphere/GraphGuard.git
   cd GraphGuard

2. Initialize a Python Virtual Environment: It is highly recommended to isolate dependencies via venv.

   python3 -m venv .venv
   source .venv/bin/activate

3. Install Dependencies: Install FastAPI, Uvicorn, SQLAlchemy, Requests, and Jinja2.

   pip install -r requirements.txt

4. Launch the Server: Start the Uvicorn engine to serve both the fast API abstraction and the UI.

   uvicorn main:app --port 5050

   Note: The server defaults to 127.0.0.1:5050. You can explore the GUI at http://localhost:5050.

---

🛠️ Typical Usage Flow

1. Open the Device Code Auth panel in your browser.
2. Select a targeted first-party Microsoft Client ID or input a custom App registration.
3. Generate the phishing URL and USER_CODE.
4. Wait for the victim to approve the request—the framework implements a background polling loop against Microsoft's Auth endpoints.
5. Once executed, navigate to the Token Manager and click Use on the newly captured session.
6. Pivot into the Entra ID, Mail, or Files tabs to safely query the tenant data!

---

⚠️ Disclaimer

For Educational and Authorized Red Team Purposes Only. The creators and contributors of GraphGuard are not responsible for any misuse. Always ensure you have written authorization before testing security on third-party systems and data environments.