Home

Architecture

The following graphic illustrates the main architecture of GraphSpy in its default configuration.

                                               +---------------+                       
                                               |               |                       
                                               |    Internet   |                       
                                               |               |                       
                                               +---------------+                       
                                                       ^                               
                                                       |                               
                                                       |                               
                                                       |                               
+---------------+                           +---------------------+                    
|               |                           |                     |                    
|    Browser    |-------------------------->|   GraphSpy (Flask)  |                    
|               |   http://127.0.0.1:5000   |                     |                    
+---------------+                           +---------------------+                    
                                                       |                               
                                                       |                               
                                         ~/.gspy/databases/database.db                 
                                                       |                               
                                                       V                               
                                            +---------------------+                    
                                            |                     |                    
                                            |  GraphSpy Database  |                    
                                            |                     |                    
                                            +---------------------+                    

GraphSpy Application

At its core, GraphSpy is a Python Flask application that can be accessed through a web browser on http://127.0.0.1:5000. Both the default interface and port can be changed using the -i and -p arguments respectively.

WARNING: GraphSpy is intended to be executed and accessed from your local machine through a localhost interface. It is not safe to expose the application on an untrusted network where other people might be able to access it, since there is no authentication built-in! In any case, never make GraphSpy accessible from the internet without restricting access through other means such as a reverse proxy, or source IP whitelist. Unauthorized access to your GraphSpy instance would not only put your system at risk, but also all sensitive information from your targets (such as access and refresh tokens) stored in the GraphSpy database.

Database

To facilitate the persistent storage of information (such as access tokens, refresh tokens, device code information, ...), GraphSpy utilizes an SQLite3 disk-based database. The database is automatically initialized at the first run and stored at ~/.gspy/databases/database.db. A different database can be created or selected using the -d argument at run, or from the settings page in the GraphSpy itself.

The ability to create as many databases as you want and switch between them at any time allows you to work on multiple projects at once and keep all information nicely separated.

Internet traffic

The client-server architecture results in most traffic to the internet being initiated from the GraphSpy application. This includes:

• The generation and polling of device codes.
• Creating access tokens with refresh tokens.
• Any API calls with these access tokens towards Microsoft Entra and Office applications

The only exceptions to this are situations where the browser itself needs to perform an action. This includes:

• Any traffic from the Outlook module after opening Outlook through the browser.
• Downloading files from OneDrive or SharePoint. (While the API calls to browse through the files from SharePoint will originate from GraphSpy, the downloading of a file will originate from the browser of the user.)

While this detail should not affect the usage of GraphSpy in general, there might be situations where you want to take this into consideration. (E.g. you are accessing GraphSpy from a host which uses a different public IP address than the host where GraphSpy is running on. Or you rely on GraphSpy to spoof the User-Agent header.)