High-Level Architecture & Security

This document details the Sec-Gemini platform architecture, hosted infrastructure on Google Cloud, multi-environment capabilities via Bring Your Own Tool (BYOT), data persistence policies, log expiration rules, and dynamic privacy mechanisms.

---

Architecture & Hosted Agent Overview

Sec-Gemini is an autonomous, agentic AI platform specialized for security research, incident response, digital forensics, and code auditing. Unlike traditional static query-response models, Sec-Gemini operates as an agent—an interactive reasoning engine that iterates over complex tasks through multi-step planning, tool execution, observation loops, and state checkpoints.

To deliver scalability, security, and enterprise reliability, Sec-Gemini runs as a managed hosted solution on Google Cloud Platform (GCP).

Core Google Cloud Infrastructure

The platform separates Request Submission from Execution, decoupling user clients from heavy long-running agent jobs through a serverless, event-driven architecture on Google Cloud:

1. Google Cloud Run: Hosts the stateless, containerized Job Worker services and MCP Microservices (such as sandboxed execution environments, static analysis services, and tool providers). Job Workers run the core Sec-Gemini agent loop in isolated, secure containers that scale dynamically based on workload demand.
2. Firestore (Database): Serves as the centralized state-of-truth and ephemeral state database. It stores job parameters, execution status transitions, and serialized agent memory checkpoints (snapshots) to enable workflow resilience.
3. Google Cloud Logging: Acts as the central operational diagnostic sink. It collects system telemetry and operational metrics from Cloud Run services under strict privacy filters and dynamic logging suppression rules.
4. Cloud Tasks & Job Dispatcher: The Job Dispatcher listens for Firestore job state updates and enqueues execution tasks into Google Cloud Tasks. Cloud Tasks provides rate-limiting, retries, and asynchronous dispatching to Cloud Run workers, guaranteeing reliable execution delivery.
5. Client Interfaces (SDK / TUI / CLI): User-facing entry points that connect to the Sec-Gemini API.

Hosted Request & Execution Flow

The following sequence diagram illustrates the lifecycle of a request from client submission to agent execution on Google Cloud infrastructure:

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 Cloud Run Job Worker
  participant Logging as Cloud Logging

  User->>CLI: submit-job "Audit target repository..."
  CLI->>DB: Create Job (Status=PENDING, Params)

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

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

  loop Agent Execution Loop
      Worker->>DB: Load Job Parameters & Snapshot Checkpoint
      Worker->>Worker: Execute Agent Step & Tool Calls
      Worker->>DB: Save Snapshot Checkpoint (State Resilience)
      opt Logging Enabled
          Worker->>Logging: Stream System Telemetry
      end
  end

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

---

Multi-Environment & Bring Your Own Tool (BYOT) Architecture

Sec-Gemini frequently needs to interact with targets or environments that are unreachable directly from the public cloud. These include:

• Enterprise internal log sources and databases behind corporate firewalls.
• Isolated incident response environments or compromised hosts in segregated networks.
• Hardware debuggers, mobile testing devices, or local lab setups connected directly to an analyst’s workstation.

To bridge this gap without exposing client networks or requiring inbound public firewall rules, Sec-Gemini implements a Multi-Environment / Bring Your Own Tool (BYOT) architecture.

How BYOT Works

sequenceDiagram
  participant Agent as Sec-Gemini Agent (Cloud Run)
  participant MCPServer as BYOT MCP Server (Cloud Run)
  participant Hub as BYOT Hub (Google Cloud)
  participant DB as Firestore
  participant Client as Local BYOT Client (sec-gemini-byot)

  Client->>Hub: Outbound gRPC Bi-directional Stream (TLS)
  Note over Client,Hub: Outbound Tunnel Established (No Inbound Ports)

  Agent->>MCPServer: Call Tool (e.g. "run_terminal")
  MCPServer->>DB: Dispatch Task (byotTasks)
  Hub->>Client: Forward Request over gRPC Stream
  Client->>Client: Execute Local Tool (File / Shell / FastMCP)
  Client->>Hub: Return Execution Result
  Hub->>DB: Update Task Result
  MCPServer->>Agent: Return Tool Output to Agent

1. Outbound gRPC Tunnel: The analyst runs the sec-gemini-byot client locally (installed via pip install sec-gemini). The client establishes a persistent, outbound gRPC bi-directional stream to the cloud-hosted BYOT Hub. Because the connection is initiated outbound, no incoming network ports or static public IPs are required on the client side.
2. Cloud BYOT MCP Server Gateway: When the agent in Cloud Run invokes a tool registered to the user’s BYOT client, it talks to the cloud BYOT MCP Server. The server queues the tool call in Firestore (byotWorkers/{worker_id}/byotTasks), which the BYOT Hub picks up and sends across the gRPC stream.
3. Local Execution & Result Return: The local BYOT client executes the tool against the local environment (e.g. local shell, local files, or custom local FastMCP servers) and streams the output back to the BYOT Hub over gRPC, returning the output to the cloud agent loop.
4. Authentication & Tenant Isolation: BYOT authentication relies on Sec-Gemini API keys. The BYOT Hub validates keys and isolates sessions under users/{user_id}/byot/, ensuring strict multi-tenant separation.

---

Data Handling & Persistence Policies

Sec-Gemini is engineered to ensure user code, queries, and analytical outputs are treated with maximum confidentiality. For a comprehensive overview of user prompt confidentiality, voluntary unlisted sharing, account deletion, data download rights, and terms of service, see the dedicated Privacy & Data Protection Guide.

1. Ephemeral State Caching

Persisted data in Firestore serves strictly as an ephemeral temporary cache for system resilience. Long-running agent jobs record serialized memory snapshots so that if a Cloud Run container reaches a soft timeout (e.g. 25 minutes) or encounters a transient infrastructure disruption, a replacement worker instance can pick up execution seamlessly.

2. Encryption at Rest & in Transit

• At Rest: All Firestore documents, agent state checkpoints, and uploaded files are encrypted at rest using standard Google Cloud AES-256 encryption.
• In Transit: All traffic between SDK/TUI clients, the API Hub, Cloud Run services, and BYOT clients is encrypted in transit using TLS 1.3 and gRPC transport security.

---

Log Expiration & Retention Schedules

To safeguard data privacy, Sec-Gemini enforces strict, automated data retention limits and expiration schedules across all cloud storage layers:

• Firestore Job Records & Snapshots: Automatically expired and permanently deleted after 7 days from creation.
• Uploaded Files & Artifacts: Automatically expired and permanently deleted after 7 days.
• User-Initiated Session Deletion: Users can manually delete their active or historical sessions at any time, either programmatically through the Python SDK or interactively via the TUI and Web interface.
• Google Cloud Logging Retention: Operational diagnostic logs stored in Google Cloud Logging are retained for 30 days, after which they are permanently purged from Google Cloud. Note that for no-log sessions (governed by the logging policy of the user’s API key), no session logs are written to Cloud Logging, other than critical exceptions (which are sanitized of user data).

---

Dynamic Logging Suppression & Limited Logging

Sec-Gemini emphasizes limited logging by design to prevent sensitive user prompts, proprietary code, tool payloads, and agent reasoning steps from being captured in diagnostic logs.

1. API Key Logging Policies & Computed Suppression Status

When a job is submitted via the API Hub, the system evaluates the logging policy attached to the user’s API key and request parameters:

• API Key Policies & Entitlements: Users with the never_log entitlement policy tied to their API key have logging automatically disabled by default across all created jobs.
• Explicit User Controls: Authorized users can pass --disable-logging via the CLI/TUI or pass disable_logging: true in the prompt metadata when using the Python SDK.

If triggered, the disable_logging: true flag is recorded in the job parameters in Firestore.

2. Real-Time Worker Interception

When a Cloud Run Job Worker claims a job with logging suppressed, its internal logging framework interceptor dynamically adjusts the runtime environment:

• Root Logger Silencing: The root Python logger level is set to logging.CRITICAL.
• Complete Output Suppression: Standard informational (INFO), debugging (DEBUG), and standard warning (WARNING) log handlers are completely silenced.
• No User Content Leakage: User prompts, code snippets, tool inputs/outputs, and agent chain-of-thought steps are never written to Google Cloud Logging.

3. Automated CI Verification of Log Absence

To guarantee that logging suppression mechanisms operate effectively and without regressions:

• Automated CI Test Pipeline: The complete absence of logs is automatically verified through continuous integration testing.
• End-to-End Log Verification: The CI suite dispatches end-to-end test jobs with logging suppression enabled, then actively queries Google Cloud Logging to assert that zero log entries, prompt payloads, agent thoughts, or tool outputs were generated or retained.

4. Sanitized Error Stack Traces

In the rare event of an unhandled infrastructure exception or worker crash, log interceptors filter the error payload to emit only system metric names and sanitized stack traces, stripping out any embedded user prompt text or proprietary code.