rdfitted/security-audit

Security Audit Skill

End-to-end Google Workspace security audit workflow. Runs in two tiers:

• Tier 1 — org-wide admin-level visibility (OAuth user consent flow, works today). Use first, always.
• Tier 2 — per-user Gmail inspection (service account with domain-wide delegation required). Use after Tier 1 surfaces concern, or for deeper forensics.

Outputs: raw JSON for retention, HTML findings brief for stakeholders.

When to invoke

• A client reports a suspicious message, credential prompt, or incident (smishing, phishing, BEC, wire change, gift-card ask)
• Onboarding a new fractional-CTO client — establish baseline
• Offboarding a departing employee — verify access revoked
• Quarterly access review cadence
• Preparing for cyber insurance questionnaire or client-security review

What you need before running

1. Super Admin access on the target Google Workspace tenant (Ryan is Super Admin on tog-nyc.com, for example)
2. OAuth client secret JSON (desktop-type "installed" client) in the target working directory — one-time setup per client repo
3. Priority-user list — the names/email-fragments to flag with narrative notes (e.g., impersonated, targeted, new hire, financial authority)
4. Output directory — typically Reports/incident_<timestamp>/ inside a client repo

Tier 1 — Admin-level audit (run first, always)

What it checks (last 30 days by default):

1. Domain user enumeration — every account, 2SV status, admin flag, last login, suspended state
2. Priority-user watchlist — substring-match on email local-part + full name; surfaces with narrative context
3. Current OAuth third-party grants per user — scored info / review / high based on scope breadth (gmail, drive, calendar, admin.directory), anonymous grants, suspicious display names
4. Login audit — suspicious_login, login_failure, gov_attack_warning, account_disabled_password_leak
5. Token audit — authorize events (new OAuth grants issued in window — NB: token refreshes also count here, so numbers can be large)
6. Admin audit — role grants/revokes, user create/delete, password resets, forwarding-setting changes, recovery-method updates
7. Drive audit — external-share events (people_with_link, public_on_the_web, shared_externally, shared_outside_domain)

Scopes requested:

• https://www.googleapis.com/auth/admin.directory.user.readonly
• https://www.googleapis.com/auth/admin.directory.user.security
• https://www.googleapis.com/auth/admin.reports.audit.readonly
• https://www.googleapis.com/auth/drive (read-only direct-access; optional — keep if client's repo already uses it)

Run:

python scripts/tier1_audit.py \
    --workdir "/path/to/client/repo" \
    --priority jack="New hire scammed" mufdi="On-site lead" tim="Impersonated" \
    --lookback-days 30

If no token.json exists in the workdir, a browser consent window opens. Log in as the Super Admin whose context we want. The token is saved for re-use.

Output:

• <workdir>/Reports/incident_<timestamp>/raw/*.json — forensic chain-of-custody dumps
• <workdir>/Reports/incident_<timestamp>/summary.json — scored summary
• <workdir>/Reports/incident_<timestamp>/summary.html — dark-themed tech-forward brief

Tier 2 — Per-user Gmail inspection (needs DWD)

What it checks:

1. Forwarding addresses — registered, pending, verified
2. Auto-forwarding — enabled state + destination + disposition (archive/delete/keep)
3. IMAP / POP enablement — exfiltration channels
4. Filters — flags any filter with forward, addLabelIds: TRASH, or removeLabelIds: INBOX on financial-keyword criteria (invoice, wire, bank, payment, ach, routing, password, verify, account)
5. Send-as aliases — flags non-primary aliases (attacker persona or legit shared inbox)
6. Vacation responder — scanned for financial keywords in body

DWD setup (one-time, Super Admin):

1. GCP Console → IAM & Admin → Service Accounts → Create (give it a descriptive name, no roles required)
2. Keys tab → Add Key → JSON → download → save as sa_key.json in workdir (GITIGNORE IT)
3. Note the service account's Unique ID (client_id, ~21-digit numeric)
4. Google Admin Console → Security → API controls → Domain-wide delegation → Add new
5. Paste the client_id; authorize these scopes (comma-separated):

   https://www.googleapis.com/auth/gmail.settings.basic,
   https://www.googleapis.com/auth/gmail.settings.sharing,
   https://www.googleapis.com/auth/admin.directory.user.readonly
   

Run:

python scripts/tier2_gmail_audit.py \
    --workdir "/path/to/client/repo" \
    --key sa_key.json \
    --admin [email protected] \
    --only [email protected] [email protected] [email protected]   # or omit for org-wide

Output:

• <workdir>/Reports/gmail_audit_<timestamp>/results.json
• <workdir>/Reports/gmail_audit_<timestamp>/audit.html

Findings brief (for stakeholder review)

After running Tier 1 (and optionally Tier 2), generate a consolidated briefing document. Uses the tech-forward dark theme consistent with other security deliverables.

python scripts/render_brief.py \
    --tier1 "/path/to/Reports/incident_<timestamp>/summary.json" \
    --tier2 "/path/to/Reports/gmail_audit_<timestamp>/results.json" \  # optional
    --client-name "The Organic Gardener" \
    --incident-context "2026-04-17 smishing incident — Jack Paulchuck scammed for $500 gift cards by attacker impersonating Tim Osborne" \
    --out "/path/to/output/findings-brief.html"

Severity tiers (use in narrative)

| Tier | Meaning | Example | |------|---------|---------| | T1 — Credential exposure | Email/password appeared in breach corpus. Probable for any org. | HIBP hit, leaked-password Google alert | | T2 — Identity compromise | Unauthorized login on a TOG account. Detectable via audit logs. | Impossible travel, anomalous IP with successful login | | T3 — Data exfil / persistence | Data left TOG or attacker established persistence. | Forwarding rules created, OAuth grants to unknown apps, mass Drive downloads |

Typical findings patterns

• Zero 2SV across org — single biggest vulnerability. Fix first, always.
• Shared/archive mailboxes with admin privileges — legacy migration residue. Revoke.
• Dormant accounts with no login in 6+ months — suspend immediately.
• Claude/Monday/Microsoft OAuth grants — almost always legit. Don't cry wolf.
• Login failures clustered on one account — validate user identity before assuming attack.
• No forwarding-setting changes in admin log + no suspicious OAuth apps = mailbox probably not compromised at admin level. Still need Tier 2 to confirm user-level filter compromise.

Anti-patterns (don't do these)

• Don't run Tier 2 org-wide as first step — wait for Tier 1 to surface concern
• Don't commit OAuth tokens, service-account keys, or credentials.json to git — the target repo should have .gitignore covering token*.json, sa_*.json, client_secret_*.json, credentials.json
• Don't interpret high grant-refresh counts as attack activity — Google's token audit double-counts refreshes
• Don't flag OAuth grants to reputable vendors (Claude, Monday, Microsoft, Adobe, Granola) as compromise indicators without corroborating signal

Files in this skill

SKILL.md                       This document
scripts/
  google_auth.py               Self-contained OAuth + service-account helpers
  tier1_audit.py               Org-wide admin-level audit
  tier2_gmail_audit.py         Per-user Gmail audit (needs DWD)
  render_brief.py              Consolidated findings-brief HTML generator
templates/
  findings_brief.html.tmpl     HTML template for the stakeholder brief

Handoff / memory

When this skill surfaces a real incident, add entries to:

• ~/.claude/clients/<client-slug>/decisions.md — what was found, what was remediated
• ~/.claude/clients/<client-slug>/status.md — current security posture, next review date
• Client's main-brain repo memory tree (if it exists) — forensic log, policy impacts