Google Workspace Inspector

# gws-inspector-go — Architecture Specification

Implemented in grclanker as the first Google Workspace tool family:

- `gws_check_access`
- `gws_assess_identity`
- `gws_assess_admin_access`
- `gws_assess_integrations`
- `gws_assess_monitoring`
- `gws_export_audit_bundle`

The current grclanker implementation keeps the original multi-framework audit intent, but the first slice is intentionally bounded to the stable Google Workspace Admin SDK surfaces that are well suited to read-only GRC assessment:

- Admin SDK Directory API for users, roles, and role assignments
- Admin SDK Reports API for login, admin, and token audit activity
- Alert Center API for tenant security alerts
- Per-user token inventory for bounded third-party OAuth review

The v1 auth path centers on service-account-based domain-wide delegated access, with optional direct bearer-token support for smoke tests or externally managed auth flows.

## Overview

Go implementation of gws-inspector — a multi-framework compliance audit tool for Google Workspace. This is a port of the Python `gws-inspector` package, providing a single-binary distribution with no runtime dependencies.

## Reference Implementation

The Python implementation is the source of truth: [github.com/hackIDLE/gws-inspector-py](https://github.com/hackIDLE/gws-inspector-py)

## Architecture

Mirror the Python package structure:

```
cmd/
└── gws-inspector/
    └── main.go                 # CLI entry point (cobra or kong)

internal/
├── auth/
│   └── auth.go                 # Service account + OAuth2 authentication
├── client/
│   └── client.go               # GWSClient — wraps multiple Google API services
├── collector/
│   └── collector.go            # GWSDataCollector → GWSData
├── models/
│   ├── finding.go              # ComplianceFinding
│   ├── data.go                 # GWSData (in-memory data bus)
│   └── analysis.go             # Intermediate analysis types
├── engine/
│   └── engine.go               # AuditEngine: collect → analyze → report → archive
├── output/
│   └── output.go               # OutputManager
├── analyzers/
│   ├── registry.go             # Framework registry pattern
│   ├── common.go               # Shared analysis functions
│   ├── fedramp.go              # FedRAMP (NIST 800-53)
│   ├── cmmc.go                 # CMMC 2.0 (NIST 800-171)
│   ├── soc2.go                 # SOC 2
│   ├── stig.go                 # DISA STIG
│   ├── irap.go                 # IRAP (ISM + Essential Eight)
│   ├── ismap.go                # ISMAP (ISO 27001)
│   ├── pci_dss.go              # PCI-DSS 4.0.1
│   └── cis.go                  # CIS Google Workspace Benchmark
└── reporters/
    ├── registry.go
    ├── executive.go
    ├── matrix.go
    ├── validation.go
    ├── fedramp.go, cmmc.go, soc2.go, stig.go
    ├── irap.go, ismap.go, pci_dss.go
    └── cis.go
```

## Key Dependencies

```go
require (
    golang.org/x/oauth2
    google.golang.org/api v0.200+
    github.com/spf13/cobra         // or alecthomas/kong
)
```

Google API packages:
- `google.golang.org/api/admin/directory/v1`
- `google.golang.org/api/admin/reports/v1`
- `google.golang.org/api/alertcenter/v1beta1`
- `google.golang.org/api/cloudidentity/v1`
- `google.golang.org/api/chromepolicy/v1`

## Google APIs (6 services)

| API | Go Package | Purpose |
|-----|-----------|---------|
| Admin Directory | `admin/directory/v1` | Users, groups, OUs, roles, domains, mobile devices |
| Admin Reports | `admin/reports/v1` | Audit logs (admin, login, drive, token) |
| Policy API | TBD (may need raw HTTP) | 2SV, passwords, sessions, security settings per OU |
| Alert Center | `alertcenter/v1beta1` | Security alerts |
| Chrome Policy | `chromepolicy/v1` | Browser policies per OU |
| Cloud Identity | `cloudidentity/v1` | Device management |

## Compliance Frameworks (8)

1. FedRAMP (NIST 800-53)
2. CMMC 2.0 (NIST 800-171)
3. SOC 2
4. DISA STIG (CIS-mapped)
5. IRAP (ISM + Essential Eight)
6. ISMAP (ISO 27001)
7. PCI-DSS 4.0.1
8. CIS Google Workspace Benchmark v1.2.0

## Security Controls (19 checks)

Identical to the Python implementation — see the Python repo's plan for the full control-to-framework matrix.

## CLI Interface

```bash
gws-inspector -c credentials.json -a admin@example.com -d example.com
gws-inspector -c credentials.json -a admin@example.com -d example.com --frameworks fedramp,cmmc
```

Flags:
- `-c, --credentials` — service account JSON or OAuth client secrets
- `-a, --admin-email` — admin email for delegation
- `-d, --domain` — Google Workspace domain
- `--oauth` — use OAuth flow
- `--frameworks` — comma-separated framework list
- `-o, --output-dir` — custom output dir
- `-V, --version`

Environment variables: `GWS_CREDENTIALS_FILE`, `GWS_ADMIN_EMAIL`, `GWS_DOMAIN`

## Build

```bash
go build -o gws-inspector ./cmd/gws-inspector
```

## Status

**Not yet implemented.** This repo contains only this specification. The Python implementation should be used as the reference for porting.