GraphSpy is a browser-based GUI tool for exploring what an attacker — or a defender replaying one — can do with stolen or granted access and refresh tokens in Entra ID and Microsoft 365 during authorized assessments.
| Tool | RedByte1337/GraphSpy — browser-based initial access and post-exploitation GUI for Entra ID and Microsoft 365, ~1395 stars, BSD-3-Clause |
| Category | Cloud identity attack simulation / M365 post-exploitation framework |
| Primary Use | Managing and exercising access tokens, refresh tokens, PRTs, and WinHello keys against the Microsoft Graph API during authorized engagements |
| Safe Use | For penetration testers and security researchers working under explicit written authorization against owned or consented tenant environments, or in lab tenants |
| Telemetry Note | All activity surfaces in Entra ID sign-in and audit logs: device code authentications, new device registrations, MFA method registrations, PRT issuance, and anomalous Microsoft Graph API reads — prime detection signals for blue teams |
GraphSpy, published by RedByte1337 under a BSD-3-Clause license, occupies a specific niche in the Microsoft cloud attack-simulation landscape: it wraps the Microsoft Graph API and related endpoints in a local browser-based GUI so that an operator holding tokens can interact with Outlook, OneDrive, SharePoint, Teams, and Entra ID the way a legitimate user would, rather than through raw API calls. The README is explicit about the motivation — existing command-line tools offered piecemeal functionality, but none matched the intuitive experience of the native applications, particularly the file-explorer feel of OneDrive. At roughly 1395 stars and distributed on PyPI, it has clearly resonated with the offensive-and-defensive Microsoft 365 community.
Installation is deliberately low-friction, which matters for consultants moving between engagements. The recommended path is pipx install graphspy, using pipx to isolate dependencies and avoid the classic Python version-conflict mess. The project targets Python 3.10+, is written largely in HTML for the front end, and is stated to work across operating systems, tested mainly on Linux and Windows. Launching the bare graphspy command starts a local web server on http://127.0.0.1:5000, and the -i and -p flags let you change the listening interface and port — a design that keeps everything on-box by default.
Architecturally, the tool is a thin, ergonomic layer over token handling. Its core primitive is a database-backed token store: you keep access tokens and refresh tokens for multiple users and scopes in one place, switch between them from a sidebar on any page, and mint fresh access tokens on demand. The README's development section points to DEVELOPMENT.md describing the architecture, request lifecycle, and schema model, which signals this is a maintained codebase with extension rules rather than a throwaway script. Multiple named databases are supported precisely so a consultant running several concurrent assessments can keep tokens and device codes segregated per client.
The device code module is where initial-access simulation lives. GraphSpy can create and poll multiple device codes simultaneously, and when a user completes authentication, the resulting access and refresh tokens are automatically persisted. Configurable post-authentication actions extend this: a Device PRT option registers or joins a new device in Entra ID, extracts the device certificate, and derives a Primary Refresh Token, while the Winhello action layers on an attempted Windows Hello for Business enrollment to obtain WinHello keys. Understanding this chain is as valuable defensively as offensively — every one of these steps generates auditable events in the target tenant.
PRTs deserve their own paragraph because the README treats them as the crown jewel of the token hierarchy. Unlike a normal refresh token bound to a single application, a PRT can be exchanged for access tokens for any application or scope, FOCI and non-FOCI alike. GraphSpy can also convert stored PRTs into PRT cookies importable directly into a browser, yielding full interactive SSO across web applications integrated with Entra ID. The Windows Hello for Business module rounds out the persistence story: registered or imported whfb keys can regenerate PRTs even after a password reset, which is precisely the scenario defenders need to test when validating whether credential rotation actually evicts an intruder.
The MFA Methods module lets the operator view, modify, and create authentication methods on a compromised account — Microsoft Authenticator, custom OTP, FIDO security keys, alternate email, and phone-based SMS or voice. Notably, GraphSpy can act as its own TOTP generator on the fly. From a purple-team perspective this is a direct exercise of the persistence techniques catalogued for identity platforms, and it maps cleanly to detection content: unexpected MFA method registration on an account is a high-signal alert in any mature Entra ID monitoring setup.
Data access is where the GUI metaphor pays off. A file explorer covers OneDrive and accessible SharePoint sites, with upload and download support plus views of recently accessed and shared files. The Outlook module offers one-click opening of the web mail client using a FOCI access token, or a full MS Graph-based mail client that lists, reads, searches, deletes, replies to, and sends HTML-formatted email with attachments. A Teams module reads and sends messages via the skype API (https://api.spaces.skype.com/). For broader discovery, the Graph Searching feature runs keyword queries across Microsoft 365 through the Microsoft Search API — the README's own example of searching for terms like "password" makes the internal-threat-model implications obvious, and equally makes clear what DLP and eDiscovery teams should be monitoring.
Rounding out the capability set are Custom Requests — arbitrary API calls signed with any token in the store, with templated requests containing variables saved for reuse — and an Entra ID module listing users with their group memberships, role assignments, devices, app roles, and API permissions. The roadmap section is honest about gaps: password and ESTSAuth cookie authentication, automatic token refreshing, an improved Teams module, expanded Entra ID enumeration including Conditional Access Policies, and cleaner exception handling. The credits section is a good map of the research lineage, acknowledging TokenTactics, AADInternals, ROADtools, GraphRunner, and foundational device-code phishing research.
For defenders, GraphSpy is best read as a checklist of identity-attack surfaces: device code flows, rogue device registrations, PRT abuse, whfb enrollment, MFA method tampering, and token-only Graph API access. Every module it offers corresponds to an observable in Entra ID sign-in, audit, and provisioning logs. For authorized operators — pentesters with scoped rules of engagement, purple teams in lab tenants, researchers studying M365 identity attacks — it consolidates what used to require a half-dozen separate scripts into one auditable interface. As always with post-exploitation tooling, the ethics live in the engagement letter; the tool itself is simply the most polished expression yet of what a token in Microsoft's cloud is actually worth.
RedByte1337/GraphSpy.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.