tacl

README

Tailscale ACL 💂

tacl (pronounced as Tackle) provides a library to parse Tailscale acl.

tacl supports converting acl rules to tailcfg.FilterRule, ssh rules to tailcfg.SSHPolicy.

Documentation

Overview

Package tacl (pronounced as tackle) implements Tailscale ACL parsing and generation of tailcfg.FilterRule from ACL

Index

• Constants
• type ACL
  • func Parse(buf []byte) (_ *ACL, err error)
  • func (acl *ACL) BuildFilter(m Machine, peers []Machine) []tailcfg.FilterRule
  • func (acl *ACL) BuildSSHPolicy(m Machine, peers []Machine, fn ActionBuilderFn) *tailcfg.SSHPolicy
• type AclAutoApprovers
• type AclEntry
• type AclGrant
• type AclSsh
• type ActionBuilderFn
• type Alias
  • func (alias Alias) ApplyDst(acl *ACL, m Machine) []string
  • func (alias Alias) ApplySrc(acl *ACL, m Machine, user User) []string
  • func (alias Alias) IsAutogroup() bool
  • func (alias Alias) IsGroup() bool
  • func (alias Alias) IsTag() bool
  • func (alias Alias) IsUser() bool
  • func (alias Alias) IsWildcard() bool
  • func (alias Alias) String() string
• type Machine
• type PortRange
  • func (pr PortRange) Parse() ([]tailcfg.PortRange, error)
  • func (pr PortRange) String() string
• type Protocol
  • func (p Protocol) Value() []int
• type SshRuleConfig
• type User

Constants

const (
	AutoGroupSelf      = "autogroup:self"
	AutoGroupMember    = "autogroup:member"
	AutoGroupMembers   = "autogroup:members"
	AutoGroupTagged    = "autogroup:tagged"
	AutoGroupInternet  = "autogroup:internet"
	AutoGroupDangerAll = "autogroup:danger-all"
)

Types

type ACL

type ACL struct {
	Entries       []AclEntry          `json:"acls,omitempty" hujson:"ACLs,omitempty"`
	Grants        []AclGrant          `json:"grants,omitempty" hujson:"Grants,omitempty"`
	SSH           []AclSsh            `json:"ssh,omitempty" hujson:"SSH,omitempty"`
	Groups        map[string][]string `json:"groups,omitempty" hujson:"Groups,omitempty"`
	Hosts         map[string]string   `json:"hosts,omitempty" hujson:"Hosts,omitempty"`
	TagOwners     map[string][]string `json:"tagOwners,omitempty" hujson:"TagOwners,omitempty"`
	AutoApprovers AclAutoApprovers    `json:"autoApprovers,omitempty" hujson:"AutoApprovers,omitempty"`
}

ACL is the central access-control component of Tailscale used to manage access within your Tailnet.

ACLs are deny-by-default, directional, locally enforced, and don't affect local network traffic.

see: https://tailscale.com/kb/1018/acls

func Parse

func Parse(buf []byte) (_ *ACL, err error)

Parse parses ACL from the contents of the given reader

func (*ACL) BuildFilter

func (acl *ACL) BuildFilter(m Machine, peers []Machine) []tailcfg.FilterRule

BuildFilter builds the tailcfg.FilterRule set for the given node, taking into account the given peers.

func (*ACL) BuildSSHPolicy

func (acl *ACL) BuildSSHPolicy(m Machine, peers []Machine, fn ActionBuilderFn) *tailcfg.SSHPolicy

type AclAutoApprovers

type AclAutoApprovers struct {
	Routes   map[string][]string `json:"routes,omitempty" hujson:"Routes,omitempty"`
	ExitNode []string            `json:"exitNode,omitempty" hujson:"ExitNode,omitempty"`
}

AclAutoApprovers defines the list of users who can perform specific actions without further approval from the admin console.

type AclEntry

type AclEntry struct {
	// Action specified by this entry.
	// Since access rules are deny-by-default, the only possible value is 'accept'.
	Action string `json:"action,omitempty" hujson:"Action,omitempty"`

	// Protocol field is an optional field you can use to specify the protocol to which the rule applies.
	// You can specify proto as an IANA IP protocol number 1-255 (for example, "16") or one of the supported named aliases.
	Protocol Protocol `json:"proto,omitempty" hujson:"Proto,omitempty"`

	// Source field specifies a list of sources to which the rule applies.
	Source []Alias `json:"src,omitempty" hujson:"Src,omitempty"`

	// Destination field specifies a list of destinations to which the rule applies.
	Destination []Alias `json:"dst,omitempty" hujson:"Dst,omitempty"`
}

type AclGrant

type AclGrant struct {
	// Source field specifies a list of sources to which the rule applies.
	Source []Alias `json:"src,omitempty" hujson:"Src,omitempty"`

	// Destination field specifies a list of destinations to which the rule applies.
	Destination []Alias `json:"dst,omitempty" hujson:"Dst,omitempty"`

	// IP field is an array of strings that grant network layer capabilities.
	// At-least one of IP or App must be specified.
	IP []tailcfg.ProtoPortRange `json:"ip,omitempty" hujson:"Ip,omitempty"`

	// App field is an optional field that maps strings to arrays of objects that define the application layer capabilities to grant.
	// At-least one of IP or App must be specified.
	App tailcfg.PeerCapMap `json:"app,omitempty" hujson:"App,omitempty"`
}

type AclSsh

type AclSsh struct {
	// Action specifies whether to accept the connection or to perform additional checks on it.
	Action string `json:"action,omitempty" hujson:"Action,omitempty"`

	// Source specifies the source (where a connection originates from).
	// You can only define an access rule's destination (dst) as yourself, a group, a tag, or an autogroup.
	// You cannot use *, other users, IP addresses, or hostnames.
	Source []Alias `json:"src,omitempty" hujson:"Src,omitempty"`

	// Destination specifies the destination (where the connection goes).
	// The destination can be a user, tag, or autogroup.
	// Unlike ACLs, you cannot specify a port because only port 22 is allowed.
	// You cannot * as the destination.
	Destination []Alias `json:"dst,omitempty" hujson:"Dst,omitempty"`

	// Users specifies the set of allowed usernames on the host.
	// see: https://tailscale.com/kb/1337/acl-syntax#users for list of valid values
	Users []string `json:"users,omitempty" hujson:"Users,omitempty"`

	// When action is check, CheckPeriod specifies the time period for which to allow a connection before requiring a check.
	CheckPeriod string `json:"checkPeriod,omitempty" hujson:"CheckPeriod,omitempty"`

	// AcceptEnv specifies the set of allowlisted environment variable names that clients can send to the host (optional)
	AcceptEnv []string `json:"acceptEnv,omitempty" hujson:"AcceptEnv,omitempty"`
}

type ActionBuilderFn

type ActionBuilderFn func(config *SshRuleConfig) *tailcfg.SSHAction

ActionBuilderFn is a callback function to delegate the task of building tailcfg.SSHAction to the caller

type Alias

type Alias string

Alias represents the value used in src, dest or target fields in ACL. Its usage and meaning is dependent on the context and the machine it is being applied to.

func (Alias) ApplyDst

func (alias Alias) ApplyDst(acl *ACL, m Machine) []string

ApplyDst applies this alias following the rules for 'destination' matching.

func (Alias) ApplySrc

func (alias Alias) ApplySrc(acl *ACL, m Machine, user User) []string

ApplySrc applies this alias following the rules for 'source' matching.

func (Alias) IsAutogroup

func (alias Alias) IsAutogroup() bool

func (Alias) IsGroup

func (alias Alias) IsGroup() bool

func (Alias) IsTag

func (alias Alias) IsTag() bool

func (Alias) IsUser

func (alias Alias) IsUser() bool

func (Alias) IsWildcard

func (alias Alias) IsWildcard() bool

func (Alias) String

func (alias Alias) String() string

type Machine

type Machine interface {
	// HostName returns the machine's host name value
	HostName() string

	// Tags return a list of tags associated with the machine
	Tags() []string

	// User returns the user object who owns this machine
	User() User

	// AllowedIPs return all IPs that this node is authorized to send packets from (used by router nodes)
	AllowedIPs() []netip.Prefix

	// IP returns the v4 and v6 IP addresses assigned to the machine
	IP() (v4, v6 netip.Addr)
}

Machine represents a node / machine in the Tailnet

type PortRange

type PortRange string

PortRange represents a single, multiple or a range of ports

func (PortRange) Parse

func (pr PortRange) Parse() ([]tailcfg.PortRange, error)

Parse parses the port-range specification into []tailcfg.PortRange

see: https://tailscale.com/kb/1337/acl-syntax#dst

func (PortRange) String

func (pr PortRange) String() string

type Protocol

type Protocol string

Protocol is used to specify the protocol to which the rule applies. Without a protocol, the access rule applies to all TCP and UDP traffic.

func (Protocol) Value

func (p Protocol) Value() []int

type SshRuleConfig

type SshRuleConfig struct {
	Action      string                  // action defined on the ssh entry: one of 'check' or 'accept'
	Principals  []*tailcfg.SSHPrincipal // list of principals identified in the ssh entry
	Users       map[string]string       // map of ssh-users -> local-users defined in the ssh entry
	CheckPeriod string                  // time period for which to allow a connection before requiring a check.
}

SshRuleConfig is configuration passed to ActionBuilderFn and extracted from ACL.SSH

type User

type User interface {
	// LoginName returns the login identity of the user
	LoginName() string

	// Roles returns the assigned roles for the user.
	// At minimum, 'member' should be return (although it is assumed anyways)
	Roles() []string
}

User represents any login identity on the system