A CLI tool for examining Google Apps login events.

To start you need Maxmind's GeoIPlite data files:

./GeoIP_data/update.sh

Then install the required Python modules:

pip install -r requirements.txt

This tool is developed with python3 in mind, but aside from some UTF-8 handling it will mostly work in python2.

Next, you must provision OAuth credentials for the tool to run:

1. Log in to GApps using a Superadmin account.
2. Go to the Google APIs Credentials page and select "Create credentials".
3. Select "OAuth Client ID" as the type of credential to create.
4. For "application type" select "Other" and enter "SuspiciousLogger" or something which will clearly be associated with the purpose.
5. The API credentials page will now yield a client_id and client_secret.
6. Copy client_secrets.json.example to client_secrets.json.
7. Copy and paste the client_id and client_secret into the matching fields in client_secrets.json.
8. Finally, run a test query in the tool (i.e. ./SuspiciousLogger.py ${USER}@example.com list), this will lead to the tool presenting a URL.
   1. Copy and paste the URL into a browser session where your Superadmin account from step one is logged in.
   2. Accept the access requested by the tool, which will yield a code.
   3. Paste the code from the prior step into the SuspiciousLogger prompt.

NOTE: This API is near real-time but inexplicably lags behind email notices of "suspicious logins" by days, weeks or even months. THANKS GOOGLE.

List all logins from an IP:

./SuspiciousLogger.py 10.0.0.33 list

List all logins from a CIDR block:

./SuspiciousLogger.py 10.0.0.0/24 list

List all logins for a User:

./SuspiciousLogger.py [email protected] list

List only successful logins:

./SuspiciousLogger.py [email protected] events login_success

List all failed google_password events:

./SuspiciousLogger.py [email protected] events login_failure --filters 'login_type==google_password'

List all suspicious logins:

./SuspiciousLogger.py all events login_success --filters 'is_suspicious==true'

List all suspicious logins for a user:

./SuspiciousLogger.py [email protected] events login_success --filters 'is_suspicious==true'

List all suspicious SAML logins from a CIDR block:

./SuspiciousLogger.py 10.0.0.0/24 events login_success --filters 'login_type==saml,is_suspicious==true'

List all non-suspicious, non-SAML logins from a CIDR block:

./SuspiciousLogger.py 10.0.0.0/24 events login_success --filters 'login_type<>saml,is_suspicious<>true'

The documentation for the google-api-python-client library is avialable here:

https://developers.google.com/api-client-library/python/start/get_started

Documentation on some relevant event types for events and "--filters":

https://developers.google.com/admin-sdk/reports/v1/reference/activity-ref-appendix-a/admin-gmail-events
https://developers.google.com/admin-sdk/reports/v1/reference/activity-ref-appendix-a/login-event-names