[](https://pypi.org/project/GraphSpy/)
[](https://twitter.com/intent/follow?screen_name=RedByte1337)
# GraphSpy
```
________ _________
/ / by RedByte1337 __ / /
/ _____/___________ ______ | |__ / _____/_____ ______
/ \ __\_ __ \__ \ \____ \| | \ \_____ \\____ \ | |
\ \_\ \ | \/ __ \| |_> | \ \/ \ |_> \___ |
\______ /__| |____ | __/|___| /_______ / ___/ ____|
\/ \/|__| \/ \/|__| \/
```
# Table of Contents
- [GraphSpy](#graphspy)
- [Table of Contents](#table-of-contents)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Execution](#execution)
- [Usage](#usage)
- [Features](#features)
- [Release Notes](#release-notes)
- [Upcoming Features](#upcoming-features)
- [Credits](#credits)
# Quick Start
## Installation
The following goes over the recommended installation process using pipx to avoid any dependency conflicts.
GraphSpy is built to work on every operating system, although it was mainly tested on Linux and Windows.
For other installation options and detailed instructions, check the [Installation page](https://github.com/RedByte1337/GraphSpy/wiki/Installation) on the wiki.
```bash
# Install pipx (skip this if you already have it)
apt install pipx
pipx ensurepath
# Install the latest version of GraphSpy from pypi
pipx install graphspy
```
## Execution
After installation, the application can be launched using the `graphspy` command from any location on the system.
Running GraphSpy without any command line arguments will launch GraphSpy and make it available at `http://127.0.0.1:5000` by default.
```bash
graphspy
```
Now simply open `http://127.0.0.1:5000` in your favorite browser to get started!
Use the `-i` and `-p` arguments to modify the interface and port to listen on.
```bash
# Run GraphSpy on http://192.168.0.10
graphspy -i 192.168.0.10 -p 80
# Run GraphSpy on port 8080 on all interfaces
graphspy -i 0.0.0.0 -p 8080
```
For detailed instructions and other command line arguments, please refer to the [Execution page](https://github.com/RedByte1337/GraphSpy/wiki/Execution) on the wiki.
## Usage
Please refer to the [GitHub Wiki](https://github.com/RedByte1337/GraphSpy/wiki) for full usage details.
For a quick feature overview, check out the [official release blog post](https://insights.spotit.be/2024/04/05/graphspy-the-swiss-army-knife-for-attacking-m365-entra/).
# Features
## Access and Refresh Tokens
Store your access and refresh tokens for multiple users and scopes in one location.
Easily switch between them or request new access tokens from any page.
## Device Codes
Easily create and poll multiple device codes at once. If a user used the device code to authenticate, GraphSpy will automatically store the access and refresh token in its database.
## MFA Methods
View, modify and create MFA methods linked to the account of the user.
The following MFA methods can be added from GraphSpy to set up persistance:
- Microsoft Authenticator App
- Custom OTP App, or use GraphSpy as OTP app to generate TOTP codes on the fly!
- FIDO Security Keys!
- Alternative email address
- Mobile/Office/Alternative Phones (SMS or call)
## Files and SharePoint
Browse through files and folders in the user's OneDrive or any accessible SharePoint site through an intuitive file explorer interface.
Of course, files can also be directly downloaded, or new files can be uploaded.
Additionally, list the user's recently accessed files or files shared with the user.
## Outlook
Open the user's Outlook with a single click using just an Outlook access token (FOCI)!
## MS Teams
Read and send messages using the Microsoft Teams module with a FOCI access token of the skype API (https://api.spaces.skype.com/).
## Graph Searching
Search for keywords through all Microsoft 365 applications using the Microsoft Search API.
For instance, use this to search for any files or emails containing keywords such as "password", "secret", ...
## Custom Requests
Perform custom API requests towards any endpoint using access tokens stored in GraphSpy.
Custom request templates with variables can be stored in the database to allow easy reuse of common custom API requests.
## Entra ID
List all Entra ID users and their properties using the Microsoft Graph API.
View additional details for a user, such as its group memberships, role assignments, devices, app roles and API permissions.
## Multiple Databases
GraphSpy supports multiple databases. This is useful when working on multiple assessments at once to keep your tokens and device codes organized.
## Dark Mode
Use the dark mode by default, or switch to light mode.
# Release Notes
Refer to the [Release Notes](https://github.com/RedByte1337/GraphSpy/wiki/Release-Notes) page on the GitHub Wiki
# Upcoming Features
* Rename files and create folders
* More authentication options
* Password, ESTSAuth Cookie, PRT, ...
* Automatic Access Token Refreshing
* Improve Microsoft Teams Module
* Download authenticated files
* Upload files and images
* Entra ID
* List Users, Groups, Applications, Devices, Conditional Access Policies, ...
* Cleaner exception handling
* While this should not have any direct impact on the user, edge cases might currently throw exceptions to the GraphSpy output instead of handling them in a cleaner way.
# Credits
The main motivation for creating GraphSpy was the lack of an easy to use way to perform post-compromise activities targetting Office365 applications (such as Outlook, Microsoft Teams, OneDrive, SharePoint, ...) with just an access token.
While several command-line tools existed which provided some basic functionality, none of them came close to the intuitive interactive experience which the original applications provide (such as the file explorer-like interface of OneDrive and SharePoint).
However, a lot of previous research was done by countless other persons (specifically regarding Device Code Phishing, which lead to the initial requirement for such a tool in the first place).
* Acknowledgements
* [TokenTactics](https://github.com/rvrsh3ll/TokenTactics) and [TokenTacticsV2](https://github.com/f-bader/TokenTacticsV2)
* [AADInternals](https://github.com/Gerenios/AADInternals)
* [Introducing a new phishing technique for compromising Office 365 accounts](https://aadinternals.com/post/phishing/)
* [The Art of the Device Code Phish](https://0xboku.com/2021/07/12/ArtOfDeviceCodePhish.html)
* [GraphRunner](https://github.com/dafthack/GraphRunner) is a PowerShell tool with a lot of similar features, which was released while GraphSpy was already in development. Regardless, both tools still have their distinguishing factors.
* Assets
* UIcons by [Flaticon](https://www.flaticon.com/uicons)
Raw data
{
"_id": null,
"home_page": "https://github.com/RedByte1337/GraphSpy",
"name": "GraphSpy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "RedByte1337",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/87/82/1571bcdace3bbc2fe107d5977e77c2a1b20e3d5333181831e67ad20c60fe/graphspy-1.4.2.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/GraphSpy/)\n\n[](https://twitter.com/intent/follow?screen_name=RedByte1337)\n\n# GraphSpy\n\n```\n ________ _________\n / / by RedByte1337 __ / / \n / _____/___________ ______ | |__ / _____/_____ ______\n/ \\ __\\_ __ \\__ \\ \\____ \\| | \\ \\_____ \\\\____ \\ | |\n\\ \\_\\ \\ | \\/ __ \\| |_> | \\ \\/ \\ |_> \\___ |\n \\______ /__| |____ | __/|___| /_______ / ___/ ____|\n \\/ \\/|__| \\/ \\/|__| \\/\n```\n\n# Table of Contents\n\n- [GraphSpy](#graphspy)\n- [Table of Contents](#table-of-contents)\n- [Quick Start](#quick-start)\n\t- [Installation](#installation)\n\t- [Execution](#execution)\n\t- [Usage](#usage)\n- [Features](#features)\n- [Release Notes](#release-notes)\n- [Upcoming Features](#upcoming-features)\n- [Credits](#credits)\n\n# Quick Start\n\n## Installation\n\nThe following goes over the recommended installation process using pipx to avoid any dependency conflicts.\n\nGraphSpy is built to work on every operating system, although it was mainly tested on Linux and Windows. \n\nFor other installation options and detailed instructions, check the [Installation page](https://github.com/RedByte1337/GraphSpy/wiki/Installation) on the wiki.\n\n```bash\n# Install pipx (skip this if you already have it)\napt install pipx\npipx ensurepath\n\n# Install the latest version of GraphSpy from pypi\npipx install graphspy\n```\n\n## Execution\n\nAfter installation, the application can be launched using the `graphspy` command from any location on the system.\n\nRunning GraphSpy without any command line arguments will launch GraphSpy and make it available at `http://127.0.0.1:5000` by default.\n\n```bash\ngraphspy\n```\n\nNow simply open `http://127.0.0.1:5000` in your favorite browser to get started!\n\nUse the `-i` and `-p` arguments to modify the interface and port to listen on.\n\n```bash\n# Run GraphSpy on http://192.168.0.10\ngraphspy -i 192.168.0.10 -p 80\n# Run GraphSpy on port 8080 on all interfaces\ngraphspy -i 0.0.0.0 -p 8080\n```\n\nFor detailed instructions and other command line arguments, please refer to the [Execution page](https://github.com/RedByte1337/GraphSpy/wiki/Execution) on the wiki.\n\n## Usage\n\nPlease refer to the [GitHub Wiki](https://github.com/RedByte1337/GraphSpy/wiki) for full usage details.\n\nFor a quick feature overview, check out the [official release blog post](https://insights.spotit.be/2024/04/05/graphspy-the-swiss-army-knife-for-attacking-m365-entra/).\n\n# Features\n\n## Access and Refresh Tokens\n\nStore your access and refresh tokens for multiple users and scopes in one location. \n\n\n\n\n\nEasily switch between them or request new access tokens from any page.\n\n\n\n## Device Codes\n\nEasily create and poll multiple device codes at once. If a user used the device code to authenticate, GraphSpy will automatically store the access and refresh token in its database.\n\n\n\n## MFA Methods\n\nView, modify and create MFA methods linked to the account of the user.\n\n\n\nThe following MFA methods can be added from GraphSpy to set up persistance:\n- Microsoft Authenticator App\n- Custom OTP App, or use GraphSpy as OTP app to generate TOTP codes on the fly!\n- FIDO Security Keys!\n- Alternative email address\n- Mobile/Office/Alternative Phones (SMS or call)\n\n\n\n## Files and SharePoint\n\nBrowse through files and folders in the user's OneDrive or any accessible SharePoint site through an intuitive file explorer interface.\n\nOf course, files can also be directly downloaded, or new files can be uploaded.\n\n\n\nAdditionally, list the user's recently accessed files or files shared with the user.\n\n\n\n## Outlook\n\nOpen the user's Outlook with a single click using just an Outlook access token (FOCI)!\n\n\n\n\n\n## MS Teams\n\nRead and send messages using the Microsoft Teams module with a FOCI access token of the skype API (https://api.spaces.skype.com/).\n\n\n\n## Graph Searching\n\nSearch for keywords through all Microsoft 365 applications using the Microsoft Search API.\n\nFor instance, use this to search for any files or emails containing keywords such as \"password\", \"secret\", ...\n\n\n\n## Custom Requests\n\nPerform custom API requests towards any endpoint using access tokens stored in GraphSpy.\n\n\n\nCustom request templates with variables can be stored in the database to allow easy reuse of common custom API requests.\n\n\n\n## Entra ID\n\nList all Entra ID users and their properties using the Microsoft Graph API.\n\n\n\nView additional details for a user, such as its group memberships, role assignments, devices, app roles and API permissions.\n\n\n\n## Multiple Databases\n\nGraphSpy supports multiple databases. This is useful when working on multiple assessments at once to keep your tokens and device codes organized.\n\n\n\n## Dark Mode\n\nUse the dark mode by default, or switch to light mode.\n\n# Release Notes\n\nRefer to the [Release Notes](https://github.com/RedByte1337/GraphSpy/wiki/Release-Notes) page on the GitHub Wiki\n\n# Upcoming Features\n\n* Rename files and create folders\n* More authentication options\n\t* Password, ESTSAuth Cookie, PRT, ...\n* Automatic Access Token Refreshing\n* Improve Microsoft Teams Module\n * Download authenticated files\n * Upload files and images\n* Entra ID\n\t* List Users, Groups, Applications, Devices, Conditional Access Policies, ...\n* Cleaner exception handling\n\t* While this should not have any direct impact on the user, edge cases might currently throw exceptions to the GraphSpy output instead of handling them in a cleaner way.\n\n# Credits\n\nThe main motivation for creating GraphSpy was the lack of an easy to use way to perform post-compromise activities targetting Office365 applications (such as Outlook, Microsoft Teams, OneDrive, SharePoint, ...) with just an access token.\n\nWhile several command-line tools existed which provided some basic functionality, none of them came close to the intuitive interactive experience which the original applications provide (such as the file explorer-like interface of OneDrive and SharePoint).\n\nHowever, a lot of previous research was done by countless other persons (specifically regarding Device Code Phishing, which lead to the initial requirement for such a tool in the first place).\n\n* Acknowledgements\n\t* [TokenTactics](https://github.com/rvrsh3ll/TokenTactics) and [TokenTacticsV2](https://github.com/f-bader/TokenTacticsV2)\n\t* [AADInternals](https://github.com/Gerenios/AADInternals)\n\t* [Introducing a new phishing technique for compromising Office 365 accounts](https://aadinternals.com/post/phishing/)\n\t* [The Art of the Device Code Phish](https://0xboku.com/2021/07/12/ArtOfDeviceCodePhish.html)\n\t* [GraphRunner](https://github.com/dafthack/GraphRunner) is a PowerShell tool with a lot of similar features, which was released while GraphSpy was already in development. Regardless, both tools still have their distinguishing factors.\n* Assets\n\t* UIcons by [Flaticon](https://www.flaticon.com/uicons)\n",
"bugtrack_url": null,
"license": null,
"summary": "Initial Access and Post-Exploitation Tool for AAD and O365 with a browser-based GUI",
"version": "1.4.2",
"project_urls": {
"Homepage": "https://github.com/RedByte1337/GraphSpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "87821571bcdace3bbc2fe107d5977e77c2a1b20e3d5333181831e67ad20c60fe",
"md5": "be88cd97f59e02c7d7c90f72628c69db",
"sha256": "789e9cd4049d7c5f5f7d2317e7cda0a8707b485c472e89191a80fea1580642b9"
},
"downloads": -1,
"filename": "graphspy-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "be88cd97f59e02c7d7c90f72628c69db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 80831,
"upload_time": "2025-02-03T21:08:36",
"upload_time_iso_8601": "2025-02-03T21:08:36.601928Z",
"url": "https://files.pythonhosted.org/packages/87/82/1571bcdace3bbc2fe107d5977e77c2a1b20e3d5333181831e67ad20c60fe/graphspy-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 21:08:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RedByte1337",
"github_project": "GraphSpy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Flask",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "PyJWT",
"specs": []
},
{
"name": "Requests",
"specs": []
},
{
"name": "pyotp",
"specs": []
},
{
"name": "fido2",
"specs": []
}
],
"lcname": "graphspy"
}
JSON
