Project Atlas AetherDev project hub
Atlas project concept

google-groups-guard

google-groups-guard** replaces imperative GAM scripts with a deterministic Rust CLI for reconciling Google Workspace group memberships and enforcing group settings. The binary runs statically linked (musl) and favours idempotence, auditability, and safety rails for day-to-day operations. google-groups-guard plan --groups engineering generate plan artifacts. Review reports///plan.json and plan.csv. Share generated summaries (summary.json, summary.csv) with reviewers or automation. Once approved, google-groups-guard sync-members --groups engineering to apply. Supply --plan to replay a stored plan if required. For permission changes only, run google-groups-guard apply-settings --groups engineering (use --snapshot to log-only). Monitor structured logs (stdout or log file) and Slack/email notifications for success/failure. Run cargo check --target x86_64-unknown-linux-gnu locally if the musl toolchain is unavailable.

Type
System
Lifecycle
Deprecated
Last touched
2025-10-14
Visibility
Public

Purpose

google-groups-guard** replaces imperative GAM scripts with a deterministic Rust CLI for reconciling Google Workspace group memberships and enforcing group settings. The binary runs statically linked (musl) and favours idempotence, auditability, and safety rails for day-to-day operations.

Current state

Last touched: 2025-10-14. Functionality and completeness: Full plan/apply and reporting flow implemented; operational deployment is documented.

Next step

Add baseline automated tests to cover critical flows; Add CI pipeline for build/test/lint; Document deployment/runtime environment (or add Dockerfile); Document interfaces (CLI flags, API endpoints, file formats); Add structured logging and basic health checks.

Interfaces

Inputs
  • TOML configs (Figment layered), optional CSV artifacts, service-account key, impersonated admin account
  • Configuration files (TOML/YAML/JSON/INI/CONF)
  • CSV files
Outputs
  • Plan and summary artifacts under reports/<run_id>/ (JSON/CSV), optional Slack/email notifications
  • CSV files

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Not in scope.

Automation Engines

Not in scope.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Artifacts

  • Plan and summary CSVs for review; config schema defines group profiles, policies, and transforms

Operational notes

Constraints and scars

  • Guard-rail thresholds can block large changes; requires explicit `--force` for bulk removals.

Reliability posture

Failure modes and safe behavior: Plans can be blocked when thresholds are exceeded; `--force` required to override. Idempotency / retries / batching behavior: Idempotent reconciliation; jittered exponential backoff on 429/5xx responses.

Observability

  • Logs: Rust logging framework detected (log/tracing/env_logger). Prometheus client dependency detected. Structured logs never include service account keys or OAuth access tokens. If additional context is required, prefer hashed or redacted identifiers.
  • Metrics/health checks: Optional metrics behind feature flag; health is primarily via `check` command and logs

Security and privacy

No telemetry is emitted. Logs redact errors but never include service account keys or secrets. Service account keys must **never** be committed. Use environment variables or GitLab secrets. Optional metrics are behind the metrics feature flag; email support is behind the mail feature flag. Guard rails ensure the final state never leaves a group without an owner and bulk removals require explicit --force.

Dependencies

Upstream
  • Google Admin Directory API, Groups Settings API, optional SMTP/Slack

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

google-groups-guard

Architecture & Major Components

  • High-level diagram (text):

    • Entry/trigger -> core logic -> outputs (details per docs below)

  • Entry points: src/main.rs, src/lib.rs

  • Top-level folders: .cargo, configs, docker, log, reports, scripts, src, templates, tests

  • src/ submodules: commands, domain, google, reporting, runtime

  • Key abstractions: plan/apply pipeline, membership sources (OU/manual/member), guard rails (bulk removal thresholds, last-owner protection), settings profiles

Setup / Build / Run

  • Build system(s): Cargo.
  • Create a service account with domain-wide delegation, store the JSON key securely, and configure auth.impersonated_admin.
  • Configuration layering uses Figment: base config, environment overlays, env vars (GG_), and CLI overrides.
  • Use plan for dry-run artifacts; use sync-members or apply-settings to mutate state.
  • For systemd installs, use the helper scripts under scripts/ and copy config into /etc/google-groups-guard/.