Google Workspace Admin — AI Security Analyzer

A security tool for Google Workspace Administrators that pulls audit logs directly from your Workspace Admin Console (via the Admin SDK Reports API) and uses Gemini AI to automatically detect suspicious activity — such as unauthorized logins, privilege escalation, data exfiltration via Drive, and unusual API token grants.

Note: All data analyzed by this tool comes from Google Workspace Admin audit logs — the same logs you see in the Admin Console under Reporting > Audit and investigation. A Google Cloud Project is only needed to create the Service Account credentials that authenticate against the Workspace Admin APIs.

Prerequisites

1. Python 3.8+
2. Google Workspace Super Admin access (to configure domain-wide delegation and to impersonate).
3. A Google Cloud Project — only used to create a Service Account for API authentication.
4. A Gemini API Key (free from Google AI Studio).

Setup

Option A: Automated Setup (Recommended)

Requires the gcloud CLI installed and authenticated (gcloud auth login).

./setup.sh

This interactive script will:

1. Create the Python virtual environment and install dependencies.
2. Let you select or create a GCP project.
3. Enable the Admin SDK API.
4. Create a Service Account and download its JSON key.
5. Generate your .env file from prompts.
6. Walk you through the one manual step — authorizing domain-wide delegation in the Workspace Admin Console.

---

Option B: Manual Setup

Click to expand manual instructions

1. Install Dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Create API Credentials (One-Time)

a. Create a Service Account in Google Cloud

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one linked to your Workspace org).
3. Go to APIs & Services > Library and enable the Admin SDK API.
4. Go to IAM & Admin > Service Accounts, create a new Service Account, and download its JSON key. Save it as credentials.json in this project directory.

b. Authorize the Service Account in Google Workspace Admin Console

1. Open the Google Workspace Admin Console.
2. Go to Security > Access and data control > API Controls > Domain-wide Delegation.
3. Click Add new and enter:
   • Client ID: The Service Account's Client ID (found in the JSON key or GCP console).
   • OAuth Scopes: https://www.googleapis.com/auth/admin.reports.audit.readonly
4. Click Authorize.

3. Configure Environment Variables

cp .env.example .env

Edit .env and set:

• WORKSPACE_DOMAIN: Your Google Workspace domain (e.g., yourcompany.com).
• SERVICE_ACCOUNT_FILE: Path to the JSON key (default: credentials.json).
• DELEGATED_ADMIN_EMAIL: Email of a Workspace Super Admin to impersonate.
• GEMINI_API_KEY: Your Gemini API Key from Google AI Studio.

Usage

Launch modes

python main.py              # interactive menu — choose scan or investigate
python main.py --scan       # go straight to routine scan
python main.py --investigate  # go straight to investigation CLI

Mode 1: Routine Scan (--scan)

Fetches the last 24 hours of logs across all monitored applications and runs an automated AI analysis. Good for daily security checks.

Mode 2: Agentic Investigation (--investigate)

Opens an autonomous AI agent that interprets your natural-language request and decides on its own which logs to fetch, analyzes them, and fetches more data if needed — all without you specifying anything technical.

▸ user john@acme.com suspects they've been hacked

The agent will autonomously:

1. Fetch login logs → check for suspicious sign-ins.
2. Fetch drive logs → check for data exfiltration.
3. Fetch token logs → check for unauthorized app access.
4. Correlate across log types and deliver a full forensic report.
5. Stay in session for follow-up questions (with full context retained):

▸ did they share any files externally?
▸ what IPs did they log in from?
▸ check admin logs too — were their privileges changed?

You can also make broader requests without specifying a user:

▸ run a full security sweep of the organization
▸ look for brute force login attempts across all users
▸ check for suspicious admin activity in the last 48 hours

Commands: /new (fresh session) · /quit (exit)

What Logs Are Analyzed?

Application	What It Covers
login	User sign-ins, failed attempts, suspicious login locations
admin	Admin console changes, privilege escalation, org unit modifications
drive	File sharing, downloads, external sharing, bulk deletions
token	OAuth token grants, third-party app authorizations

Customization

• Change what is monitored: Edit APPLICATIONS_TO_MONITOR in config.py.
• Change how much data is fetched: Edit MAX_RESULTS_PER_FETCH in config.py.
• Change the AI model: Edit the model name in analyzer.py (default: gemini-2.5-flash).