Tailsnitch: A Comprehensive Security Auditor for Tailscale Enterprises

# Tailsnitch: A Comprehensive Security Auditor for Tailscale Enterprises ## Overview Tailsnitch is a purpose‑built security auditor for Tailscale configurations. It performs an automated assessment of a tailnet—scanning for more than 50 potential vulnerabilities—including overly permissive access controls, insecure authentication keys, outdated device clients, and network exposure. The tool is designed to be run from a single command, to integrate into CI/CD pipelines, and to provide remediation hooks that interact directly with the Tailscale API. ## Quick Start Guide ```bash # 1. Set your Tailscale API credentials export TSKEY="tskey-api-..." # 2. Run a full audit tailsnitch # 3. Show only high‑severity findings tailsnitch --severity high # 4. Interactively fix issues tailsnitch --fix ``` ## Installation ### 1. Download a Pre‑built Binary The latest release is available on the project’s GitHub Releases page. macOS users should remove the quarantine flag after download: ```bash sudo xattr -rd com.apple.quarantine tailsnitch ``` ### 2. Install via Go ```bash go install github.com/Adversis/tailsnitch@latest ``` ### 3. Build from Source ```bash git clone https://github.com/Adversis/tailsnitch.git cd tailsnitch go build -o tailsnitch . ``` ## Authentication Methods Tailsnitch supports two mechanisms, with OAuth client preferred when available. ### OAuth Client (Recommended) * Store scoped credentials: ```bash export TS_OAUTH_CLIENT_ID="..." export TS_OAUTH_CLIENT_SECRET="tskey-client-..." ``` * Create the client in the Tailscale admin console under **Admin → Settings → OAuth**. * Minimum scopes for a read‑only audit are `all:read` or the individual scopes: - `policy_file:read` - `devices:core:read` - `dns:read` - `auth_keys:read` * Additional scopes for the `--fix` mode: - `devices:core` (for deletion or tag modification) - `auth_keys` (for key deletion) ### API Key * Set ```bash export TSKEY="tskey-api-..." ``` * Create under **Admin → Settings → Keys**. The key inherits the creator’s permissions. ## Core Features ### Full Audit The default call `tailsnitch` performs all 52 checks across 7 categories: Access Control, Authentication & Keys, Device Security, Network Exposure, SSH Rules, Logging & Admin, and DNS. Optionally, `--verbose` shows passing checks, while `--json` dumps the full report for downstream tooling. ### Filtering and Targeted Scans | Flag | Purpose | |------|---------| | `--severity` | Minimum severity threshold (`critical`, `high`, `medium`, `low`, `info`). | | `--category` | Narrow to a single category (`access`, `auth`, `device`, `network`, `ssh`, `log`, `dns`). | | `--checks` | Run comma‑separated list of check IDs or slugs. | | `--tailnet` | Explicitly audit a tailnet when the OAuth client has access to multiple. | ### Interactive Fix Mode The `--fix` flag enables an interactive prompt that offers safe remediations for API‑fixable items: | Check | Action | |-------|--------| | AUTH‑001, AUTH‑002, AUTH‑003 | Delete auth keys | | AUTH‑004 | Replace with an ephemerals key | | DEV‑002 | Remove tags from user devices | | DEV‑004 | Delete stale devices | | DEV‑005 | Authorise pending devices | Additional options: - `--dry-run`: Preview the changes. - `--auto`: Auto‑apply safe fixes (confirmation still required). - `--no-audit-log`: Suppress audit logging of fix actions. ### SOC 2 Evidence Export Generate structured evidence for SOC 2 audits that maps each check to Common Criteria (CC) control codes: ```bash tailsnitch --soc2 json > soc2-evidence.json ``` or ```bash tailsnitch --soc2 csv > soc2-evidence.csv ``` The export includes per‑resource results, CC code mappings, and timestamps to support audit trails. ### Suppressing Known Risks `tailsnitch` respects a `.tailsnitch‑ignore` file that can suppress specific checks with justification. Supported locations are the current directory and the user’s home (`~/.tailsnitch‑ignore`). A full example: ``` # .tailsnitch-ignore # Informational checks ACL‑008 # We intentionally don’t use groups ACL‑009 # Legacy ACLs are fine for our use case # Medium‑severity with justification DEV‑006 # External devices are approved contractors LOG‑001 # Flow logs require Enterprise plan ``` Use `--ignore-file` to point to a custom file or `--no-ignore` to bypass processing. ### JSON Export and Advanced Processing ```bash # Full report tailsnitch --json > audit.json # Extract failures as TSV jq '.suggestions | map(select(.pass==false)) | .[] | [.id,.title,.severity,.remediation] | @tsv' audit.json > findings.tsv ``` ### Command Reference A concise reference for all flags is included in the original documentation; key flags include `--severity`, `--category`, `--check`, `--fix`, `--auto`, `--dry-run`, `--soc2`, and `--tailscale-path` for local Tailnet‑Lock checks. ## Security Checks Landscape Tailsnitch implements 52 checks grouped into 7 categories. Highlights include: - **ACL‑001** (critical): Default "allow all" policy. - **AUTH‑001** (high): Reusable auth keys. - **DEV‑001** (high): Tagged devices lacking key expiry. - **NET‑001** (high): Funnel exposure. - **SSH‑002** (high): Root SSH without re‑authentication. - **DEV‑004** (medium): Stale devices. The detailed spec can be found in the project’s `CHECKS.md`. ## Sample Report ``` +===================================================================== | TAILSNITCH SECURITY AUDIT | | Tailnet: example.com | | Version: 1.0.0 (build: abc123) | +===================================================================== Using ignore file: .tailsnitch‑ignore (3 rules) === ACCESS CONTROLS =================================================== [CRITICAL] ACL‑001: Default 'allow all' policy active Your ACL policy omits the 'acls' field. Tailscale applies a default 'allow all' policy, granting all devices full access. Remediation: Define explicit ACL rules following the least privilege principle. Source: https://tailscale.com/kb/1192/acl-samples === AUTHENTICATION & KEYS ============================================= [HIGH] AUTH‑001: Reusable auth keys exist Found 2 reusable auth key(s). These can be reused to add multiple devices if compromised. Details: - Key tskey-auth-xxx (expires in 45 days) - Key tskey-auth-yyy (expires in 89 days) Remediation: Store reusable keys in a secrets manager. Prefer one‑off keys. Source: https://tailscale.com/kb/1085/auth-keys SUMMARY ===================================================================== Critical: 1 High: 3 Medium: 5 Low: 2 Info: 8 Total findings: 19 | Passed: 33 ``` ## CI/CD Integration Tailsnitch can be leveraged in automated pipelines to enforce security policies. A GitHub Actions example: ```yaml - name: Audit Tailscale Security env: TS_OAUTH_CLIENT_ID: ${{ secrets.TS_OAUTH_CLIENT_ID }} TS_OAUTH_CLIENT_SECRET: ${{ secrets.TS_OAUTH_CLIENT_SECRET }} run: | tailsnitch --json > audit.json if tailsnitch --severity high --json | jq -e '.summary.critical + .summary.high > 0'; then echo "Critical or high severity issues found!" tailsnitch --severity high exit 1 fi ``` ## Conclusion Tailsnitch brings disciplined, repeatable security auditing to any Tailscale deployment. Its concise CLI interface, support for OAuth‑scoped access, interactive remediation, and SOC‑2 evidence export make it a decisive addition to the security toolchain of modern DevOps and platform teams. --- ### References - Tailscale Security Hardening Guide - ACL Syntax Reference - Tailscale SSH - Audit Logging - Tailnet Lock ### License MIT