Tailscale Funnel as a new Service Mode tunnel option by mnaqvi-ks · Pull Request #2378 · Keeper-Security/Commander

mnaqvi-ks · 2026-09-18T10:13:03Z

Adds Tailscale Funnel as a new tunnel option for Commander Service Mode, alongside the existing Ngrok and Cloudflare integrations. Users can now expose the Service Mode REST API over a public HTTPS URL using their own Tailscale account, with no changes to how Ngrok/Cloudflare already work.

# Plain personal auth key
keeper service-create -p 8090 -ts '<tailscale-auth-key>' -rm foreground -q y -f yaml -c "ls"

# OAuth-issued auth key (needs the ACL tag it's scoped to)
keeper service-create -p 8090 -ts '<oauth-client-secret>' -tst 'tag:commander-service' -rm foreground -q y -f yaml -c "ls"

Features

New tunnel provider — -ts, --tailscale <auth-key> / -tst, --tailscale_advertise_tags <tags>, following the same single-flag convention as -ng/-cf. Mutually exclusive with Ngrok/Cloudflare.
CLI detection & auto-install — detects a missing Tailscale CLI and, with explicit user confirmation, installs it automatically (Homebrew on macOS, official script on Linux, MSI with UAC elevation on Windows). Falls back to manual guidance if declined or if it fails.
Daemon detection & auto-start — same consent-gated flow if tailscaled isn't running.
Authentication — supports both plain personal auth keys and OAuth-client-issued keys. Used only for tailscale up; never touches the Service Mode API Key, which continues to gate every API request unchanged.
Full Funnel lifecycle — start, live status, and reset wired into service-create/service-start/service-status/service-stop. Startup failures roll back cleanly (including already-started Ngrok/Cloudflare processes).
Public URL retrieval — real HTTPS URL pulled from the node's Tailscale hostname; printed on create, persisted to config, reported via service-status, and included in Docker vault-record metadata (-ur).
Security — auth key passed via a short-lived, owner-only temp file (--auth-key=file:...) instead of a raw CLI argument, avoiding exposure via ps to other local users. Never logged.

Design notes

service-stop only resets the Funnel exposure — it doesn't log the machine out of Tailscale or stop the daemon, since tailscaled is system-wide and may be used for other things on the same machine.
CLI flag naming (-ts <key> as a single flag) intentionally matches the existing -ng/-cf convention rather than a separate enable+key pair.

Files changed

File	Purpose
`keepercommander/service/config/tailscale_config.py` (new)	Orchestrates CLI/daemon checks, authentication, Funnel start, and URL retrieval — the Tailscale equivalent of `ngrok_config.py`/`cloudflare_config.py`
`keepercommander/service/util/tunneling.py`	Adds all low-level `tailscale` CLI wrapper functions (install, daemon start, auth, Funnel start/stop/status, URL lookup)
`keepercommander/service/core/service_manager.py`	Wires Tailscale into `start_service`/`stop_service`/`get_status`, including rollback-on-failure and interrupt handling
`keepercommander/service/core/process_info.py`	Adds `tailscale_enabled`/`tailscale_port` lifecycle tracking (no PID — Tailscale has no Commander-owned subprocess)
`keepercommander/service/core/globals.py`	Transient, same-process global for deferring vault-metadata write-back until the real Funnel URL is known
`keepercommander/service/commands/create_service.py`	Adds `-ts`/`-tst` CLI flags and config schema fields
`keepercommander/service/commands/service_config_handlers.py`	Interactive and streamlined config prompts/assembly for Tailscale, extending the existing mutual-exclusion chain
`keepercommander/service/commands/integrations/vault_metadata.py`	Extracts the shared `get_service_url()` helper; fixes Docker metadata write-back timing so it waits for the real URL
`keepercommander/service/config/config_validation.py`	Adds `validate_tailscale_auth_key`
`keepercommander/service/config/models.py` / `service_config.py`	Adds `tailscale`, `tailscale_auth_key`, `tailscale_advertise_tags`, `tailscale_public_url` config fields, defaults, and backward-compat migration
`keepercommander/resources/service_config.ini`	Adds interactive prompt text for Tailscale
`keepercommander/service/README.md`	Documents the new flags, examples, and the `--force-reauth`/single-use-key note
`unit-tests/service/test_create_service.py`	Tests for the new CLI flag behavior, mutual exclusion, and streamlined config assembly

Compatibility

No changes to ngrok_config.py or cloudflare_config.py. All changes to shared files are additive, confirmed via diff review. Full existing test suite (279 tests) passes unchanged.

- Introduced Tailscale configuration and management in the service. - Added functions for installing, starting, and managing Tailscale daemons and funnels. - Enhanced ProcessInfo to track Tailscale status and ports. - Updated ServiceManager to handle Tailscale alongside existing tunneling options (ngrok, Cloudflare). - Implemented validation for Tailscale configuration parameters. - Created a new TailscaleConfigurator class for managing Tailscale setup and validation. - Added logging for Tailscale subprocess activities. - Updated unit tests to cover new Tailscale functionality.

…ller

…mmediately

…UAC prompt

- Introduced `tailscale_advertise_tags` to ServiceConfig and related classes. - Updated ServiceConfigHandler to handle new argument for Tailscale. - Modified TailscaleConfigurator to utilize advertise tags during authentication. - Adjusted validation logic to check for presence of Tailscale auth key and tags. - Enhanced installation and daemon management functions to ensure proper handling of Tailscale. - Updated unit tests to cover new `tailscale_advertise_tags` parameter.

…2365) (#2379) * Fix Gateway Name not displayed in pam rotation info output * Add UID type normalization and graceful error handling to gateway name resolution * Improve gateway name resolution: add UID validation and specific exception logging * Prevent None == None false positive by explicitly checking target_uid before gateway lookup

#2372) * Block Service Mode from ever accessing its own config records * Fix copilot review comments * Fix claude review comments * Fix review comments

…ess (#2383) (#2385) * Protect Integration config records from Service Mode API access * Add terraform backward compatability and test cases * Fix review comments * Fix failing test case in windows * Restrict folder access via Service Mode for all *-setup commands * Prevent config and service config json file attachments * Fix claude review comments

- Introduced Tailscale configuration and management in the service. - Added functions for installing, starting, and managing Tailscale daemons and funnels. - Enhanced ProcessInfo to track Tailscale status and ports. - Updated ServiceManager to handle Tailscale alongside existing tunneling options (ngrok, Cloudflare). - Implemented validation for Tailscale configuration parameters. - Created a new TailscaleConfigurator class for managing Tailscale setup and validation. - Added logging for Tailscale subprocess activities. - Updated unit tests to cover new Tailscale functionality.

…ller

…mmediately

…UAC prompt

- Introduced `tailscale_advertise_tags` to ServiceConfig and related classes. - Updated ServiceConfigHandler to handle new argument for Tailscale. - Modified TailscaleConfigurator to utilize advertise tags during authentication. - Adjusted validation logic to check for presence of Tailscale auth key and tags. - Enhanced installation and daemon management functions to ensure proper handling of Tailscale. - Updated unit tests to cover new `tailscale_advertise_tags` parameter.

…ithub.com/Keeper-Security/Commander into feature/tailscale-funnel-service-mode-int

pkamble-ks · 2026-09-22T10:55:06Z


                except Exception as e:
                    logger.error(f"Failed to start service subprocess: {e}")
                    raise


Tailscale Funnel is started before the Commander service subprocess is successfully created. If spawn_detached_process() or ProcessInfo.save() fails here, the exception path does not stop the Tailscale Funnel that was already configured at lines 118-120. This can leave the Funnel publicly exposed while the Commander service is not running. Can we add Tailscale cleanup to this rollback path?

fixed, the outer exception handler now stops the Funnel if it was already up before the subprocess/Flask app failed to start.

pkamble-ks · 2026-09-22T10:59:53Z

            except psutil.NoSuchProcess:
                ProcessInfo.clear()
                pass


When the Commander process is no longer running, this clears ProcessInfo but leaves the Tailscale Funnel configuration active. Since Funnel is managed by tailscaled and not tied to the Commander process lifecycle, an unexpected Commander crash/SIGKILL can leave the public Funnel endpoint enabled. Should we reconcile/disable the Commander-managed Funnel when detecting that the service process is gone?

Fixed — get_status() now stops the Funnel too when it detects the process is gone, not just on an explicit service-stop

pkamble-ks · 2026-09-22T11:02:42Z

+# Tailscale Funnel only accepts one of these as the external-facing port;
+# the local target port (the Commander service port) is unrestricted and
+# separate. 443 is the default so the public URL needs no port suffix.
+TAILSCALE_FUNNEL_ALLOWED_PORTS = (443, 8443, 10000)


TAILSCALE_FUNNEL_ALLOWED_PORTS defines the supported external Funnel ports, but start_tailscale_funnel() doesn't validate funnel_port against it. Should we validate the port here before invoking the CLI, or remove the unused constant?

Added validation using the existing constant instead of removing it. The parameter is retained for future extensibility and keeps the signature consistent with get_tailscale_funnel_url and stop_tailscale_funnel, so validating it now prevents invalid values from reaching the Tailscale CLI and failing there.

…status checks

… in configuration

mbachhav-ks · 2026-09-24T10:39:54Z

Do not commit log file and log folder

Sorry for that
fixed

mbachhav-ks · 2026-09-24T10:44:03Z

+
+        guidance = guidance_fn()
+        logger.error(guidance)
+        print(guidance)


Can you explain why guidance is printed?

This flow handles two checks: the Tailscale CLI being missing and the daemon not running. In either case, we show the manual fix before offering auto-fix, so the user always knows what to do if they decline or auto-fix fails
Guidance here printed for the manual fix

mnaqvi-ks added 6 commits September 9, 2026 19:53

feat: Update Windows Tailscale installation to use official MSI insta…

b461f77

…ller

feat: Enhance Windows Tailscale installation to update process PATH i…

c7eea46

…mmediately

feat: Implement elevated installation for Tailscale on Windows using …

9a07448

…UAC prompt

feat: Add Tailscale Funnel support to service configuration and commands

26f6b45

mnaqvi-ks requested review from amuley-ks, bpadhan-ks, mbachhav-ks and pkamble-ks September 18, 2026 10:13

sshrushanth-ks and others added 13 commits September 18, 2026 08:05

handle root node visibility flag correctly

98d24ef

KC-1457: Block Service Mode from ever accessing its own config records (

20b43e9

#2372) * Block Service Mode from ever accessing its own config records * Fix copilot review comments * Fix claude review comments * Fix review comments

Fix PAM tunnel diagnose proxy support

3ebacec

feat: Update Windows Tailscale installation to use official MSI insta…

4d0fda8

…ller

feat: Enhance Windows Tailscale installation to update process PATH i…

11569cb

…mmediately

feat: Implement elevated installation for Tailscale on Windows using …

5cfa878

…UAC prompt

feat: Add Tailscale Funnel support to service configuration and commands

d5768ee

chore: Remove obsolete Tailscale subprocess log file

b24df09

Merge branch 'feature/tailscale-funnel-service-mode-int' of https://g…

b7fbe33

…ithub.com/Keeper-Security/Commander into feature/tailscale-funnel-service-mode-int

pkamble-ks reviewed Sep 22, 2026

View reviewed changes

mnaqvi-ks added 2 commits September 23, 2026 12:12

feat: Validate Tailscale Funnel port in start_tailscale_funnel function

161bd09

feat: Enhance Tailscale Funnel management during service startup and …

f2c5d28

…status checks

mnaqvi-ks requested a review from pkamble-ks September 23, 2026 06:55

feat: Implement Tailscale Funnel activation verification and rollback…

1a2da6f

… in configuration

mbachhav-ks requested changes Sep 24, 2026

View reviewed changes

chore: Remove obsolete Tailscale subprocess log file

e774845

mnaqvi-ks requested a review from mbachhav-ks September 24, 2026 11:08

Navigation Menu

Tailscale Funnel as a new Service Mode tunnel option - #2378

Tailscale Funnel as a new Service Mode tunnel option#2378
mnaqvi-ks wants to merge 23 commits into
feature/tailscale-funnel-service-modefrom
feature/tailscale-funnel-service-mode-int

mnaqvi-ks commented Sep 18, 2026

Uh oh!

pkamble-ks Sep 22, 2026

Uh oh!

mnaqvi-ks Sep 23, 2026

Uh oh!

pkamble-ks Sep 22, 2026

Uh oh!

mnaqvi-ks Sep 23, 2026

Uh oh!

pkamble-ks Sep 22, 2026

Uh oh!

mnaqvi-ks Sep 23, 2026

Uh oh!

mbachhav-ks Sep 24, 2026

Uh oh!

mnaqvi-ks Sep 24, 2026

Uh oh!

mbachhav-ks Sep 24, 2026

Uh oh!

mnaqvi-ks Sep 24, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

mnaqvi-ks commented Sep 18, 2026

Features

Design notes

Files changed

Compatibility

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants