Configuration audit logging

Configuration audit logs let you identify who did what, and when, in your tailnet. Configuration audit logs record actions that modify a tailnet’s configuration, including the type of action, the actor, the target resource, and the time.

You can export logs for long-term storage and/or for security analysis, threat detection, and incident investigation. You can also stream logs to a security information and event management (SIEM) system.

For changes to the tailnet policy file, the log includes a full diff of the previous and new files.

All users who have access to the admin console can view configuration audit logs in the Logs page of the admin console, and can filter these logs to find specific events.

Configuration audit logs are enabled by default for all tailnets, and are available for the most recent 90 days.

Log structure

Logs include several components:

• Timestamp: When the event happened. This is displayed in your browser’s local time.
• Action: What action happened. For example, approve a device, or modify the tailnet policy file.
• Actor: Which user or process completed the action. If the action is made by a user, this value is the user’s name. The user's email or GitHub username, as well as their name, is available in the events returned by the API. If the action is made by the Tailscale control plane, this value is the Tailscale service. For a list of actions made by the Tailscale control plane, see Service events.
• Target: Which resource the action applied to. For example, for an action modifying a user’s role, the target is the user. For an action approving a device, the target is the device. Where the action is a tailnet-wide configuration, the target is the tailnet.
• Diff: The old and the new values provided, if relevant. For example, if you renamed a node’s machine name, or updated a list of tags, you will see both the old and new values. For ACL changes, you’ll see a full diff of the previous and updated versions, including non-substantive changes like comments. For re-authenticating a node, you’ll see the old node key expiry and the new key expiry.

Enabling configuration audit logging

Configuration audit logs are always enabled for all tailnets and cannot be disabled.

Configuration audit logs are a subset of the logs that Tailscale uses to provide the service, in line with our privacy policy.

Accessing configuration audit logs

Configuration audit logs can be accessed in the Logs page of admin console or via API.

Viewing configuration audit logs in the admin console

All users who have access to the admin console can view configuration audit logs in the Logs page of the admin console, and can filter these logs to find specific events.

Logs are shown in the order that events occurred, starting with the most recent.

Filtering configuration audit logs

Events in the Logs page of the admin console can be filtered to more easily find events meeting certain criteria.

Filters can be used on time, action, and actor. Multiple filters can be applied simultaneously to find events meeting all the filtering criteria.

Time

Use the Timeframe filter to show only logs between two specified dates.

Type of action

Use the Action filter to show only logs that match the selected actions. For example, you can see all events that include an update to your tailnet policy file.

Actor

Use the Actor filter to show only logs where actions were taken by the selected users.

Accessing configuration audit logs via API

You can export configuration audit logs from the Tailscale API. You need an API access token with the logs:configuration:read scope to access configuration audit logs.

The response to the logs API call is in the form of the TailnetLogsResponse struct:

type TailnetLogsResponse struct {
	Version string        `json:"version"`
	Tailnet dbx.TailnetID `json:"tailnetId"`

	Logs []Log `json:"logs"` // Ordered chronologically
}

You can use the following query parameters with the API:

• start: Required. Start of the timeframe, in RFC3339 timestamp format, for the logs to retrieve. For example: 2022-07-20T00:00:00Z.
• end: Required. End of the timeframe, in RFC3339 timestamp format, for the logs to retrieve. For example, 2022-07-21T00:00:00Z.

start and end times are inclusive within nanosecond resolution.

This example assumes you have set up the following variables to use for your API call:

• $ACCESS_TOKEN: An API access token to use when calling the Tailscale API. You can create an API access token in the Keys page of the admin console.
• $TAILNET_ID: The organization name for the tailnet whose logs are being retrieved. You can view your organization name in the General settings page of the admin console.
• $START: The start of the timeframe for the logs to retrieve.
• $END: The end of the timeframe for the logs to retrieve.

export ACCESS_TOKEN=tskey-api-k123456CNTRL-0123456789abcdef
export TAILNET_ID=example.com
export START=2022-07-20T00:00:00Z
export END=2022-07-21T00:00:00Z

curl -u  $ACCESS_TOKEN:  -X GET \
  "https://api.tailscale.com/api/v2/tailnet/{$TAILNET_ID}/logging/configuration?start={$START}&end={$END}"

Optionally, use json_pp to prettify the JSON output:

curl -u  $ACCESS_TOKEN: -X GET \
  "https://api.tailscale.com/api/v2/tailnet/{$TAILNET_ID}/logging/configuration?start={$START}&end={$END}" \
  | json_pp

The output will look like:

{
	"logs": [
		{
			"action": "UPDATE",
			"actor": {
				"displayName": "Alice Architect",
				"id": "123456CNTRL",
				"loginName": "alice@example.com",
				"type": "USER"
			},
			"deferredAt": "0001-01-01T00:00:00Z",
			"eventGroupID": "12345",
			"eventTime": "2022-07-20T20:13:30.136022207Z",
			"new": "2023-01-14T20:13:30.134350003Z",
			"old": "0001-01-01T00:00:00Z",
			"origin": "NODE",
			"target": {
				"id": "654321CNTRL",
				"name": "node1.yak-bebop.ts.net",
				"property": "KEY_EXPIRY_TIME",
				"type": "NODE"
			},
			"type": "CONFIG"
		},
		{
			"action": "CREATE",
			"actor": {
				"displayName": "Alice Architect",
				"id": "123456CNTRL",
				"loginName": "alice@example.com",
				"type": "USER"
			},
			"deferredAt": "0001-01-01T00:00:00Z",
			"eventGroupID": "23456",
			"eventTime": "2022-07-20T18:40:58.838529518Z",
			"new": {
				"capabilities": ["CONTROL_API_SCOPE_ALL_READ", "CONTROL_API_SCOPE_ALL"],
				"expires": "2022-10-18 18:40:58.653877012 +0000 UTC"
			},
			"origin": "ADMIN_UI",
			"target": {
				"id": "789123CNTRL",
				"name": "Control API key",
				"type": "API_KEY"
			},
			"type": "CONFIG"
		},
		{
			"action": "UPDATE",
			"actor": {
				"displayName": "Bob Builder",
				"id": "987654CNTRL",
				"loginName": "bob@example.com",
				"type": "USER"
			},
			"deferredAt": "0001-01-01T00:00:00Z",
			"eventGroupID": "34567",
			"eventTime": "2022-07-20T22:35:19.590021877Z",
			"new": ["...", "...", "10.0.0.0/24", "10.0.1.0/24"],
			"old": ["...", "..."],
			"origin": "ADMIN_UI",
			"target": {
				"id": "876543CNTRL",
				"name": "bob-workstation.yak-bebop.ts.net",
				"property": "ALLOWED_IPS",
				"type": "NODE"
			},
			"type": "CONFIG"
		}
	],
	"tailnetId": "example.com",
	"version": "1.1"
}

Currently, there is no pagination support and no maximum page size for the API. All events in the specified timeframe are returned.

When multiple events occur for a single operation, the actions have the same value for eventGroupID.

Reverting ACLs from audit logs

You need to be an Owner, Admin, or IT admin of a tailnet in order to revert a tailnet policy file from audit logs.

You can revert your tailnet policy file from a previous date and time.

1. Open the Configuration logs page of the admin console.

2. Locate and expand the log entry containing the policy file change you want to revert to, then select Revert to previous version. In the confirmation dialog, select Revert.

   

3. Open the Access controls page of the admin console and verify the policy file was reverted with the expected changes.

Events

Configuration audit logs include write actions that change the configuration of a tailnet, including changes that a user can make in the admin console or via API.

Any successfully completed event will create a corresponding log entry.

Events included in configuration audit logs are:

Note that failed login attempts are not included in Tailscale events—these should be seen in your identity provider logs, not Tailscale logs.

Multiple events for a single operation

Multiple events that occur as part of the same operation are logged individually. For example, when a user is deleted, there are log entries for deleting each of their nodes and each of their API access tokens, as well as deleting the user themselves. When a node is added to your tailnet, there are log entries for updating the name for a node, creating a node, updating the key expiry time for a node, logging into a node, and if applicable, approving the node.

Events for shared nodes

When using shared nodes, some events are logged in both the sharer and sharee tailnets. Events related to invites are only logged in the sharer tailnet, and events related to the shared node are logged in both the sharer and sharee tailnets.

Service events

The log includes service events, which are actions performed by the Tailscale service, not performed by users directly. Service events include:

Events not included

Changes to a tailnet that were initiated by a request to Tailscale’s support team are currently not included. This includes:

• Update identity provider
• Complete identity provider configuration for Okta or OneLogin
• Update organization name
• Update custom HTTPS domain
• Delete tailnet
• Allowlist tailnet for alpha feature

Changes that would have been included if performed by a user, but were instead initiated by a Support request are also not included:

• Update name for tailnet
• Update role for user
• Delete user
• Create billing subscription for tailnet
• Update billing subscription for tailnet
• Cancel billing subscription for tailnet
• Update billing address for tailnet
• Update billing email for tailnet
• Update billing payment information for tailnet
• Update key expiry time for node
• Enable device approval for tailnet
• Disable device approval for tailnet

Configuration audit logs streaming

Log streaming lets you stream network flow logs into a security information and event management (SIEM) system. For more information, see Log streaming.

Limitations

• Configuration audit logs only include actions that modify a tailnet’s configurations. Read-only actions, such as a user viewing the admin console, are not included.
• Changes to a tailnet that were initiated by Tailscale’s support team are not currently included.
• Configuration audit logs only include changes to configuration of a tailnet. Information about connections within a tailnet (data plane audit logs), such as network flow logs, are not included in configuration logs. You can use Network flow logs to log information about connections with a tailnet.
• Configuration audit logs are available as part of the admin console, exportable via API, and as a streaming source for SIEM systems.
• There is currently no guarantee for a maximum delay between an event taking place and its inclusion in the audit logs. In practice, this occurs within seconds.
• The period of time that configuration logs are stored cannot be configured. Configuration logs are stored for 90 days.
• Devices with the same node key will appear in logs as the same node target.
• When a user is suspended, the suspension of the user's nodes, API access tokens, and auth keys are not logged.
• When a user is deleted, the deletion of the user's API access tokens and auth keys are not logged.