High-Level Architecture & Security

This document details the Sec-Gemini platform architecture, data persistence policies, and privacy mechanisms. It is designed to provide trusted testers and external clients with full confidence in how their data is handled, stored, and secured.

---

Architecture Overview

The Sec-Gemini system separates Request Submission from Execution, allowing for robust and fine-grained privacy controls.

Participants

The platform is composed of 5 key participants:

1. Client (SDK/TUI): Serves as the user-facing entry point. It submits queries to the cloud.
2. Firestore (Database): Acts as the state of truth. It stores job parameters, input queries, and serialized execution checkpoints.
3. Job Dispatcher: A glue service that listens for Firestore writes and schedules executions.
4. Cloud Tasks: Ensures reliable, rate-limited delivery of execution requests to the worker.
5. Job Worker: The heavy-lifter. It runs the actual Sec Gemini Agent inside Google Cloud Run, reading parameters from Firestore and logging diagnostic data.

System Flow

The following sequence diagram illustrates the flow from a user submitting a query to an agent running in the cloud.

sequenceDiagram
  participant User
  participant CLI as SDK / TUI Client
  participant DB as Firestore
  participant Dispatcher as Job Dispatcher
  participant Queue as Cloud Tasks
  participant Worker as Job Worker

  User->>CLI: submit-job "Audit this..."
  CLI->>DB: Create Job (Status=PENDING)

  par Async Dispatch
      DB->>Dispatcher: on_snapshot (Status=PENDING)
      Dispatcher->>Queue: Create Task (Target=Worker)
  end

  Queue->>Worker: POST /job_worker (Job ID)

  loop Agent Execution Loop
      Worker->>DB: Load Job & Snapshot
      Worker->>Worker: Run Steps
      Worker->>DB: Save Snapshot (Checkpoint)
  end

  Worker->>DB: Update Job (Status=COMPLETED/FAILED)

---

Data Handling & Persistence

Sec-Gemini ensures that your data is not stored permanently or inappropriately accessed.

1. Ephemeral Temporary Cache

Access to persisted data in Firestore is used strictly as a temporary cache to ensure system resilience. In long-running agent workflows, checkpoints are saved so the worker can pick up where it left off in case of an interruption.

2. Automatic Data Expiry & Deletion

To maintain privacy, automatic data retention and expiry are strictly enforced:

• Firestore Job Records: Automatically expired after 7 days from creation.
• Uploaded Files: Automatically expired after 7 days.

3. Encryption at Rest

All data persisted in Firestore and all uploaded files are encrypted at rest using standard Google Cloud encryption mechanisms.

---

Dynamic Logging Suppression

External clients can explicitly suppression agentic “thoughts” and tools text logs to prevent sensitive data leak.

1. Computed Suppression Status

When a job is submitted, the API Hub evaluates user entitlements and preferences:

• User Entitlement Policies: Specific users have entitlements (never_log) that automatically suppress logging by default.
• Explicit User Toggle: Authorized users can pass --disable-logging via the TUI or pass a specific metadata flag in the Python SDK.

2. Real-Time Interception

The Job Worker picks up the job from Firestore and reads the suppression flag. If logging is disabled, the worker’s intercept logic forces the Python root logger level to CRITICAL.

• During normal execution, no logs are produced at INFO, DEBUG, or standard WARNING levels.
• No User Content in Standard Logs: User prompt texts, tool executions, and agent observations are completely suppressed.

---

Client Guarantees

By separating submission from execution and implementing dynamic interception, Sec-Gemini offers strong privacy and trust guarantees:

• No Human Access to Session Data: Access to temporary data (Firestore caching and uploaded files) is strictly restricted to authorized internal service workers and system processes. No direct human viewing or interactive usage is permitted.
• Persistence Limited to System Resilience: For no-log sessions, there is no persistence of agent workflow outputs or user queries outside Firestore, other than critical failures that affect system stability (stack traces only).
• Zero-Day Auditing: Zero user queries or internal agent thoughts appear in standard diagnostic logs.
• Sensitive Data Filter: In the event of a system failure, the critical log payload is filtered to contain only error stack traces and system metrics, protecting proprietary data.