________ _________
/ / by RedByte1337 __ / /
/ _____/___________ ______ | |__ / _____/_____ ______
/ \ __\_ __ \__ \ \____ \| | \ \_____ \\____ \ | |
\ \_\ \ | \/ __ \| |_> | \ \/ \ |_> \___ |
\______ /__| |____ | __/|___| /_______ / ___/ ____|
\/ \/|__| \/ \/|__| \/
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 on the wiki.
# 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
# Install the browser binaries required for ESTS cookie authentication
python -m playwright install chromiumAfter 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.
graphspyNow 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.
# 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 8080For detailed instructions and other command line arguments, please refer to the Execution page on the wiki.
Use the included Dockerfile to containerize GraphSpy. The commands below use Podman, but docker can be substituted directly if you prefer Docker.
# Build the local image
podman build -t graphspy .
# Create a local directory to persist GraphSpy data (databases, tokens, ...)
mkdir -p ./graphspy-data
# Run GraphSpy and expose it on http://<your-host-ip>:5000
podman run --rm -it \
-p 0.0.0.0:5000:5000 \
-v ./graphspy-data:/root/.gspy \
--name graphspy \
graphspyAll user data lives inside /root/.gspy in the container, so bind-mount a folder from your machine to keep access tokens, databases, and device codes between runs. The container entrypoint runs graphspy -i 0.0.0.0 -p 5000 with FLASK_ENV=production, ensuring development mode stays disabled unless you explicitly add --debug.
You can override any CLI arguments by appending them after the image name. For example, to run GraphSpy on port 8080 and listen on all interfaces:
podman run --rm -it -p 0.0.0.0:8080:8080 graphspy -i 0.0.0.0 -p 8080Please refer to the GitHub Wiki for full usage details.
For a quick feature overview, check out the official release blog post.
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.
If you already have SSO cookies (for example from previous phishing) head to the ESTS Cookies tab and paste the ESTSAUTHPERSISTENT or ESTSAUTH (or both). GraphSpy replays that session with a headless browser, mirroring ROADtools native redirect handling, and silently redeems the cookies into fresh access tokens.
Everything runs headless by default, but you can pass --show-browser to watch the automation step-by-step while troubleshooting.
Capture clear-text Entra ID credentials? The Entra Credentials tab lets you safely store usernames, passwords, and optional tenant hints in the database. You can replay those credentials whenever needed to perform a Resource Owner Password Credentials (ROPC) grant for any public client and resource supported by Azure AD.
From the same page you can:
- Generate access tokens directly from stored credentials and optionally activate them immediately in GraphSpy.
- Request refresh tokens in the same flow and store them for later use, including FOCI context.
- Override the tenant ID/domain per request if you need to target a different directory than the one saved with the credential.
Keep in mind that Microsoft blocks password-based auth when the account is protected by MFA or conditional access, so this feature shines most when accounts are legacy, have weaker policies, or you have already satisfied the additional requirements.
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.
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)
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.
Open the user's Outlook web mail with a single click using just an Outlook access token (FOCI)!
Or use the Outlook Graph module to list, read, search, delete, reply or send emails with just an access token for the MS Graph API!
Craft completely HTML formated emails directly in GraphSpy and include images and attachments.
Read and send messages using the Microsoft Teams module with a FOCI access token of the skype API (https://api.spaces.skype.com/).
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", ...
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.
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.
GraphSpy supports multiple databases. This is useful when working on multiple assessments at once to keep your tokens and device codes organized.
Use the dark mode by default, or switch to light mode.
Refer to the Release Notes page on the GitHub Wiki
- Rename files and create folders
- More authentication options
- 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.
Do you or your organization want to be featured as a key sponsor of this project here, or even mentioned within GraphSpy itself? Or do you just like GraphSpy and want to support my work?
Please check out my Sponsor page.
If you do not have the means to sponsor, but you still want to show your gratitude, feel free to add a star instead. ⭐
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 and TokenTacticsV2
- AADInternals
- Introducing a new phishing technique for compromising Office 365 accounts
- The Art of the Device Code Phish
- 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.
- ROADtools / roadtx for the interactive auth research that inspired GraphSpy’s ESTS cookie flow
- Assets
- UIcons by Flaticon