Skip to content
Proyectos

Adversis/tailsnitch has 1,142 GitHub stars and 28 forks. GitHot measured +2 stars in 24 hours, +3 in 7 days, and +6 in 15 days. Last checked 2026-11-22 11:49 UTC. Last push 2026-09-03.

Cómo se miden estas cifras

Crecimiento de estrellas medido

in 24h
+2
in 7 days
+3
in 15 days
+6
in 1 month
Recopilando historial

Cambios netos en períodos que se solapan, no totales diarios. Los datos no disponibles se dejan en blanco. Las estrellas indican interés, no calidad.

Acerca de

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

Seguridad

README.md

Original

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:

Scope Used for
policy_file:read Tailnet policy file — ACL-, NET-, SSH-*
devices:core:read Device list — DEV-, NET-, ACL-011
dns:read DNS configuration — DNS-001, DEV-007
auth_keys:read Machine auth keys — AUTH-*, ACL-011
feature_settings:read Tailnet settings — DEV-008, DEV-009, DEV-014
logs:network:read Network flow logging setting — LOG-001
networking_settings:read HTTPS certificate setting — NET-004
log_streaming:read Log stream destinations — LOG-002
webhooks:read Webhook endpoints — LOG-005, LOG-012
oauth_keys:read OAuth clients — LOG-006
users:read User roles and status — USER-001, LOG-006
account_settings:read Security contact — LOG-011
devices:posture_attributes:read Posture integrations — DEV-014

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:

Check Action
AUTH-001, AUTH-002, AUTH-003 Delete auth keys
DEV-002 Remove tags from user devices
DEV-004 Delete stale devices
DEV-005 Authorize pending devices

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

# Export full report
tailsnitch --json > audit.json

# Extract failed checks as TSV
tailsnitch --json | jq -r '
  .suggestions
  | map(select(.pass == false))
  | .[]
  | [.id, .title, .severity, .remediation]
  | @tsv
' > findings.tsv

# Summary by severity
tailsnitch --json | jq '
  .suggestions
  | map(select(.pass == false))
  | group_by(.severity)
  | map({severity: .[0].severity, count: length})
'

# List critical/high issues with admin links
tailsnitch --json | jq -r '
  .suggestions
  | map(select(.pass == false and (.severity == "CRITICAL" or .severity == "HIGH")))
  | .[]
  | "\(.id): \(.title)\n  Fix: \(.fix.admin_url // "manual")\n"
'

Command Reference

Flag Description
--json Output as JSON
--severity Filter by minimum severity: critical, high, medium, low, info
--category Filter by category: access, auth, network, ssh, log, device, dns
--checks Run specific checks (comma-separated IDs or slugs)
--list-checks List all available checks and exit
--tailnet Specify tailnet to audit (default: from API key)
--verbose Show passing checks too
--fix Enable interactive fix mode
--auto Auto-select safe fixes (requires --fix)
--dry-run Preview fix actions without executing (requires --fix)
--no-audit-log Disable audit logging of fix actions
--soc2 Export SOC 2 evidence: json or csv
--tailscale-path Path to tailscale CLI (for Tailnet Lock checks)
--timeout Overall time budget for the audit (default 2m)
--ignore-file Path to ignore file
--no-ignore Disable ignore file processing
--version Show version information

Security Checks

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

Critical Severity

ID Check Risk
ACL-001 Default 'allow all' policy All devices have unrestricted access
ACL-002 SSH autogroup:nonroot misconfiguration SSH as any non-root user
ACL-006 tagOwners too broad Privilege escalation via tags
ACL-007 autogroup:danger-all usage Access granted to external users

High Severity

ID Check Risk
ACL-011 Tag reach crosses a trust boundary A stolen reusable key mints a tag that reaches everything
AUTH-001 Reusable auth keys Unlimited device additions if stolen
AUTH-002 Long expiry auth keys Extended exposure window
AUTH-003 Pre-authorized keys Bypass device approval
AUTH-006 Federated identity subject too broad Any principal the issuer vouches for can mint the tag
DEV-001 Tagged devices without key expiry Indefinite access
DEV-002 User devices tagged Persist after user removal
DEV-010 Tailnet Lock disabled No protection against stolen keys
DEV-012 Pending Tailnet Lock signatures Unsigned nodes need review
NET-001 Funnel exposure Public internet access
NET-003 Subnet router trust boundary Unencrypted traffic on local network
SSH-002 Root SSH without check mode No re-authentication required

Medium Severity

ID Check Risk
ACL-004 autogroup:member usage External users included
ACL-005 AutoApprovers configured Bypass route approval
AUTH-004 Non-ephemeral CI/CD keys Stale devices accumulate
AUTH-005 Workload identity federation not in use Long-lived keys stay stealable
DEV-003 Outdated clients Potential vulnerabilities
DEV-004 Stale devices Unused attack surface
DEV-005 Unauthorized devices Pending approval queue
DEV-007 Sensitive machine names CT log exposure
DEV-009 Device approval config May not be enabled
NET-004 HTTPS CT log exposure Machine names public
NET-005 Exit node traffic visibility Operator sees all traffic
NET-006 Serve exposure Local services on tailnet
SSH-003 Recorder UI exposure Sessions visible to network

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 Informational. It fails only when a tag an auth key can assign reaches a wildcard destination, a routed subnet or exit-node egress: High if a reusable key assigns that tag, Medium if only a one-off key does. A device count never sets severity.
  • AUTH-005 reports Medium when the tailnet has no trust credentials at all, and Low when trust credentials exist but a reusable key still mints tags none of them cover.
  • AUTH-006 reports High for a subject that is nothing but a wildcard, and Low for a narrower wildcard or a missing audience.

Output Example

+=====================================================================+
|                    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 least privilege principle.

  Source: https://tailscale.com/docs/reference/examples/acls
----------------------------------------------------------------------

=== 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/docs/features/access-control/auth-keys
----------------------------------------------------------------------

SUMMARY
======================================================================
  Critical: 1  High: 3  Medium: 5  Low: 2  Info: 8
  Total findings: 19  |  Passed: 33

Tailnet Lock Checks

Tailnet Lock checks (DEV-010, DEV-012) require the local tailscale CLI and run against the local machine's daemon. When auditing a remote tailnet via --tailnet, these checks reflect local status, not the audited tailnet.

# Specify custom tailscale binary path if needed
tailsnitch --tailscale-path /opt/tailscale/bin/tailscale

CI/CD Integration

Run Tailsnitch in CI/CD pipelines to catch security regressions:

# GitHub Actions example
- 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
    # Fail if critical or high severity issues exist
    if tailsnitch --severity high --json | jq -e '.summary.critical + .summary.high > 0' > /dev/null; then
      echo "Critical or high severity issues found!"
      tailsnitch --severity high
      exit 1
    fi

References

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Explorar proyectos relacionados

Cargando…