tailsnitch

Tailsnitch

A security auditor for Tailscale configurations. Tailsnitch scans your tailnet for 57 misconfigurations, overly permissive access controls, and security best practice violations.

Quick Start

# 1. Set your Tailscale API credentials
export TS_API_KEY="tskey-api-..."

# 2. Run audit
tailsnitch

# 3. See only high-severity findings
tailsnitch --severity high

# 4. Fix some issues  ~interactively~ yolo mode
tailsnitch --fix

Installation

Download Pre-built Binary

Download the latest release from GitHub Releases.

macOS users: Remove quarantine attribute after download:

sudo xattr -rd com.apple.quarantine tailsnitch

Install via Go

go install github.com/Adversis/tailsnitch@latest

Build from Source

git clone https://github.com/Adversis/tailsnitch.git
cd tailsnitch
go build -o tailsnitch .

Authentication

Tailsnitch supports two authentication methods. OAuth is preferred when both are configured.

Option 1: OAuth Client (Recommended)

OAuth clients provide scoped, auditable access that doesn't expire when employees leave.

export TS_OAUTH_CLIENT_ID="..."
export TS_OAUTH_CLIENT_SECRET="tskey-client-..."

Create an OAuth client at: https://login.tailscale.com/admin/settings/oauth

Required scopes for read-only audit:

all:read covers everything. Granting scopes individually:

Any scope you leave out only affects the checks that need it: those checks report that they could not read the setting rather than passing.

AUTH-005 and AUTH-006 read the tailnet's federated identities, which the admin console calls trust credentials. They arrive from the same keys listing as auth keys, so auth_keys:read is expected to cover them. That has not been confirmed against a live tailnet. If the keys listing cannot be read, both checks report not evaluated rather than passing. Whether a missing scope returns an error or instead returns the listing with the identities filtered out is unconfirmed; if it filters silently, AUTH-005 would report that no trust credentials exist and AUTH-006 would find nothing to check.

Additional scopes for fix mode:

• devices:core - Delete devices, modify tags (requires tag selection)
• auth_keys - Delete auth keys

Tailnet Lock

DEV-010 and DEV-012 report on Tailnet Lock, which the Tailscale API does not expose as a tailnet setting. Devices locked out by it are visible through the API, but determining whether lock is enabled needs the local tailscale CLI, which reads the daemon on the machine running tailsnitch. When auditing another tailnet with --tailnet, treat that part of the result accordingly. Use --tailscale-path if the binary is in a non-standard location.

Option 2: API Key

API keys operate as the user who created them and inherit that user's permissions.

export TS_API_KEY="tskey-api-..."

Create an API key at: https://login.tailscale.com/admin/settings/keys

Usage Examples

Basic Audit

# Run full audit
tailsnitch

# Show passing checks too (verbose)
tailsnitch --verbose

# Output as JSON for processing
tailsnitch --json

# Audit a specific tailnet (when OAuth client has access to multiple)
tailsnitch --tailnet mycompany.com

Filter Results

# Only show critical and high severity issues
tailsnitch --severity high

# Filter by category
tailsnitch --category access    # ACL issues
tailsnitch --category auth      # Authentication & keys
tailsnitch --category device    # Device security
tailsnitch --category network   # Network exposure
tailsnitch --category ssh       # SSH rules
tailsnitch --category log       # Logging & admin

# Run specific checks only
tailsnitch --checks ACL-001,AUTH-001,DEV-010
tailsnitch --checks stale-devices,tailnet-lock-not-enabled

# List all available checks
tailsnitch --list-checks

Interactive Fix Mode

Fix mode allows you to remediate issues directly via the Tailscale API:

# Interactive fix mode
tailsnitch --fix

# Preview what would be fixed (dry run)
tailsnitch --fix --dry-run

# Auto-select safe fixes (still requires confirmation)
tailsnitch --fix --auto

# Disable audit logging of fix actions
tailsnitch --fix --no-audit-log

API-fixable items:

Fix mode also provides direct links to the admin console for issues that require manual intervention.

SOC 2 Evidence Export

Generate evidence reports for SOC 2 audits with Common Criteria (CC) control mappings:

# Export as JSON
tailsnitch --soc2 json > soc2-evidence.json

# Export as CSV (for spreadsheets)
tailsnitch --soc2 csv > soc2-evidence.csv

The SOC 2 report includes:

• Per-resource test results (each device, key, ACL rule tested individually)
• CC code mappings (CC6.1, CC6.2, CC6.3, CC6.6, CC7.1, CC7.2, etc.)
• Pass/Fail/N/A status for each control test
• Timestamp for audit trail

Example CSV output:

resource_type,resource_id,resource_name,check_id,check_title,cc_codes,status,details,tested_at
device,node123,prod-server,DEV-001,Tagged devices with key expiry disabled,CC6.1;CC6.3,PASS,Tags: [tag:server] key expiry enabled,2025-01-05T10:30:00Z
key,tskey-auth-xxx,tskey-auth-xxx,AUTH-001,Reusable auth keys exist,CC6.1;CC6.2;CC6.3,FAIL,Reusable key expires in 45 days,2025-01-05T10:30:00Z

Ignore Known Risks

Create a .tailsnitch-ignore file to suppress findings for known-accepted risks:

# .tailsnitch-ignore
# Ignore informational checks
ACL-008  # We intentionally don't use groups
ACL-009  # Legacy ACLs are fine for our use case

# Ignore specific medium checks with justification
DEV-006  # External devices are approved contractors
LOG-001  # Flow logs require Enterprise plan

# Ignore one item within a check, instead of muting the whole check
ACL-011:tag:monitoring  # broad by design; every other tag is still checked
AUTH-001:tskey-auth-xxxx  # rotates automatically via CI, tracked in TICKET-123

A line names either a whole check (ACL-011) or one item within it (CHECK-ID:item, split on the first colon - the item itself may contain colons). A per-item rule suppresses only that item: the check still runs and still reports everything else it finds. Suppressing every flagged item never turns a failing check into a passing one - the finding stays, downgraded to Informational, so a suppressed finding never reads as a satisfied control.

Ignore file locations (checked in order):

1. .tailsnitch-ignore in current directory
2. ~/.tailsnitch-ignore in home directory

Because the first location is the working directory, an ignore file can come from a repository rather than from you. Every run reports which file it used and how many findings and items it suppressed, and --json records this in the ignore_file and ignored fields (CHECK-ID for a whole check, CHECK-ID:item for one suppressed item). Use --no-ignore to skip the file.

# Use a specific ignore file
tailsnitch --ignore-file /path/to/ignore

# Disable ignore file processing entirely
tailsnitch --no-ignore

JSON Export and Processing

…

Command Reference

Security Checks

Tailsnitch performs 57 security checks across 7 categories. See docs/CHECKS.md for detailed documentation of each check.

Critical Severity

High Severity

Medium Severity

Informational

Checks for logging configuration, DNS settings, user roles, and manual verification items.

Severity that depends on the finding

Several checks rate what they find rather than carrying one fixed severity. Three are worth calling out here:

• ACL-011 reports every tag's reach at Inf