Skip to content

Security Policy

Operating a remote-control interface for an IDE with terminal access demands enterprise-grade security. The Antimatter project takes the security of your host development environment extremely seriously.

Reporting a vulnerability

If you discover a security vulnerability, please do NOT open a public issue. Instead, use GitHub's private vulnerability reporting or email the maintainers directly.

Supported Versions

Version Supported
main branch
Latest GitHub Release
Older releases

Security Mechanisms

Because Antimatter exposes a local WebSocket server that can proxy terminal commands, we implement multiple overlapping security layers so that compromising any single layer is not sufficient for an attacker to gain access.

256-bit Bearer Token + Ed25519 Handshake

Token generation: On first run, the extension generates a 256-bit Bearer Token with crypto.randomBytes(32) — equivalent entropy to AES-256. It's stored securely in VS Code SecretStorage (OS keychain: Keychain on macOS, Credential Manager on Windows, libsecret on Linux) and persists across IDE restarts, reloads, and even uninstall/reinstall cycles.

Token verification: Every WebSocket connection must present this token. The server checks it with crypto.timingSafeEqual — immune to timing side-channel attacks. Invalid tokens → close code 4001 Unauthorized.

Ed25519 handshake: After the token check, the client sends an AUTH_CHALLENGE nonce. The bridge signs it with its persistent Ed25519 private key and returns AUTH_RESPONSE. The client verifies the signature against the public key received during QR pairing — this proves the bridge's identity and prevents Man-in-the-Middle attacks.

Full details

See the WebSocket Protocol Reference for the complete handshake flow, message fields, and close codes.

Biometric Lock (Physical Security)

The Android app gates sensitive features — particularly the Remote Terminal — behind Android's androidx.biometric API. The terminal proxy only opens after successful fingerprint or face unlock.

Even if your phone is left unlocked on a desk, an unauthorized person cannot execute host commands without passing the biometric check.

Origin Header Validation (CSWSH Protection)

To protect against Cross-Site WebSocket Hijacking (CSWSH), the bridge enforces strict Origin header validation. Only these origins are accepted:

  • vscode-webview://… (the extension's own webview)
  • https://<team>.cloudflareaccess.com (Cloudflare Access)

Malicious websites in your browser cannot silently connect to ws://localhost:8765.

Path Normalization & Sandboxing

The app can request file tree data and file contents. To prevent Local File Arbitrary Read vulnerabilities (e.g. ../../../../etc/passwd), the extension strictly sanitizes and normalizes all incoming file paths. Reads are sandboxed to:

  • The active VS Code workspace
  • The .gemini/antigravity-ide directory

Path traversal attempts are rejected before reaching the filesystem.

Payload Size Limits (DoS Mitigation)

To protect against memory exhaustion attacks and Denial of Service (DoS), the WebSocket router strictly limits the size of incoming payloads.

  • 5MB Limit: Any payload exceeding 5MB is immediately dropped.
  • The server responds with a 4000 close code or a standard error payload if the payload is grossly oversized.

Strict Terminal Allowlist

The Remote Terminal operates under a strict regex-based allowlist. By default, only safe commands (e.g., npm, yarn, git, ls, cat, pwd) are permitted to execute blindly.

Destructive Commands: Commands such as rm trigger a synchronous, blocking modal inside the VS Code UI. The host user must explicitly click "Execute" on their desktop before the command runs.

Secure Tunnels (Cloudflare)

We actively discourage unencrypted public tunnels. Antimatter natively supports:

  • Cloudflare Quick Tunnels — free, auto-provisioned, TLS-encrypted
  • Cloudflare Zero Trust — persistent hostname, OAuth/SAML access policies, service auth

The WebSocket server binds exclusively to 127.0.0.1 — it is never directly accessible from the network. Only Cloudflare's tunnel connector can reach it.

Defense-in-Depth Summary

Layer Protects against Mechanism
TLS (Cloudflare) Network eavesdropping End-to-end encryption between app ↔ Cloudflare edge
Bearer token Unauthorized connections 256-bit random token, timing-safe comparison
Ed25519 handshake MITM / server spoofing Cryptographic identity proof
Origin validation CSWSH attacks Strict allow-list of Origins
Biometric lock Physical device theft Fingerprint/face required for terminal
Path sandboxing Arbitrary file read Normalize + restrict to workspace
Localhost binding LAN snooping Server only on 127.0.0.1