gdmcode

Security hardening

This guide covers deploying gdm in team or enterprise environments where security posture matters.

1. Network requirements

gdm makes outbound HTTPS calls to:

api.x.ai — xAI Grok
generativelanguage.googleapis.com — Google Gemini
api.openai.com — OpenAI Codex

No other external connections are made unless a tool explicitly performs a web search or browser automation task.

Proxy configuration:

Set GDM_HTTPS_PROXY to route all outbound API calls through a corporate proxy:

export GDM_HTTPS_PROXY=https://proxy.corp.example.com:8080

gdm relay mode (/proxy):

For users in restricted regions, the interactive /proxy command can route model requests through a gdm-operated relay. Treat this relay as transport, not secret storage:

Keep provider API keys encrypted locally in the OS keychain through gdm login.
Store only the relay token locally when /proxy token is configured.
Do not persist user provider keys on the relay server.
Use non-reversible token fingerprints for relay rate limiting and abuse detection.
Reject malformed, oversized, or non-JSON request bodies before forwarding upstream.

The relay necessarily sees request and response payloads while proxying them. Deploy it with TLS, centralized access logs, retention limits, and clear user disclosure.

Air-gapped environments:

Use a local model provider (Ollama or vLLM) and set providers.ollama.local_only = true in config.toml. This prevents any cloud fallback.

2. Audit log setup

gdm writes a hash-chained audit log to .gdm/audit.db. Each entry records:

action type and arguments hash
actor identity
timestamp
hash of the previous entry (chain link)

Enable audit enforcement — refuse to run if the audit log is not writable:

# .gdm/team.toml
[policy]
require_audit_log = true

Audit retention:

# config.toml
[audit]
retain_days = 90   # delete entries older than 90 days

Set retain_days according to your compliance requirements (e.g. 365 for most SOC 2 controls).

Verify audit integrity:

gdm doctor    # reports audit log status and last hash

3. Team policy setup

Team policy lives in .gdm/team.toml and should be committed to version control. Policy values override all individual settings — including CLI flags.

Minimal hardened policy:

# .gdm/team.toml
[policy]
policy_enforced       = true
max_autonomy_level    = 2        # require human confirmation for most actions
allow_git_push        = false    # disallow autonomous git push
allow_network         = true
network_allowlist     = ["api.x.ai", "generativelanguage.googleapis.com", "api.openai.com"]
require_audit_log     = true

Trust the config (GPG signing):

For teams that want tamper-evident team.toml, sign the file with GPG and verify in CI:

gpg --sign .gdm/team.toml

Verify in your CI pipeline before any gdm invocation:

gpg --verify .gdm/team.toml.sig .gdm/team.toml || exit 1

Path denylist:

Add a .gdm/instructions.md rule to block the agent from touching sensitive paths:

## Rules
- Never read or modify files matching: `.env`, `*.pem`, `*.key`, `secrets/`

4. Identity configuration

gdm supports two identity modes:

LocalIdentity (default):

The actor is derived from the OS user ($USER / USERNAME). Suitable for single-developer use or when OIDC is not available.

OIDCIdentity (planned):

When available, gdm will accept a JWT from your identity provider and bind actor identity to the verified subject claim. This enables per-user audit trails in shared CI environments.

Until OIDC is implemented, use environment isolation (one OS user per CI job) to ensure accurate actor attribution in audit logs.

5. Secret management

Rules:

API keys, tokens, and passwords must be stored in the OS keychain via gdm login.
Relay tokens should be entered with /proxy token so they are hidden at the terminal.
Use gdm logout <provider> or /logout <provider> to remove keychain/fallback credentials. Environment variables and TOML entries override logout and must be removed manually.
They must never appear in config.toml, team.toml, or any environment variable committed to version control.
team.toml is committed to git — treat it as fully public.

CI environments:

Inject secrets as masked CI environment variables:

# GitHub Actions
env:
  XAI_API_KEY: $

gdm reads XAI_API_KEY, GEMINI_API_KEY, and OPENAI_API_KEY directly from the environment. No gdm login call is needed in CI.

Keychain keys (never put in TOML): xai_api_key, openai_api_key, anthropic_api_key, google_api_key, github_token

6. Bridge security (Chrome extension)

The gdm browser start command starts a local bridge server that the Chrome extension connects to. By default the bridge only accepts connections from localhost.

Configure allowed origins:

# .gdm/config.toml  (do NOT use team.toml -- this is host-specific)
[bridge]
allowed_origins = ["chrome-extension://YOUR_EXTENSION_ID"]

Keep allowed_origins as narrow as possible. Do not set it to "*".

The bridge uses short-lived tokens for pairing; tokens expire after 60 seconds.

7. Prompt injection mitigations

gdm applies the following mitigations against prompt injection attacks embedded in file content or web search results:

Argument scanning — tool arguments are scanned against a denylist of injection patterns (e.g. “ignore previous instructions”, role-override phrases) before execution.
Sandboxed tool output — tool results are injected as tool role messages, not user messages, reducing the model tendency to treat them as authoritative instructions.
Autonomy cap — at autonomy <= 2, the user must confirm any file write or shell command, providing a human review checkpoint even if injection occurs.
Path restrictions — file tools resolve paths relative to the project root and reject traversal sequences (../, absolute paths outside the root).

No mitigation is perfect. For high-sensitivity codebases, use max_autonomy_level = 1 in team policy and review all proposed changes before confirming.

8. SSRF mitigations

Tools that make outbound HTTP requests (web search, browser automation, webhook calls) are subject to SSRF (Server-Side Request Forgery) mitigations:

Network allowlist:

# .gdm/team.toml
[policy]
network_allowlist = [
    "api.x.ai",
    "generativelanguage.googleapis.com",
    "api.openai.com",
    "www.google.com"    # if web search is enabled
]

When network_allowlist is non-empty, any HTTP tool call to a host not on the list is blocked before the connection is made.

Private IP block:

gdm resolves destination hostnames before connecting and blocks requests to RFC-1918 addresses (10.x, 172.16-31.x, 192.168.x), loopback (127.x), and link-local (169.254.x).

Recommendation: always set network_allowlist in team.toml for production deployments.