fix(ssh): add opt-in SSRF guard for SSH bastion hosts

SshTunnelService passed request.getSshHost() straight to jsch.getSession()
with no validation, so an authenticated user who can create a connection
could aim the tunnel at the cloud metadata endpoint (169.254.169.254) or
internal hosts and use the backend as a probe inside the network. This is
CodeQL alert #138 (java/ssrf), open since the initial commit — the file had
never been modified, and the "fixed then reappeared" timeline on that alert
was scan flapping, not a reverted fix.

SshHostGuard resolves the host and checks every returned address rather than
matching the literal string, so a public hostname whose A record points at a
private or link-local address is still refused. Covers loopback, wildcard,
link-local, RFC1918, CGNAT, multicast, IPv6 ULA, and IPv4-mapped IPv6 forms.
It sits in createSession, so establishTunnel and testSshConnection are both
covered by one call site.

testSshConnection calls the guard outside its try block: that method catches
broad Exception and returns false, which would render a blocked host as an
ordinary auth failure.

The guard ships disabled. Bastions legitimately live on RFC1918 networks, so
enabling it by default would break existing self-hosted installs on upgrade.
Note this means a default install is as exposed as before while the CodeQL
alert closes — the sanitizer is on the call path regardless of the flag — so
a green #138 does not mean deployments are protected. Documented in CLAUDE.md.

Author: notSumit25

CLAUDE.md

@@ -197,7 +197,7 @@ returns a number).
 ### Backend Rules
 1. **Database Provider Registry**: Use `DatabaseProviderRegistry` for all DB-specific operations. Do NOT add if/else or switch for database types.
 2. **LLM Provider Registry**: Use `LlmProviderRegistry` for all provider-specific LLM behavior. Do NOT add if/else or switch on provider type. Chat and embedding providers are registered and resolved independently — some providers offer only one. Providers are *factories* over credentials, not `ChatModel`s, so credentials stay resolvable per call and key rotation needs no restart.
-3. **SSH-Aware Access**: Always use `ConnectionService.getJdbcTemplate(connectionId, request)` — handles SSH tunneling transparently.
+3. **SSH-Aware Access**: Always use `ConnectionService.getJdbcTemplate(connectionId, request)` — handles SSH tunneling transparently. The bastion host is screened by `SshHostGuard` before any session is created (see SSRF guard below).
 4. **SQL Rule**: All generated SQL MUST use table-qualified column names (`table.column_name`).
 5. **RAG Caching**: Three-tier cache (memory → Redis → Azure Search). Redis failure is graceful (app continues without caching).
 6. **Virtual Threads**: Enabled for concurrency (JDK 25).
@@ -321,6 +321,36 @@ it against a real database — not a theoretical hardening pass.
   constructs a real `MySQLQueryExecutionProvider`. Do not reintroduce a stubbed
   dialect here; the mock is what let the blocker ship.
 
+### SSH Tunnel SSRF Guard
+
+`SshHostGuard` screens `request.getSshHost()` before `jsch.getSession(...)` in
+`SshTunnelService.createSession`, closing CodeQL `java/ssrf` alert #138. Both entry
+points are covered by that single call site (`establishTunnel` and
+`testSshConnection`).
+
+- **It resolves the host and checks every returned address**, not just the literal
+  string. A public hostname whose A record points at `169.254.169.254` or `10.x` is
+  still refused — a string-only check is defeated by one DNS record.
+- Blocked: loopback, wildcard, link-local (cloud metadata), RFC1918, CGNAT
+  (`100.64/10`), multicast, IPv6 ULA (`fc00::/7`), and IPv4-mapped/compatible IPv6
+  forms that smuggle a blocked v4 address through a v6 literal.
+- **`testSshConnection` calls the guard *outside* its try block.** That method catches
+  broad `Exception` and returns `false`, so a guard rejection inside it would render a
+  blocked host as an ordinary auth failure — the silent-failure anti-pattern above.
+  It propagates `IllegalArgumentException` instead, matching how a missing SSH password
+  already surfaces.
+- **It ships disabled** (`deepsql.ssh.host-guard.enabled=false`). Bastions legitimately
+  live on RFC1918 networks, so enabling it by default would break existing self-hosted
+  installs on upgrade. The trade-off is explicit: **on a default install the SSRF
+  surface is open** — an authenticated user who can create connections can still point
+  the tunnel at `169.254.169.254` or internal hosts. The CodeQL alert closes either way
+  (the sanitizer is on the call path regardless of the flag), so a closed alert here
+  does **not** mean deployments are protected. Do not read #138 going green as
+  "SSRF handled".
+- Operators who want the protection set `enabled=true` and allowlist their own bastion
+  via `deepsql.ssh.host-guard.allowed-hosts` (exact host, or a leading-dot suffix like
+  `.corp.internal`).
+
 ### Data Model Rules
 
 - **`mcp_tokens.user_id` is a non-null FK with no cascade.** Deleting a user who holds

backend/src/main/java/com/dbaagent/service/SshHostGuard.java

@@ -0,0 +1,123 @@
+package com.dbaagent.service;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import java.net.Inet4Address;
+import java.net.Inet6Address;
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.util.Locale;
+
+/**
+ * Rejects SSH bastion hosts that point back into infrastructure the caller
+ * should not reach through DeepSQL — loopback, link-local (including the cloud
+ * metadata endpoint), and RFC1918 ranges.
+ *
+ * The host is resolved and every returned address is checked, so a public
+ * hostname whose A record points at 10.x or 169.254.169.254 is still refused.
+ */
+@Component
+@Slf4j
+public class SshHostGuard {
+
+    private final SshHostGuardProperties properties;
+
+    public SshHostGuard(SshHostGuardProperties properties) {
+        this.properties = properties;
+    }
+
+    public void assertAllowed(String sshHost) {
+        if (sshHost == null || sshHost.isBlank()) {
+            throw new IllegalArgumentException("SSH host is required");
+        }
+
+        String host = normalize(sshHost);
+
+        if (!properties.isEnabled() || isExplicitlyAllowed(host)) {
+            return;
+        }
+
+        InetAddress[] addresses;
+        try {
+            addresses = InetAddress.getAllByName(host);
+        } catch (UnknownHostException e) {
+            throw new IllegalArgumentException("SSH host could not be resolved: " + sshHost);
+        }
+
+        for (InetAddress address : addresses) {
+            if (isBlocked(address)) {
+                log.warn("Blocked SSH tunnel to restricted host {} (resolved to {})",
+                        sshHost, address.getHostAddress());
+                throw new IllegalArgumentException(
+                        "SSH host '" + sshHost + "' resolves to a restricted address ("
+                                + address.getHostAddress() + "). Add it to "
+                                + "deepsql.ssh.host-guard.allowed-hosts if this is intentional.");
+            }
+        }
+    }
+
+    private boolean isExplicitlyAllowed(String host) {
+        for (String allowed : properties.getAllowedHosts()) {
+            if (allowed == null || allowed.isBlank()) continue;
+            String candidate = normalize(allowed);
+            if (candidate.startsWith(".")) {
+                if (host.endsWith(candidate)) return true;
+            } else if (host.equals(candidate)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean isBlocked(InetAddress address) {
+        if (address.isLoopbackAddress()
+                || address.isAnyLocalAddress()
+                || address.isLinkLocalAddress()
+                || address.isSiteLocalAddress()
+                || address.isMulticastAddress()) {
+            return true;
+        }
+        if (address instanceof Inet4Address) {
+            return isBlockedIpv4(address.getAddress());
+        }
+        if (address instanceof Inet6Address v6) {
+            // Unique local addresses (fc00::/7) have no isSiteLocalAddress() mapping in Java.
+            if ((v6.getAddress()[0] & 0xFE) == 0xFC) return true;
+            // IPv4-mapped/compatible forms smuggle a blocked v4 address through a v6 literal.
+            byte[] embedded = embeddedIpv4(v6);
+            return embedded != null && isBlockedIpv4(embedded);
+        }
+        return false;
+    }
+
+    private boolean isBlockedIpv4(byte[] octets) {
+        int first = octets[0] & 0xFF;
+        int second = octets[1] & 0xFF;
+        // 100.64.0.0/10 carrier-grade NAT, used for cloud-internal routing.
+        if (first == 100 && second >= 64 && second <= 127) return true;
+        // 192.0.0.0/24 IETF protocol assignments.
+        if (first == 192 && second == 0 && (octets[2] & 0xFF) == 0) return true;
+        // 0.0.0.0/8 "this network".
+        return first == 0;
+    }
+
+    private byte[] embeddedIpv4(Inet6Address address) {
+        byte[] bytes = address.getAddress();
+        for (int i = 0; i < 10; i++) {
+            if (bytes[i] != 0) return null;
+        }
+        boolean mapped = (bytes[10] & 0xFF) == 0xFF && (bytes[11] & 0xFF) == 0xFF;
+        boolean compat = bytes[10] == 0 && bytes[11] == 0;
+        if (!mapped && !compat) return null;
+        return new byte[]{bytes[12], bytes[13], bytes[14], bytes[15]};
+    }
+
+    private String normalize(String host) {
+        String trimmed = host.trim().toLowerCase(Locale.ROOT);
+        if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+            trimmed = trimmed.substring(1, trimmed.length() - 1);
+        }
+        return trimmed;
+    }
+}

backend/src/main/java/com/dbaagent/service/SshHostGuardProperties.java

@@ -0,0 +1,32 @@
+package com.dbaagent.service;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Binds the SSH bastion host guard.
+ *
+ * Off by default: bastions legitimately live on RFC1918 networks, so enabling
+ * this would break existing self-hosted installs on upgrade. Operators who want
+ * the protection set {@code deepsql.ssh.host-guard.enabled=true} and allowlist
+ * their own bastion. Disabled means the SSRF surface is open — see the SSH
+ * Tunnel SSRF Guard section in CLAUDE.md.
+ */
+@Component
+@ConfigurationProperties(prefix = "deepsql.ssh.host-guard")
+@Data
+public class SshHostGuardProperties {
+
+    private boolean enabled = false;
+
+    /**
+     * Hosts exempt from the private/link-local block. Matched case-insensitively
+     * against the literal value, and against the resolved IP for hostnames.
+     * A leading "." denotes a domain suffix match (".corp.example.com").
+     */
+    private List<String> allowedHosts = new ArrayList<>();
+}

backend/src/main/java/com/dbaagent/service/SshTunnelService.java

@@ -21,6 +21,7 @@
 public class SshTunnelService {
 
     private final DatabaseProviderRegistry providerRegistry;
+    private final SshHostGuard sshHostGuard;
 
     private static final int SSH_CONNECT_TIMEOUT = 30000; // 30 seconds
     private static final String LOCAL_BIND_HOST = "127.0.0.1";
@@ -33,8 +34,9 @@ public class SshTunnelService {
         for (int i = 0; i < LOCK_STRIPES; i++) tunnelLocks[i] = new Object();
     }
 
-    public SshTunnelService(DatabaseProviderRegistry providerRegistry) {
+    public SshTunnelService(DatabaseProviderRegistry providerRegistry, SshHostGuard sshHostGuard) {
         this.providerRegistry = providerRegistry;
+        this.sshHostGuard = sshHostGuard;
     }
 
     /**
@@ -103,6 +105,8 @@ private Session createSession(ConnectionRequest request) throws JSchException {
         // Create a new JSch instance per session to avoid shared state issues
         JSch jsch = new JSch();
 
+        sshHostGuard.assertAllowed(request.getSshHost());
+
         String sshHost = request.getSshHost();
         int sshPort = request.getSshPort() != null ? request.getSshPort() : 22;
         String sshUsername = request.getSshUsername();
@@ -234,6 +238,9 @@ public boolean testSshConnection(ConnectionRequest request) {
             return true; // SSH not required
         }
 
+        // Outside the try: a blocked host must surface its reason, not read as a failed login.
+        sshHostGuard.assertAllowed(request.getSshHost());
+
         Session session = null;
         try {
             log.info("Testing SSH connection to {}@{}:{}",

backend/src/test/java/com/dbaagent/service/SshHostGuardTest.java

@@ -0,0 +1,111 @@
+package com.dbaagent.service;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SshHostGuardTest {
+
+    private SshHostGuardProperties properties;
+    private SshHostGuard guard;
+
+    @BeforeEach
+    void setUp() {
+        properties = new SshHostGuardProperties();
+        // Ships disabled; these cases cover the behaviour once an operator turns it on.
+        properties.setEnabled(true);
+        guard = new SshHostGuard(properties);
+    }
+
+    @Test
+    void shipsDisabledByDefault() {
+        SshHostGuardProperties defaults = new SshHostGuardProperties();
+
+        assertFalse(defaults.isEnabled());
+        assertTrue(defaults.getAllowedHosts().isEmpty());
+        assertDoesNotThrow(() -> new SshHostGuard(defaults).assertAllowed("169.254.169.254"));
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {
+            "127.0.0.1",
+            "localhost",
+            "0.0.0.0",
+            "10.0.0.5",
+            "172.16.4.9",
+            "192.168.1.1",
+            "169.254.169.254",
+            "100.64.0.1",
+            "[::1]",
+            "[fd00::1]",
+            "[::ffff:169.254.169.254]"
+    })
+    void blocksRestrictedTargets(String host) {
+        assertThrows(IllegalArgumentException.class, () -> guard.assertAllowed(host));
+    }
+
+    @Test
+    void blockedMessageNamesTheHostAndTheEscapeHatch() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> guard.assertAllowed("169.254.169.254"));
+
+        assertTrue(e.getMessage().contains("169.254.169.254"), e.getMessage());
+        assertTrue(e.getMessage().contains("allowed-hosts"), e.getMessage());
+    }
+
+    @Test
+    void allowsPublicAddress() {
+        assertDoesNotThrow(() -> guard.assertAllowed("93.184.216.34"));
+    }
+
+    @Test
+    void rejectsBlankHost() {
+        assertThrows(IllegalArgumentException.class, () -> guard.assertAllowed("  "));
+        assertThrows(IllegalArgumentException.class, () -> guard.assertAllowed(null));
+    }
+
+    @Test
+    void rejectsUnresolvableHost() {
+        assertThrows(IllegalArgumentException.class,
+                () -> guard.assertAllowed("no-such-host.invalid"));
+    }
+
+    @Test
+    void allowlistExemptsExactHost() {
+        properties.setAllowedHosts(List.of("10.0.0.5"));
+
+        assertDoesNotThrow(() -> guard.assertAllowed("10.0.0.5"));
+        assertThrows(IllegalArgumentException.class, () -> guard.assertAllowed("10.0.0.6"));
+    }
+
+    @Test
+    void allowlistIsCaseInsensitiveAndTrimmed() {
+        properties.setAllowedHosts(List.of("  LocalHost  "));
+
+        assertDoesNotThrow(() -> guard.assertAllowed("localhost"));
+    }
+
+    @Test
+    void allowlistSupportsDomainSuffix() {
+        properties.setAllowedHosts(List.of(".corp.internal"));
+
+        assertDoesNotThrow(() -> guard.assertAllowed("bastion.corp.internal"));
+        assertThrows(IllegalArgumentException.class, () -> guard.assertAllowed("10.0.0.5"));
+    }
+
+    @Test
+    void disabledGuardPermitsEverything() {
+        properties.setEnabled(false);
+
+        assertDoesNotThrow(() -> guard.assertAllowed("169.254.169.254"));
+        assertDoesNotThrow(() -> guard.assertAllowed("no-such-host.invalid"));
+    }
+}

backend/src/test/java/com/dbaagent/service/SshTunnelServiceTest.java

@@ -26,7 +26,8 @@ class SshTunnelServiceTest {
 
     @BeforeEach
     void setUp() {
-        sshTunnelService = new SshTunnelService(providerRegistry);
+        sshTunnelService = new SshTunnelService(
+                providerRegistry, new SshHostGuard(new SshHostGuardProperties()));
     }
 
     @Test